Create a Geocode Job and Upload Data

Article
06/14/2022

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