Download Data Source Walkthrough

Article
05/22/2024

Note

Bing Maps Spatial Data Service Data Source Management API retirement

Bing Maps Spatial Data Service Data Source Management API is deprecated and will be retired. Free (Basic) account customers can continue to use Bing Maps Data Source Management API until June 30th, 2025. Enterprise account customers can continue to use Bing Maps Data Source Management API until June 30th, 2028. To avoid service disruptions, all implementations using Bing Maps Spatial Data Service Data Source Management API will need to be updated to use an alternative, such as an Azure-based solution, by the retirement date that applies to your Bing Maps for Enterprise account type. For detailed migration guidance, see Migrate Bing Maps Data Source Management and Query API.

Azure Maps is Microsoft's next-generation maps and geospatial services for developers. Azure Maps has many of the same features as Bing Maps for Enterprise, and more. To get started with Azure Maps, create a free Azure subscription and an Azure Maps account. For more information about azure Maps, see Azure Maps Documentation. For migration guidance, see Bing Maps Migration Overview.

Use the DataSourceDownload API to download entity data for a published data source.

Note

Both HTTP and HTTPS protocols are supported.

Create the Download Data Source Job

To start the download process, create a DataSourceDownload URL request using the following format.

https://spatial.virtualearth.net/REST/v1/Dataflows/DataSourceDownload/accessId/DataSourceName?output=xml&key=DataSourceMasterKey

When you make the download request, the response provides the ID and status of the download job, and a status URL. The status URL is specified in the Link element with the role attribute set to self. The Link and status URL fields are highlighted in the following response example.

Note that the job status is set to Pending. Job status values include Pending, Completed and Aborted. The next section describes how to use the status URL to monitor job status and to get the location of the downloaded entity data.

<Response xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">  
  <Copyright>Copyright © 2011 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the  
 content and any results may not be used, reproduced or transmitted in any manner without express written permission  
 from Microsoft Corporation.</Copyright>  
  <BrandLogoUri>http://spatial.virtualearth.net/Branding/logo_powered_by.png</BrandLogoUri>  
  <StatusCode>201</StatusCode>  
  <StatusDescription>Created</StatusDescription>  
  <AuthenticationResultCode>ValidCredentials</AuthenticationResultCode>  
  <TraceId>b1aae77f9b9145ffa87d97d7d405cffd</TraceId>  
  <ResourceSets>  
    <ResourceSet>  
      <EstimatedTotal>1</EstimatedTotal>  
      <Resources>  
        <DownloadJob>  
          <Id>e14b1d9bd65c4b9d99d267bbb8102ccf</Id>  
          <Link role="self">https://spatial.virtualearth.net/REST/v1/dataflows/DataSourceDownload/DataSourceName</Link>  
          <Description></Description>  
          <Status>Pending</Status>  
          <CreatedDate>2011-11-09T15:15:51.8326153-08:00</CreatedDate>  
          <CompletedDate xsi:nil="true" />  
          <TotalEntityCount>0</TotalEntityCount>  
          <ProcessedEntityCount>0</ProcessedEntityCount>  
          <FailedEntityCount>0</FailedEntityCount>  
        </DataflowJob>  
      </Resources>  
    </ResourceSet>  
  </ResourceSets>  
</Response>

Check Job Status

To monitor the status of your download job, use the status URL described in the previous section with your data source master key.

https://spatial.virtualearth.net/REST/v1/dataflows/DataSourceDownload/DataSourceName?output=xml&key=DataSourceMasterKey

When the status is set to Completed, a download URL appears in the response. The download URL is specified as a Link field with the role attribute set to output and the name attribute set to succeeded.

The following response shows that the job is completed and specifies a download URL. These fields are highlighted. The next section describes the download data and how to access it.

<Response xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">  
  <Copyright>Copyright © 2011 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the   
content and any results may not be used, reproduced or transmitted in any manner without express written permission   
from Microsoft Corporation.</Copyright>  
  <BrandLogoUri>http://spatial.virtualearth.net/Branding/logo_powered_by.png</BrandLogoUri>  
  <StatusCode>200</StatusCode>  
  <StatusDescription>OK</StatusDescription>  
  <AuthenticationResultCode>ValidCredentials</AuthenticationResultCode>  
  <TraceId>2a4fcb1fd1274497ab8ed84955012264</TraceId>  
  <ResourceSets>  
    <ResourceSet>  
      <EstimatedTotal>1</EstimatedTotal>  
      <Resources>  
        <DataflowJob>  
          <Id>e14b1d9bd65c4b9d99d267bbb8102ccf</Id>  
          <Link role="self">https://spatial.virtualearth.net/REST/v1/dataflows/DataSourceDownload/DataSourceName</Link>  
          <Link role="output" name="succeeded">https://spatial.virtualearth.net/REST/v1/dataflows/DataSourceDownload/DataSourceName/output/succeeded</Link>  
          <Description></Description>  
          <Status>Completed</Status>  
          <CreatedDate>2011-11-08T16:35:00.2429749-08:00</CreatedDate>  
          <CompletedDate>2011-11-08T16:44:00.9349209-08:00</CompletedDate>  
          <TotalEntityCount>2</TotalEntityCount>  
          <ProcessedEntityCount>0</ProcessedEntityCount>  
          <FailedEntityCount>0</FailedEntityCount>  
        </DataflowJob>  
      </Resources>  
    </ResourceSet>  
  </ResourceSets>  
