Geocode Dataflow Walkthrough

Note

Bing Maps Spatial Data Service Geocode Dataflow API retirement

Bing Maps Spatial Data Service Geocode Dataflow API is deprecated and will be retired. Free (Basic) account customers can continue to use Bing Maps Spatial Data Service Geocode Dataflow API until June 30th, 2025. Enterprise account customers can continue to use Bing Maps Spatial Data Service Geocode Dataflow API until June 30th, 2028. To avoid service disruptions, all implementations using Bing Maps Spatial Data Service Geocode Dataflow API will need to be updated to use Azure Maps Get Geocoding Batch or Azure Maps Get Reverse Geocoding Batch API by the retirement date that applies to your Bing Maps for Enterprise account type. Azure Maps Geocoding Batch API and Azure Maps Reverse Geocode Batch API will be updated to support a larger number of locations per batch soon. For detailed migration guidance, see Migrate Bing Maps Geocode Dataflow 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.

The following steps show how to use the Geocode Dataflow API and version 2.0 of the Geocode Dataflow data schema to geocode large sets of spatial data.

Uploading Your Spatial Data

Format the data

To create a job to geocode a set of spatial data using version 2.0 of the Geocode Dataflow schema, your input data must conform to the Data Schema v2.0 and be specified using XML format, or as text strings delimited by the comma, tab, or pipe (|) character.

The following is an XML example that contains data to geocode. You can find examples in other formats in Sample Input and Output v2.0.

<?xml version="1.0" encoding="utf-8"?>  
<GeocodeFeed xmlns="http://schemas.microsoft.com/search/local/2010/5/geocode" Version="2.0">  
  <GeocodeEntity Id="001" xmlns="http://schemas.microsoft.com/search/local/2010/5/geocode">  
    <GeocodeRequest Culture="en-US" IncludeNeighborhood="1">  
      <Address AddressLine="1 Microsoft Way" AdminDistrict="WA" Locality="Redmond" PostalCode="98052" />  
    </GeocodeRequest>  
  </GeocodeEntity>  
  <GeocodeEntity Id="002" xmlns="http://schemas.microsoft.com/search/local/2010/5/geocode">  
    <GeocodeRequest IncludeNeighborhood="1" MaxResults="2" Query="Kings Road">  
      <ConfidenceFilter MinimumConfidence="Medium"/>  
    </GeocodeRequest>  
  </GeocodeEntity>  
  <GeocodeEntity Id="003" xmlns="http://schemas.microsoft.com/search/local/2010/5/geocode">  
    <GeocodeRequest Culture="en-US" Query="Seattle Space Needle" IncludeNeighborhood="1" IncludeQueryParse="true" MaxResults="5" >  
    </GeocodeRequest>  
  </GeocodeEntity>  
    <GeocodeEntity Id="004" xmlns="http://schemas.microsoft.com/search/local/2010/5/geocode">  
      <GeocodeRequest Culture="en-US" Query="">  
        <Address AddressLine="" AdminDistrict="" />  
      </GeocodeRequest>  
    </GeocodeEntity>  
    <GeocodeEntity Id="005" xmlns="http://schemas.microsoft.com/search/local/2010/5/geocode">  
      <ReverseGeocodeRequest Culture="en-US" IncludeNeighborhood="1" MaxResults="5" IncludeEntityTypes="Neighborhood">  
        <Location Longitude="-122.11871" Latitude="47.673099"/>  
        <ConfidenceFilter MinimumConfidence="High"/>  
      </ReverseGeocodeRequest>  
    </GeocodeEntity>  
    <GeocodeEntity Id="006"  xmlns="http://schemas.microsoft.com/search/local/2010/5/geocode" >  
      <ReverseGeocodeRequest Culture="en-ca">  
        <Location Longitude="-113.403092450204" Latitude="53.4802172766598"/>  
      </ReverseGeocodeRequest>  
    </GeocodeEntity>  
    <GeocodeEntity Id="007"  xmlns="http://schemas.microsoft.com/search/local/2010/5/geocode" >  
      <ReverseGeocodeRequest IncludeNeighborhood="1" MaxResults="5" IncludeEntityTypes="Neighborhood,PopulatedPlace">  
        <Location Longitude="-122.12934" Latitude="47.64054"/>  
      </ReverseGeocodeRequest>  
    </GeocodeEntity>  
  </GeocodeFeed>  
  

Upload the data and create the geocode job

