Download Geocode Job Results

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 URLs to download results from a Geocode Job are provided when your job has completed and you request job status. When your job has completed, the Status field in the job status response is set to Completed and the URLs to use to download processed data are defined in the response as XML Link values, or as part of a JSON links collection. You can distinguish these link elements in the response because they have the attribute role set to output. These link elements also specify the name attribute and set it to succeeded or failed to identify a download URL for data that was processed successfully or for data that encountered errors during processing. A link does not appear if there is no data to download. Therefore, if all your data was processed successfully, a link with the name attribute and set it to failed will not appear in the response. The following are examples of these link elements.

XML

<Link role="output" name="succeeded">https://spatial.virtualearth.net/REST/v1/dataflows/Geocode/5bf10c37df944083b1879fbb0556e67e/output/succeeded</Link>  
<Link role="output" name="failed">https://spatial.virtualearth.net/REST/v1/dataflows/Geocode/5bf10c37df944083b1879fbb0556e67e/output/failed</Link>  
  

JSON

"links":[  
      {  
         "name":"succeeded",  
         "role":"output",  
         "url":"https:\/\/spatial.virtualearth.net\/REST\/v1\/dataflows\/Geocode\/5bf10c37df944083b1879fbb0556e67e\/output\/succeeded"  
      },  
      {  
         "name":"failed",  
         "role":"output",  
         "url":"https:\/\/spatial.virtualearth.net\/REST\/v1\/dataflows\/Geocode\/5bf10c37df944083b1879fbb0556e67e\/output\/failed"  
      }  
]  
  

To use these URLs, you must add the Bing Maps Key parameter that you used to create the job. For example, to download the data that was processed successfully in the above example, you would add the parameter key MyDataflowJobKey where MyDataflowJobKey is the Bing Maps Key that you used to create the job.

https://spatial.virtualearth.net/REST/v1/dataflows/Geocode/5bf10c37df944083b1879fbb0556e67e/output/succeeded?key=MyDataflowJobKey  

For information about the Geocode Dataflow data schema, see Data Schema v2.0.

Sample Code

The following code shows how to download the results of a geocode job. The geocoded results are saved in text files. This code is part of a complete Geocode Dataflow code sample. To view the complete code sample, see Sample Code. You may also want to read the Walkthrough to get a step-by-step description of how to use the Geocode Dataflow. The walkthrough includes example URLs and HTTP responses.

//Downloads job results to files names Success.txt (successfully geocoded results) and   
//   Failed.txt (info about spatial data that was not geocoded successfully).  
//Parameters:   
//   statusDetails: Inclues job status and the URLs to use to download all geocoded results.  
//   key: The Bing Maps Key for this job. The same key is used to create the job and get job status.     
  
static void DownloadResults(DownloadDetails statusDetails, string key)  
{  
    //Write the results for data that was geocoded successfully to a file named Success.xml  
    if (statusDetails.suceededlink != null && !statusDetails.suceededlink.Equals(String.Empty))  
    {  
        //Create a request to download successfully geocoded data. You must add the Bing Maps Key to the   
        //  download location URL provided in the response to the job status request.  
        UriBuilder successUriBuilder = new UriBuilder(statusDetails.suceededlink + @"?key=" + key);  
        HttpWebRequest request1 = (HttpWebRequest)WebRequest.Create(successUriBuilder.Uri);  
  
        request1.Method = "GET";  
  
        using (HttpWebResponse response = (HttpWebResponse)request1.GetResponse())  
        {  
            if (response.StatusCode != HttpStatusCode.OK)  
                throw new Exception ("An HTTP error status code was encountered when downloading results.");  
  
            using (Stream receiveStream = response.GetResponseStream())  
            {  
                StreamWriter successfile = new StreamWriter("Success.txt");  
                using (StreamReader r = new StreamReader(receiveStream))  
                {  
                    string line;  
                    while ((line = r.ReadLine()) != null)  
                    {  
                        successfile.Write(line);  
                    }  
                }  
                successfile.Close();  
            }  
  
        }  
    }  
  
    //If some spatial data could not be geocoded, write the error information to a file called Failed.xml  
    if (statusDetails.failedlink != null && !statusDetails.failedlink.Equals(String.Empty))  
    {  
        //Create an HTTP request to download error information. You must add the Bing Maps Key to the   
        //  download location URL provided in the response to the job status request.  
        UriBuilder failedUriBuilder = new UriBuilder(statusDetails.failedlink + @"?key=" + key);  
        HttpWebRequest request2 = (HttpWebRequest)WebRequest.Create(failedUriBuilder.Uri);  
  
        request2.Method = "GET";  
  
        using (HttpWebResponse response = (HttpWebResponse)request2.GetResponse())  
        {  
            if (response.StatusCode != HttpStatusCode.OK)  
                throw new Exception ("An HTTP error status code was encountered when downloading results.");  
  
            using (Stream receiveStream = response.GetResponseStream())  
            {  
                StreamWriter failedfile = new StreamWriter("Failed.txt");  
                using (StreamReader r = new StreamReader(receiveStream))  
                {  
                    string line;  
                    while ((line = r.ReadLine()) != null)  
                    {  
                        failedfile.Write(line);  
                        }  
                }  
                failedfile.Close();  
            }  
  
        }  
    }  
}