Get Status of a Geocode Job
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.
Use the following URL to get the status of a geocode job.
Supported HTTP Methods
GET
URL template
Note
This template supports both HTTP and HTTPS protocols. URLs in the response use HTTPS protocol.
Get status information for a geocode job.
The Bing Maps Key that you specify must be the same Bing Maps Key that you used to create the job. A URL in the following format without the Bing Maps Key is provided in the response to the URL request that you made to Create Job. The URL is specified in a link field with an attribute of self. For more information, see Response Data.
http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode/jobID?output=output&key={BingMapsKey}
Template Parameters
Note
Parameter names and values are not case-sensitive except for the key parameter value.
| Parameter | Alias | Description | Values |
|---|---|---|---|
| jobID | Required. The ID of the job. | When you request a dataflow job, the job ID is returned in the ID field of the response. For more information, see Response Data. Example: e14b1d9bd65c4b9d99d267bbb8102ccf |
|
| key | Required. The Bing Maps Key that you used to create the geocode job. | A Bing Maps Key from the Bing Maps Account Center. Example: key=abc123def456ghi789abc123def456ghi789 |
|
| output | o | Optional. The output format for the response. | One of the following values: - json [default] - xml Example: o=xml |
Examples
This example requests resource information for the job with an ID of e14b1d9bd65c4b9d99d267bbb8102ccf that was created by using the Bing Maps Key b1c323ea234b1c323ea234b1c323ea234.
http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode/e14b1d9bd65c4b9d99d267bbb8102ccf?key=b1c323ea234b1c323ea234b1c323ea234
Response
This URL supports the following response formats.
JSON: application/json
XML: application/xml
For information about the response, see Response Data.
Sample Code
The following code shows how to get the status of a geocode job. 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.
class DownloadDetails
{
public string jobStatus { get; set; }
public string suceededlink { get; set; }
public string failedlink { get; set; }
}
//Checks the status of a dataflow job and defines the URLs to use to download results when the job is completed.
//Parameters:
// dataflowJobLocation: The URL to use to check status for a job.
// key: The Bing Maps Key for this job. The same key is used to create the job and download results.
//Return value: A DownloadDetails object that contains the status of the geocode dataflow job (Completed, Pending, Aborted).
// When the status is set to Completed, DownloadDetails also contains the links to download the results
static DownloadDetails CheckStatus(string dataflowJobLocation, string key)
{
DownloadDetails statusDetails = new DownloadDetails();
statusDetails.jobStatus = "Pending";
//Build the HTTP Request to get job status
UriBuilder uriBuilder = new UriBuilder(dataflowJobLocation + @"?key=" + key + "&output=xml");
HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uriBuilder.Uri);
request.Method = "GET";
//Submit the request and read the response to get job status and to retrieve the links for
// downloading the job results
//Note: The following conditional statements make use of the fact that the 'Status' field will
// always appear after the 'Link' fields in the HTTP response.
using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
{
if (response.StatusCode != HttpStatusCode.OK)
throw new Exception ("An HTTP error status code was encountered when checking job status.");
using (Stream receiveStream = response.GetResponseStream())
{
XmlTextReader reader = new XmlTextReader(receiveStream);
while (reader.Read())
{
if (reader.IsStartElement())
{
if (reader.Name.Equals("Status"))
{
//return job status
statusDetails.jobStatus = reader.ReadString();
return (statusDetails);
}
else if (reader.Name.Equals("Link"))
{
//Set the URL location values for retrieving
// successful and failed job results
reader.MoveToFirstAttribute();
if (reader.Value.Equals("output"))
{
reader.MoveToNextAttribute();
if (reader.Value.Equals("succeeded"))
{
statusDetails.suceededlink = reader.ReadString();
}
else if (reader.Value.Equals("failed"))
{
statusDetails.failedlink = reader.ReadString();
}
}
}
}
}
}
}
return (statusDetails);
}
HTTP Status Codes
Note
For more details about these HTTP status codes, see Status Codes and Error Handling.
When the request is successful, the following HTTP status code is returned.
- 200
When the request is not successful, the response returns one of the following HTTP status codes.
400
500
503