To geocode the data, upload the data and create a geocode job by using a REST URL and HTTP POST protocol. The following shows an example. For more information, see Create Job.

Note

Both HTTP and HTTPS protocols are supported. The HTTPS protocol is recommended for geocode jobs that require you to secure your information.

http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?description=Geocode%20Demo&input=xml&output=xml&key=YourBingMapsKey  

When you make this request, the response includes a DataflowJob resource. This resource contains a set Link elements that define URLs. When you initiate a job, the response you receive contains a URL that you can use to get job status. After the job has completed, additional URLs are provided to download the geocoded results. The following response includes a URL for getting status as described in the next section. For more information about the DataflowJob resource, see Response Data.

<Response xmlns:xsi="http://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 © 2010 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>  
        <DataflowJob>  
          <Id>e14b1d9bd65c4b9d99d267bbb8102ccf</Id>  
          <Link role="self">https://spatial.virtualearth.net/REST/v1/dataflows/geocode/e14b1d9bd65c4b9d99d267bbb8102ccf</Link>  
          <Description>Geocode Demo</Description>  
          <Status>Pending</Status>  
          <CreatedDate>2010-03-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>  

Checking Job Status

To find out the status of a geocode job, use the URL provided by Link element with the role attribute set to self. You must append the Bing Maps Key that you used to create the job to the URL to use it. For more information, see Get Job Status.

Based on the example response above, you would make the following URL request to get job status. The job status is defined by the Status field. Continue to check status until it shows that the job has Completed. Then you can download the results as described in the next section.

https://spatial.virtualearth.net/REST/v1/dataflows/geocode/e14b1d9bd65c4b9d99d267bbb8102ccf?key=YourBingMapsKey  

<Response xmlns:xsi="http://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 © 2010 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/geocode/e14b1d9bd65c4b9d99d267bbb8102ccf</Link>  
          <Link role="output" name="succeeded">https://spatial.virtualearth.net/REST/v1/dataflows/geocode/e14b1d9bd65c4b9d99d267bbb8102ccf/output/succeeded</Link>  
          <Link role="output" name="failed">https://spatial.virtualearth.net/REST/v1/dataflows/geocode/e14b1d9bd65c4b9d99d267bbb8102ccf/output/failed</Link>  
          <Description>Geocode Job 1</Description>  
          <Status>Completed</Status>  
          <CreatedDate>2010-03-08T16:35:00.2429749-08:00</CreatedDate>  
          <CompletedDate>2010-03-08T16:44:00.9349209-08:00</CompletedDate>  
          <TotalEntityCount>6</TotalEntityCount>  
          <ProcessedEntityCount>6</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.

Downloading Results

When the status of your job is Completed, you can download the results of the geocode job. The results are available for download for fourteen (14) calendar days. The Link URLs to use are identified by their name attribute and are set to succeeded and failed. A succeeded or failed Link URL only appears in the response if there is corresponding data to download. For example, if all the data was geocoded successfully, a failed Link URL does not appear. To download data, you must append the Bing Maps Key that you used to create the job to the download URLs.

The following show the download URLs and the geocoded data for this example.

URL (name=succeeded)

https://spatial.virtualearth.net/REST/v1/dataflows/geocode/e14b1d9bd65c4b9d99d267bbb8102ccf/output/succeeded?key={BingMapsKey}  

Successful Geocode Results