</Response>

If your job status is Aborted, then the job ended due to an error and an ErrorMessage element appears in the response and contains error information.

Get the downloaded data

To access the downloaded entity data, use the download URL described in the previous section with the data source master key.

https://spatial.virtualearth.net/REST/v1/dataflows/DataSourceDownload/DataSourceName/output/succeeded?key=DataSourceMasterKey

The downloaded data includes the data schema and a set of entity data that matches that schema in XML format. XML is the only option for downloaded entity data.

The following sample data is an example of downloaded entity data.

<?xml version="1.0" encoding="UTF-8" ?>  
<MainRoot>  
  <xs:schema xmlns="" xmlns:xs="https://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" id="DataSourceName">  
    <xs:element name="DataSourceName" msdata:IsDataSet="true" msdata:UseCurrentLocale="true">  
      <xs:complexType>  
        <xs:choice minOccurs="0" maxOccurs="unbounded">  
          <xs:element name="MyDataSourceEntityType">  
            <xs:complexType>  
              <xs:sequence>  
                <xs:element name="EntityID" type="xs:string" minOccurs="0"/>  
                <xs:element name="Latitude" type="xs:double" minOccurs="0"/>  
                <xs:element name="Longitude" type="xs:double" minOccurs="0"/>  
                <xs:element name="AddressLine" type="xs:string" minOccurs="0"/>  
                <xs:element name="Locality" type="xs:string" minOccurs="0"/>  
                <xs:element name="AdminDistrict" type="xs:string" minOccurs="0"/>  
                <xs:element name="CountryRegion" type="xs:string" minOccurs="0"/>  
                <xs:element name="PostalCode" type="xs:string" minOccurs="0"/>  
                <xs:element name="Confidence" type="xs:string" minOccurs="0"/>  
                <xs:element name="Phone" type="xs:string" minOccurs="0"/>  
                <xs:element name="Open" type="xs:long" minOccurs="0"/>  
                <xs:element name="Close" type="xs:long" minOccurs="0"/>  
                <xs:element name="IsWheelchairAccessible" type="xs:boolean" minOccurs="0" />  
              </xs:sequence>  
            </xs:complexType>  
          </xs:element>  
        </xs:choice>  
      </xs:complexType>  
      <xs:unique name="Constraint1" msdata:PrimaryKey="true">  
        <xs:selector xpath=".//MyDataSourceEntityType"/>  
        <xs:field xpath="EntityID"/>  
      </xs:unique>  
    </xs:element>  
  </xs:schema>  
  <MyDataSourceEntityType>  
    <EntityID>1</EntityID>  
    <Latitude>47.673302</Latitude>  
    <Longitude>-122.118576</Longitude>  
    <AddressLine>1 Microsoft Way</AddressLine>  
    <Locality>Redmond</Locality>  
    <AdminDistrict>WA</AdminDistrict>  
    <CountryRegion>United States</CountryRegion>  
    <PostalCode>98052</PostalCode>  
    <Confidence>High</Confidence>  
    <Phone>303-555-0188</Phone>  
    <Open>700</Open>  
    <Close>1800</Close>  
    <IsWheelchairAccessible>true</IsWheelchairAccessible>  
  </MyDataSourceEntityType>  
  <MyDataSourceEntityType>  
    <EntityID>2</EntityID>  
    <Latitude>34.023614</Latitude>  
    <Longitude>-118.28398</Longitude>  
    <AddressLine>W Jefferson Blvd</AddressLine>  
    <Locality>Los Angeles</Locality>  
    <AdminDistrict>CA</AdminDistrict>  
    <CountryRegion>United States</CountryRegion>  
    <PostalCode>90007</PostalCode>  
    <Confidence>Medium</Confidence>  
    <Phone>303-555-0188</Phone>  
    <Open>700</Open>  
    <Close>1800</Close>  
    <IsWheelchairAccessible>false</IsWheelchairAccessible>  
  </MyDataSourceEntityType>  
</MainRoot>

Share via

Download Data Source Walkthrough

Create the Download Data Source Job

Check Job Status

Get the downloaded data

Additional resources