Export (0) Print
Expand All

Create a Geocode Job and Upload Data

Bing

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

Ff701737.Important(en-us,MSDN.10).gifImportant:
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

Ff701737.note(en-us,MSDN.10).gifNote:
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.

Ff701737.note(en-us,MSDN.10).gifNote:
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 Geocode Dataflow Data Schema - Version 2.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 Geocode Dataflow Sample Input and Output Data Version 2.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

This example creates a geocode job for spatial data that is provided in an xml format and assigns a description “My dataflow” to the job.

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 Geocode Dataflow Response Description.

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 Geocode Dataflow Sample Code. You may also want to read the Geocode Dataflow 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

Ff701737.note(en-us,MSDN.10).gifNote:
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

    Ff701737.note(en-us,MSDN.10).gifNote:
    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.

Show:
© 2014 Microsoft