<?xml version="1.0" encoding="utf-8"?>  
<GeocodeFeed Version="2.0" xmlns="http://schemas.microsoft.com/search/local/2010/5/geocode" >  
  <GeocodeEntity Id="010">  
    <ReverseGeocodeRequest Culture="en-US" IncludeEntityTypes="Neighborhood" IncludeNeighborhood="true" MaxResults="5">  
      <Location Latitude="47.673099" Longitude="-122.11871" />  
      <ConfidenceFilter MinimumConfidence="High" />  
    </ReverseGeocodeRequest>  
    <GeocodeResponse Name="Anderson Park, WA" EntityType="Neighborhood" Confidence="High" MatchCodes="Ambiguous, Good">  
      <Address AdminDistrict="WA" CountryRegion="United States" AdminDistrict2="King Co." FormattedAddress="Anderson Park, WA" Locality="Redmond" Neighborhood="Anderson Park" />  
      <GeocodePoint CalculationMethod="Rooftop" Latitude="47.6732406616211" Longitude="-122.118690490723" Type="Point" UsageTypes="Display" />  
      <BoundingBox SouthLatitude="47.6442702786285" WestLongitude="-122.176023680315" NorthLatitude="47.7022110446136" EastLongitude="-122.061357301131" />  
      <Point Latitude="47.6732406616211" Longitude="-122.118690490723" />  
    </GeocodeResponse>  
    <StatusCode>Success</StatusCode>  
    <TraceId>f2deda5c9fd04e41a3ead1907bcdd7d9</TraceId>  
  </GeocodeEntity>  
  <GeocodeEntity Id="001">  
    <GeocodeRequest Culture="en-US" IncludeNeighborhood="true">  
      <Address AddressLine="1 Microsoft Way" AdminDistrict="WA" Locality="Redmond" PostalCode="98052" />  
    </GeocodeRequest>  
    <GeocodeResponse Name="1 Microsoft Way, Redmond, WA 98052" EntityType="Address" Confidence="High" MatchCodes="Good">  
      <Address AddressLine="1 Microsoft Way" AdminDistrict="WA" CountryRegion="United States" AdminDistrict2="King Co." FormattedAddress="1 Microsoft Way, Redmond, WA 98052" Locality="Redmond" PostalCode="98052" />  
      <GeocodePoint CalculationMethod="InterpolationOffset" Latitude="47.6401305198669" Longitude="-122.129731848836" Type="Point" UsageTypes="Display" />  
      <GeocodePoint CalculationMethod="Interpolation" Latitude="47.6401546597481" Longitude="-122.129788175225" Type="Point" UsageTypes="Route" />  
      <BoundingBox SouthLatitude="47.6362678022963" WestLongitude="-122.137375102026" NorthLatitude="47.6439932374376" EastLongitude="-122.122088595645" />  
      <Point Latitude="47.6401305198669" Longitude="-122.129731848836" />  
    </GeocodeResponse>  
    <StatusCode>Success</StatusCode>  
    <TraceId>73ed21b4a4734676a3ae2d5d63e5b974</TraceId>  
  </GeocodeEntity>  
  <GeocodeEntity Id="002">  
    <GeocodeRequest IncludeNeighborhood="true" MaxResults="2" Query="Kings Road">  
      <ConfidenceFilter MinimumConfidence="Medium" />  
    </GeocodeRequest>  
    <GeocodeResponse Name="Kings Road Park, ID" EntityType="Park" Confidence="High" MatchCodes="Good">  
      <Address AdminDistrict="ID" CountryRegion="United States" AdminDistrict2="Canyon Co." FormattedAddress="Kings Road Park, ID" Locality="Nampa" Landmark="Kings Road Park" />  
      <GeocodePoint CalculationMethod="Rooftop" Latitude="43.5681953430176" Longitude="-116.528587341309" Type="Point" UsageTypes="Display" />  
      <BoundingBox SouthLatitude="43.5670738220215" WestLongitude="-116.530143737793" NorthLatitude="43.5693168640137" EastLongitude="-116.527038574219" />  
      <Point Latitude="43.5681953430176" Longitude="-116.528587341309" />  
    </GeocodeResponse>  
    <GeocodeResponse Name="Kings Park, Australia" EntityType="Park" Confidence="High" MatchCodes="Good">  
      <Address AdminDistrict="QLD" CountryRegion="Australia" FormattedAddress="Kings Park, Australia" Locality="Brisbane" Landmark="Kings Park" />  
      <GeocodePoint CalculationMethod="Rooftop" Latitude="-27.4164142608643" Longitude="152.942535400391" Type="Point" UsageTypes="Display" />  
      <BoundingBox SouthLatitude="-27.417537689209" WestLongitude="152.941268920898" NorthLatitude="-27.4152927398682" EastLongitude="152.943786621094" />  
      <Point Latitude="-27.4164142608643" Longitude="152.942535400391" />  
    </GeocodeResponse>  
    <StatusCode>Success</StatusCode>  
    <TraceId>4888f2dacb964c7ab381456d172281f5</TraceId>  
  </GeocodeEntity>  
  <GeocodeEntity Id="003">  
    <GeocodeRequest Culture="en-US" IncludeNeighborhood="true" MaxResults="5" Query="Seattle Space Needle" IncludeQueryParse="true" />  
    <GeocodeResponse Name="Space Needle, WA" EntityType="LandmarkBuilding" Confidence="High" MatchCodes="Good">  
      <Address AdminDistrict="WA" CountryRegion="United States" AdminDistrict2="King Co." FormattedAddress="Space Needle, WA" Locality="Seattle" Landmark="Space Needle" />  
      <GeocodePoint CalculationMethod="Rooftop" Latitude="47.619930267334" Longitude="-122.348670959473" Type="Point" UsageTypes="Display" />  
      <QueryParseValue Property="Locality" Value="Seattle" />  
      <QueryParseValue Property="Landmark" Value="Space Needle" />  
      <BoundingBox SouthLatitude="47.6193733215332" WestLongitude="-122.350967407227" NorthLatitude="47.6216163635254" EastLongitude="-122.347640991211" />  
      <Point Latitude="47.619930267334" Longitude="-122.348670959473" />  
    </GeocodeResponse>  
    <StatusCode>Success</StatusCode>  
    <TraceId>858ecbd4dd06407ea1fd55b3e482f317</TraceId>  
  </GeocodeEntity>  
  <GeocodeEntity Id="006">  
    <ReverseGeocodeRequest Culture="en-ca">  
      <Location Latitude="53.4802172766598" Longitude="-113.403092450204" />  
    </ReverseGeocodeRequest>  
    <GeocodeResponse Name="448 Kirkpatrick Cres NW, Edmonton, AB T6L, Canada" EntityType="Address" Confidence="Medium" MatchCodes="Good">  
      <Address AddressLine="448 Kirkpatrick Cres NW" AdminDistrict="AB" CountryRegion="Canada" AdminDistrict2="Alberta" FormattedAddress="448 Kirkpatrick Cres NW, Edmonton, AB T6L, Canada" Locality="Edmonton" PostalCode="T6L" />  
      <GeocodePoint CalculationMethod="Interpolation" Latitude="53.4802203" Longitude="-113.4031111" Type="Point" UsageTypes="Display, Route" />  
      <BoundingBox SouthLatitude="53.4790962" WestLongitude="-113.4050001" NorthLatitude="53.4813445" EastLongitude="-113.4012221" />  
      <Point Latitude="53.4802203" Longitude="-113.4031111" />  
    </GeocodeResponse>  
    <StatusCode>Success</StatusCode>  
    <TraceId>94e6029cf3a5422496033678cbb7862b</TraceId>  
  </GeocodeEntity>  
  <GeocodeEntity Id="007">  
    <ReverseGeocodeRequest IncludeEntityTypes="Neighborhood,PopulatedPlace" IncludeNeighborhood="true" MaxResults="5">  
      <Location Latitude="47.64054" Longitude="-122.12934" />  
    </ReverseGeocodeRequest>  
    <GeocodeResponse Name="Redmond, WA" EntityType="PopulatedPlace" Confidence="High" MatchCodes="Good">  
      <Address AdminDistrict="WA" CountryRegion="United States" AdminDistrict2="King Co." FormattedAddress="Redmond, WA" Locality="Redmond" />  
      <GeocodePoint CalculationMethod="Rooftop" Latitude="47.6785583496094" Longitude="-122.130989074707" Type="Point" UsageTypes="Display" />  
      <BoundingBox SouthLatitude="47.6257362365723" WestLongitude="-122.245330810547" NorthLatitude="47.7296524047852" EastLongitude="-121.995613098145" />  
      <Point Latitude="47.6785583496094" Longitude="-122.130989074707" />  
    </GeocodeResponse>  
    <StatusCode>Success</StatusCode>  
    <TraceId>3f8922f29c474bf19e372b7cab716ef9</TraceId>  
  </GeocodeEntity>  
</GeocodeFeed>  

URL (name=failed)

https://spatial.virtualearth.net/REST/v1/dataflows/geocode/e14b1d9bd65c4b9d99d267bbb8102ccf/output/failed?key={BingMapsKey}  

Failed Geocode Results

<?xml version="1.0" encoding="utf-8"?>  
<GeocodeFeed Version="2.0" xmlns="http://schemas.microsoft.com/search/local/2010/5/geocode" >  
  <GeocodeEntity Id="004">  
    <GeocodeRequest Culture="en-US">  
      <Address />  
    </GeocodeRequest>  
    <StatusCode>BadRequest</StatusCode>  
    <FaultReason>To geocode a location, you must specify at least one address field.</FaultReason>  
    <TraceId>2f2a8ea2402842198b6d9d6a62b03eeb</TraceId>  
  </GeocodeEntity>  
</GeocodeFeed>