Get Status of a Geocode Job

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