Batch Geocoder API Developer's Guide

Batch Geocoder Example

Performing batch geocoding on a data set means to run a series of commands:

  1. Upload the data to the Batch Geocoder and start the processing job
  2. Download the results when processing is done

After you have submitted the job and downloaded the results, you can optionally delete the job.

app_id and app_code are authentication credentials. This document uses {YOUR_APP_CODE} and {YOUR_APP_ID} as placeholders for access and authorization credentials. Please replace these placeholders with your own unique application-specific credentials to access the API resources. For more information about the access and authorization credentials credentials, see Acquiring Credentials.

Note: When using a command line utility such as cURL or wget, remember to set the header before specifying the body of the request.
  1. Start a new batch geocoding job and upload the data to be geocoded by submitting an HTTP POST request with action=run and attaching the input data to the body. Set the HTTP header Content-Type to text/plain. The following is an example for geocoding addresses, i.e. forward geocoding. The examples use the | (pipe) delimiter for input and output columns in URL encoded form (%7C for |).

    Example input:

    0001|Invalidenstra├če 116 10115 Berlin|DEU
    0002|Am Kronberger Hang 8 65824 Schwalbach|DEU
    0003|425 W Randolph St Chicago IL 60606|USA
    0004|One Main Street Cambridge MA 02142|USA
    0005|200 S Mathilda Ave Sunnyvale CA 94086|USA

    If you want to reverse geocode from a set of geographic coordinates, see the following example.

    Example input:

  2. The result of the jobs request contains a RequestID. Use this RequestID to identify this job in future actions you want to perform on it.

    Example response:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
    <ns2:SearchBatch xmlns:ns2="">
  3. Optionally, check the job status with a GET request{REQUEST_ID}
  4. Download a zip file containing the results from the following link:{REQUEST_ID}/all

    The zip file contains the results and reports.

    • the geocoded addresses (result_YYYYMMDD-HH-MM__out.txt)
    • addresses that could not be matched (optional file) (result_YYYYMMDD-HH-MM__err.txt)
    • invalid input that could not be processed (result_YYYYMMDD-HH-MM__inv.txt)
    • a report file (result_YYYYMMDD-HH-MM__rpt.txt)

    where YYYYMMDD-HH-MM is the date and time when the job was processed.

Note: You can also access the results files individually at
  • jobs/{REQUEST_ID}/result
  • jobs/{REQUEST_ID}/errors
  • jobs/{REQUEST_ID}/no-matches