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 |).

    https://batch.geocoder.cit.api.here.com/6.2/jobs
    ?action=run
    &mailto={YOUR_EMAIL}
    &gen=8
    &header=true
    &indelim=%7C
    &outdelim=%7C
    &outcols=displayLatitude,displayLongitude,locationLabel,
      houseNumber,street,district,city,postalCode,
      county,state,country
    &outputCombined=false
    &app_code={YOUR_APP_CODE}
    &app_id={YOUR_APP_ID}

    Example input:

    recId|searchText|country
    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.

    https://batch.geocoder.cit.api.here.com/6.2/jobs
    ?action=run
    &mailto={YOUR_EMAIL}
    &gen=8
    &header=true
    &mode=retrieveAddresses
    &maxresults=1
    &indelim=%7C
    &outdelim=%7C
    &outcols=displayLatitude,displayLongitude,distance,locationLabel,
      houseNumber,street,district,city,postalCode,
      county,state,country
    &outputCombined=false
    &app_code={YOUR_APP_CODE}
    &app_id={YOUR_APP_ID}

    Example input:

    recId|prox
    0001|52.505308,13.327739,250
    0002|49.917257,8.486488,250
    0003|51.119593,7.399356,250
    0004|49.20012,8.12326,250
    0005|51.116845,7.397318,250
    0006|52.265938,7.976922,250
    0007|48.143131,10.829233,250
    0008|51.770237,7.442682,250
    0009|51.511877,7.461382,250
    0010|52.53,13.391389,250
  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="http://batch.geo.nlp.nokia.com/lbsp/Search-Batch/1">
      <Response>
        <MetaInfo>
          <RequestID>12331722725344</RequestID>
        </MetaInfo>
        <Status>accepted</Status>
        <TotalCount>0</TotalCount>
        <ValidCount>0</ValidCount> 
        <InvalidCount>0</InvalidCount> 
        <ProcessedCount>0</ProcessedCount> 
        <PendingCount>0</PendingCount> 
        <SuccessCount>0</SuccessCount> 
        <ErrorCount>0</ErrorCount> 
      </Response> 
    </ns2:SearchBatch>
  3. Optionally, check the job status with a GET request
    https://batch.geocoder.cit.api.here.com/6.2/jobs/{REQUEST_ID}
    ?action=status
    &app_code={YOUR_APP_CODE}
    &app_id={YOUR_APP_ID}
  4. Download a zip file containing the results from the following link:
    https://batch.geocoder.cit.api.here.com/6.2/jobs/{REQUEST_ID}/all
    ?app_code={YOUR_APP_CODE}
    &app_id={YOUR_APP_ID}

    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

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.