Partager via

Create a Geocode Job and Upload Data

  • Article

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 upload a set of spatial data and to create a job to geocode and reverse-geocode the data.

Supported HTTP Methods

POST

URL template

Important

This template supports both HTTP and HTTPS protocols. URLs in the response use HTTPS protocol.

A job is created when you geocode entity data. Before using this API, review the job limits in Geocode and Data Source Limits.

Upload locations and points and create a geocode job.

The data that you upload can contain both data to geocode and data to reverse geocode. The geocode process detects the type of data for each entry and performs the appropriate action.

http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?input=input&output=output&dataLocation=dataLocation&key={BingMapsKey}

Template Parameters

Note

Parameter names and values are not case-sensitive except for the key parameter value.

Parameter Alias Description Values
dataLocation Optional. Specifies the location of the data to download. Note: You must set the dataLocation parameter to the location of the data or include the data to process in the HTTP request. If you do both, the URL returns an error. A Windows Azure™ Blob Service REST API location that contains the data to process. The data must be in XML format. The Blob Service REST API uses the following URL formats:

http://account-name.blob.core.windows.net/myDataFile

https://account-name.blob.core.windows.net/myDataFile

For more information, see Addressing Blob Service Requests.

Before you make your request to start the dataflow job, make sure that the Blob Service URL is available publicly or shared with a signature key. If the URL is shared with a signature key, it must be encoded. For more information, see Managing Access to Containers and Blobs.

The following content types are supported for data that is retrieved from an HTTP server.

- application/xml
- text/xml
- text/plain
- application/octet-stream [for compressed data]

Example: dataLocation=http://myServer.myDomain.com/spatialDataSource
input Required. The format of the input data file. One of the following values:

- xml
- csv
- tab
- pipe

For more information about input files for a Geocode Dataflow, see Data Schema v2.0.

Example: input=csv
key Required. A Bing Maps Key to use for the geocode job. A Bing Maps Key obtained from the Bing Maps Account Center.
output o Optional. The output format for the response. One of the following values:

- json [default]
- xml

Example: output=xml

Input

This URL supports the following input formats. For examples, see Sample Input and Output v2.0.

When you create the HTTP request to upload data and create a geocode job, you must post the input data in the body of the request or set the dataLocation parameter to a URL where your data can be retrieved. You must also set the content type in the request to one of the following values, depending on the format of the input data.

  • XML (application/xml)

  • Comma-delimited values (text/plain)

  • Tab-delimited values (text/plain)

  • Pipe-delimited values (text/plain)

  • Binary (application/octet-stream) [Specify this format when you upload compressed data from a Blob Service REST API location using the dataLocation parameter.]

Examples

This example creates a geocode job for spatial data that is provided in an xml format.

http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?input=xml&key={BingMapsKey}

Response

The response to this URL contains a representation of the geocode dataflow job instance.

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 create a job to geocode spatial data. The data you want to geocode is uploaded as part of the job creation process. 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.

//Creates a geocode dataflow job and uploads spatial data to process.  
//Parameters:   
//   dataFilePath: The path to the file that contains the spatial data to geocode.  
//   dataFormat: The format of the input data. Possible values are xml, csv, tab and pipe.  
//   key: The Bing Maps Key to use for this job. The same key is used to get job status and download results.  
//   description: Text that is used to describe the geocode dataflow job.   
//Return value : A URL that defines the location of the geocode dataflow job that was created.  
static string CreateJob(string dataFilePath, string dataFormat, string key, string description)  
{  
    //Define parameters for the HTTP request  
    //  
    // The 'Content-Type' header of the HTTP Request must be "text/plain" or "application/xml"  
    // depending on the input data format.  
    //  
    string contentType = "text/plain";  
    if (dataFormat.Equals("xml", StringComparison.OrdinalIgnoreCase))  
        contentType = "application/xml";  
  
    StringBuilder queryStringBuilder = new StringBuilder();  
  
    //  
    // The 'input'(input format) and 'key' (Bing Maps Key) parameters are required.  
    //  
    queryStringBuilder.Append("input=").Append(Uri.EscapeUriString(dataFormat));  
    queryStringBuilder.Append("&");  
    queryStringBuilder.Append("key=").Append(Uri.EscapeUriString(key));  
  
    if (!String.IsNullOrEmpty(description))  
    {  
        //  
        // The 'description' parameter is optional.  
        //  
        queryStringBuilder.Append("&");  
  
    }  
  
    //Build the HTTP URI that will upload and create the geocode dataflow job  
    UriBuilder uriBuilder = new UriBuilder("http://spatial.virtualearth.net");  
    uriBuilder.Path = "/REST/v1/dataflows/geocode";  
    uriBuilder.Query = queryStringBuilder.ToString();  
  
    //Include the data to geocode in the HTTP request  
    using (FileStream dataStream = File.OpenRead(dataFilePath))  
    {  
        HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uriBuilder.Uri);  
  
        //  
        // The HTTP method must be 'POST'.  
        //  
        request.Method = "POST";  
        request.ContentType = contentType;  
  
        using (Stream requestStream = request.GetRequestStream())  
        {  
            byte[] buffer = new byte[16384];  
            int bytesRead = dataStream.Read(buffer, 0, buffer.Length);  
            while (bytesRead > 0)  
            {  
                requestStream.Write(buffer, 0, bytesRead);  
  
                bytesRead = dataStream.Read(buffer, 0, buffer.Length);  
            }  
        }  
  
        //Submit the HTTP request and check if the job was created successfully.   
        using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())  
        {  
            //  
            // If the job was created successfully, the status code should be  
            // 201 (Created) and the 'Location' header should contain a URL  
            // that defines the location of the new dataflow job. You use this   
            // URL with the Bing Maps Key to query the status of your job.  
            //  
            if (response.StatusCode != HttpStatusCode.Created)  
                throw new Exception ("An HTTP error status code was encountered when creating the geocode job.");  
  
            string dataflowJobLocation = response.GetResponseHeader("Location");  
            if (String.IsNullOrEmpty(dataflowJobLocation))  
                throw new Exception ("The 'Location' header is missing from the HTTP response when creating a goecode job.");  
  
            return dataflowJobLocation;  
        }  
    }  
}

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.

  • 201

When the request is not successful, the response returns one of the following errors.

  • 400

  • 500

  • 503

    Note

    The response may contain a 503 HTTP status error code when the number of pending geocode dataflow jobs is exceeded. The maximum number of pending geocode dataflow jobs that can be associated with a Bing Maps Key is 10.