Batch Geocoder APIdocumentation.developer.here.com/pdf/batch_geocoding_nlp...Batch Geocoder API is a...

Batch Geocoder APIDeveloper's Guide

Version 6.2.35.2

Batch Geocoder API Developer's Guide 2► Contents

Contents

Legal Notices..........................................................................................................................................................3

Document Information.................................................................................................................................... 4

Chapter 1: Overview................................................................................................................................. 5What is the Batch Geocoder API?...............................................................................................................6

Why use the Batch Geocoder API?.............................................................................................................6

Chapter 2: Quick Start........................................................................................................................... 7Batch Geocoder Example..............................................................................................................................8

Chapter 3: User Guide......................................................................................................................... 11Acquiring Credentials...................................................................................................................................12

Constructing a Request.............................................................................................................................. 12

Customer Integration Testing...................................................................................................................12

Input Data...................................................................................................................................................... 13

Output Data...................................................................................................................................................16

Cancelling a Job............................................................................................................................................21

Removing a Job............................................................................................................................................ 22

Tools................................................................................................................................................................ 22

Service Support............................................................................................................................................ 23

Chapter 4: API Reference................................................................................................................. 24API Endpoints................................................................................................................................................ 25

Request Parameters.................................................................................................................................... 26

Job Status...................................................................................................................................................... 28

Error Messages............................................................................................................................................. 34

Batch Geocoder API Developer's Guide 3► Legal Notices

Legal Notices© 2015 HERE. All rights reserved.

This material, including documentation and any related computer programs, is protected by

copyright controlled by HERE. All rights are reserved. Copying, including reproducing, storing,

adapting or translating, any or all of this material requires the prior written consent of HERE. This

material also contains confidential information, which may not be disclosed to others without the

prior written consent of HERE.

Trademark Acknowledgements

HERE and Nokia are trademarks or registered trademarks of Nokia Corporation in the United States

and other countries.

Other trade names are trademarks or registered trademarks of their owners.

Disclaimer

This content is provided "as-is" and without warranties of any kind, either express or implied,

including, but not limited to, the implied warranties of merchantability, fitness for a particular

purpose, satisfactory quality and non-infringement. Nokia does not warrant that the content is error

free and Nokia does not warrant or make any representations regarding the quality, correctness,

accuracy, or reliability of the content. You should therefore verify any information contained in the

content before acting on it.

To the furthest extent permitted by law, under no circumstances, including without limitation Nokia's

negligence, shall Nokia be liable for any damages, including, without limitation, direct, special,

indirect, punitive, consequential, exemplary and/ or incidental damages that result from the use or

application of this content, even if Nokia or an authorized representative has been advised of the

possibility of such damages.

Batch Geocoder API Developer's Guide 4► Document Information

Document Information

Product

Name: Batch Geocoder API

Version: Version 6.2.35.2

Document

Name: Batch Geocoder API Developer's Guide

Id: 2a9711c-1430923818

Status: FINAL

Date: 2015-May-06, 14:51 (GMT)

Batch Geocoder API Developer's Guide 5► Overview

Chapter

1

OverviewTopics:

• What is the Batch Geocoder API?

• Why use the Batch Geocoder API?

This section introduces the Batch Geocoder API and describes its

common use cases.

Batch Geocoder API Developer's Guide 6► Overview

What is the Batch Geocoder API?Batch Geocoder API is a web service that allows users to geocode large data sets (hundreds of

thousands). Users upload a single input file, the service processes the data asynchronously and

returns a single file with the results.

Why use the Batch Geocoder API?Use the Batch Geocoder API to geocode large data sets in one batch. Upload addresses or geographic

coordinates that you have in a text file and download the complete results in one file when the

job is done. The Batch Geocoder API saves you from sending individual service requests to the

service address by address. And since the result is also in text form (delimited file format) your client

application does not need to parse XML or JSON.

Jobs are processed asynchronously. Clients can either wait for an email notification or poll the status

of the job and download the result when the job is completed.

For geocoding the input can be qualified addresses (structured input) or free-form search strings,

both containing complete or partial address information. For reverse geocoding the input is

geographic coordinates and an optional radius. The result per input is either a single record exactly

matching the input or a sequence of records ranked by relevance when the input is ambiguous. In this

respect the Batch Geocoder API works just in the same way as the transactional Geocoder API.

The service is for forward and reverse geocoding. Landmark geocoding is not available for batch at

this time.

Batch Geocoder API Developer's Guide 7► Quick Start

Chapter

2

Quick StartTopics:

• Batch Geocoder Example

This article describes the simplest scenario using the Batch

Geocoder API and illustrates it with a working example.

Note that the example uses demo credentials. These are suitable

for testing, but must be replaced with application-specific

credentials in your own applications. Please see also Acquiring

Credentials on page 12.


Batch Geocoder ExamplePerforming 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. You can use the demo credentials in the

examples for testing, but must substitute them with your own unique values in your website or

application. See Acquiring Credentials on page 12 for more information.

Note: When using a command line utility such as cURL or wget, remember to set the headerbefore 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.

http://batch.geocoder.cit.api.here.com/6.2/jobs?action=run&mailto=<my_email>&gen=7&header=true&indelim=|&outdelim=|&outcols=displayLatitude,displayLongitude,locationLabel, houseNumber,street,district,city,postalCode, county,state,country&outputCombined=false&app_code=AJKnXv84fjrb0KIHawS0Tg&app_id=DemoAppId01082013GAL

Example input:

recId|searchText|country0001|Invalidenstraße 116 10115 Berlin|DEU0002|Am Kronberger Hang 8 65824 Schwalbach|DEU0003|425 W Randolph St Chicago IL 60606|USA0004|One Main Street Cambridge MA 02142|USA0005|200 S Mathilda Ave Sunnyvale CA 94086|USA

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

http://batch.geocoder.cit.api.here.com/6.2/jobs


?action=run&mailto=<my_email>&gen=7&header=true&mode=retrieveAddresses&maxresults=1&indelim=|&outdelim=|&outcols=displayLatitude,displayLongitude,distance,locationLabel, houseNumber,street,district,city,postalCode, county,state,country&outputCombined=false&app_code=AJKnXv84fjrb0KIHawS0Tg&app_id=DemoAppId01082013GAL

Example input:

recId|prox0001|52.505308,13.327739,2500002|49.917257,8.486488,2500003|51.119593,7.399356,2500004|49.20012,8.12326,2500005|51.116845,7.397318,2500006|52.265938,7.976922,2500007|48.143131,10.829233,2500008|51.770237,7.442682,2500009|51.511877,7.461382,2500010|52.53,13.391389,250

2. The result of the jobs request contains a RequestID. Use this RequestID to identify this job infuture 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

http://batch.geocoder.cit.api.here.com/6.2/jobs/<RequestID>?action=status&app_code=AJKnXv84fjrb0KIHawS0Tg&app_id=DemoAppId01082013GAL

4. Download a zip file containing the results from the following link:

http://batch.geocoder.cit.api.here.com/6.2/jobs/<RequestID>/all?app_code=AJKnXv84fjrb0KIHawS0Tg&app_id=DemoAppId01082013GAL

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/<RequestID>/result

jobs/<RequestID>/errors

jobs/<RequestID>/no-matches

Batch Geocoder API Developer's Guide 11► User Guide

Chapter

3

User GuideTopics:

• Acquiring Credentials

• Constructing a Request

• Customer Integration Testing

• Input Data

• Output Data

• Cancelling a Job

• Removing a Job

• Tools

• Service Support

The articles in this part of the guide explain essential concepts and

show how to use the Batch Geocoder API.

The text is accompanied by examples that show the API in

operation. Note that where credentials are required, the examples

use demo ones. These are acceptable for testing purposes, but

must be replaced by application-specific credentials in real-life

applications (please see also Acquiring Credentials on page 12).


Acquiring CredentialsAll users of HERE APIs must obtain authentication and authorization credentials and provide them as

values for the parameters app_id and app_code. The credentials are assigned per application.

To obtain the credentials for an application, please visit http://developer.here.com/get-started for

more details.

Constructing a RequestA request to the Batch Geocoder API includes the basic elements shown in the following table and, in

addition, it may contain resource-specific parameters.

Table 1: Basic request elements

Element Value/Example Description

Base URL http://batch.geocoder.api.here.com

http://batch.geocoder.cit.api.here.com

Production environment only

CIT environment: see Customer

Integration Testing on page 12

Path /6.2/

Resource /jobs An endpoint from API Endpoints on

page 25

Application Code &app_code=AJKnXv84fjrb0KIHawS0Tg Substitute your own unique

app_code

Application Id &app_id=DemoAppId01082013GAL Substitute your own unique app_id

Customer Integration TestingHERE is committed to maintain the best possible production service for all customers. Given that the

production environment is live and common to all API users, we request that you use the alternative

Customer Integration Testing (CIT) environment when evaluating our products, running tests, making

changes in your code and altering the way you access our APIs.

The CIT environment also allows you to test your software against a newer version of the service

before HERE brings that version into production. CIT offers a fully functional environment for

http://developer.here.com/get-started


customers to use for development and testing, but it does not support high loads or performance

testing in general.

Note that the same application id can be used in both environments, but CIT may require a dedicated

application code. If this is the case, please contact us as described under Service Support on page

23.

The CIT environment is not intended for general production use.

Input DataInput data consists of the addresses to be geocoded. Your input must abide by the following

limitations:

• The number of lines to geocode is limited to 1,000,000 (excluding the header)

• The maximum request size is limited to 2GB uncompressed

If the request exceeds these limitations, the request returns an error and the addresses are not

processed.

You must provide the input data in a delimited file format. The field delimiter can be any of the

following characters:

• | (pipe)

• ; (semicolon)

• : (colon)

• , (comma)

• \t (tab)

Just as with Geocoder API, the address data can be structured (qualified) or unstructured (freeform).

The following is an example of an input file with the address as freeform with a country code qualifier

using "|" as a delimiter.

recId|searchText|country 1|425 W Randolph St, Chicago Illinois 60606|USA 2|31 St James Ave Boston MA 02116|USA 3|10115 Berlin Invalidenstrasse 117|DEU

The following is an example of the same addresses in fully qualified form:

recId|street|city|postalCode|country 1|425 Randolph St|Chicago||USA 2|31 St James Ave|Boston|02116|USA 3|Invalidenstrasse 117|Berlin|10115|DEU


The column recId is optional. If provided, it is repeated in the output for reference. If you have an

occurrence of the delimiter character in the data, you must enclose the data in double quotes. Below

an example where the delimiter is a comma and the input contains commas.

recId,searchText,country 1,"Sturmstraße 8, 80687 München", DEU 2,"Milano", ITA 3,"Rom", ITA 4,"Tecklenburger Straße, Westerkappeln 49492", DEU 5,"425 W Randolph St Chicago, Illinois, 60606", USA

Basic Input Fields

Input field names are not case sensitive. When no record ID is supplied (field name recId), then

the BGC will generate one as a sequence from 1 to numLines. Record IDs may be of any form and

may contain numbers and/or strings. They even may consist of several words. The result will be

alphabetically sorted by recId.

Table 2: General

recId identifies input address in the response

Table 3: Address, freeform

searchText single line query string, may be enclosed in

double quotes

Table 4: Address, qualified

street

houseNumber

district

city

postalCode

county

state

country


Table 5: Geographic coordinates, reverse geocoding

mode One of three values:

retrieveAddresses - Search for the

closest street address or addresses

retrieveAreas - Retrieve the

administrative area information for the

position provided in the request

trackPosition - Retrieve street

information based on a position and bearing

pos pos=lat,lon,bearing

Use with mode=trackPosition

A position with latitude, longitude, and bearing.

Bearing expresses the direction in which an asset

is heading in degrees starting at true north and

continuing clockwise around the compass. North

is 0 degrees, east is 90 degrees, south is 180

degrees, west is 270 degrees.

prox prox=lat,lon,radius

Use with mode=retrieveAddresses and

retrieveAreas

A type of SpatialFilter. A spatial filter limits the

search for any other attributes on the request.

Proximity specifies a circle to search using a

latitude, a longitude, and a radius in meters.

Table 6: Miscellaneous

locationattributes query parameter needed for requesting special

output fields, e.g. mapReferenceID and

mapReferenceMapVersion are activated using

the value mr for locationattributes

addressattributes query parameter to request special address

attributes


responseattributes query parameter to request special response

attributes

mapview map view to be used for geocoding

countryfocus country focus to be used for geocoding

bbox bounding box filter to be used for geocoding

prox proximity filter to be used for geocoding

locationid location id of the requested object

additionaldata additional query paramters to be used for

geocoding

gen generation parameter to be used for geocoding

For the detailed description of these parameters, please consult the Geocoder API Developer's

Guide.

Output DataThe output data follows the format that was specified when starting the job. The first three columns

are fixed and are always:

• recId

• seqNumber

• seqLength

recId is the same id you provided in the input. seqNumber and seqLength are used to number

ambiguous results for an input address. For the input "425 Randolph St" two results exist: E and W

Randolph St. The seqLength is the number of records returned, which is 2 in this case, and both

results are sorted by seqNumber. There is no guarantee that the result is sorted by recId and

seqNumber.

In the example below the complete output for the example input data in Input Data on page 13 can

be found:

recId|seqNumber|seqLength|displayLatitude|displayLongitude |houseNumber|street|city|postalCode|country|1|1|2|41.8838692|-87.6389008|425|W Randolph St|Chicago|60606|USA1|2|2|41.8842278|-87.6169052|425|E Randolph St|Chicago|60601|USA2|1|1|42.3508682|-71.0714874|31|Saint James Ave|Boston|02116|USA


3|1|1|52.5304108|13.3852701|117|Invalidenstraße|Berlin|10115|DEU

Basic Output Fields

Table 7: General

recId Identifies your input address in the response

seqNumber Numbers consecutively the different results for

the corresponding input record starting with 1

seqLength Number of results for the corresponding input

record

Table 8: Geographical Location

displayLatitude Latitude of display position

displayLongitude Longitude of display position

navigationLatitude (same as latitude) Latitude of navigation position

navigationLongitude (same as longitude) Longitude of navigation position

mapViewBottomRightLatitude Latitude of mapview's bottom right corner

mapViewBottomRightLongitude Longitude of mapview's bottom right corner

mapViewTopLeftLatitude (same as

latitude)

Latitude of mapview's top left corner

mapViewTopLeftLongitude (same as

longitude)

Longitude of mapview's top left corner

Table 9: Address

street Refers to the street name.

houseNumber House number. Depending on regional

characteristics, can also be house name. For API

implementations which do not support separate

street and house number fields, this field can be

omitted.

building Building Name


district Includes the subdivision level below the city. Use

of this field is optional if a second subdivision

level is not available.

city Refers to the locality of the address.

postalCode Postal code

county Includes the second subdivision level(s) below the

country. Use of this field is optional if a second

subdivision level is not available.

state Includes the first subdivision level(s) below the

country. Where commonly used, this is a state

code (i.e., CA for Califonia).

country ISO 3166-alpha-3 country code

addressLines

addressAdditionalData Example:

CountryName=Vereinigte Staaten; StateName=Illinois

Table 10: Formatted Localized Address

locationLabel Assembled address value for displaying

purposes.

Table 11: Address Match Information

relevance Indicates the relevance of the results found;

the higher the score the more relevant the

alternative. The score is a normalized value

between 0 and 1.

matchType Quality of the location match.

pointAddress: Location matches exactly as

point address.

interpolated: Location was interpolated.


matchCode Code indicating how well the result matches

the request. Enumeration [exact, ambiguous,

upHierarchy, ambiguousUpHierarchy].

matchLevel The most detailed address field that matched

the input record

matchQualityStreet

matchQualityHouseNumber

matchQualityBuilding

matchQualityDistrict

matchQualityCity

matchQualityPostalCode

matchQualityCounty

matchQualityState

matchQualityCountry

MatchQuality provides detailed information

about the match quality of a result at attribute

level. Match quality is a value between 0.0 and

1.0. 1.0 represents a 100% match.

Table 12: Map Reference

mapReferenceId

mapReferenceMapVersion

mapReferenceSideOfStreet

mapReferenceSpot

mapReferenceCountryId

mapReferenceStateId

mapReferenceCountyId

mapReferenceCityId

mapReferenceDistrictId

Note: Requires to add

locationattributes= (one of mr,

mapReference, all) to the request or

to add locationattributes column

with value mr, mapReference, or all to

the input

Table 13: Address Details

addressDetailsCountryCode

addressDetailsCountry


locationattributes= (one of dt,


addressDetailsCountryLanguage

addressDetailsState

addressDetailsStateLanguage

addressDetailsCounty

addressDetailsCountyLanguage

addressDetailsCity

addressDetailsCityLanguage

addressDetailsDistrict

addressDetailsDistrictLanguage

addressDetailsStreet

addressDetailsStreetLanguage

addressDetailsHouseNumber

addressDetailsHouseNumberLanguage

addressDetailsPostalCode

addressDetailsBuilding

addressDetailsBuildingLanguage

addressDetails, all) to the request

or to add locationattributes column

with value dt, addressDetails, or all

to the input

Table 14: Street Details

addressDetailsStreetDetailsBaseName

addressDetailsStreetDetailsPrefix

addressDetailsStreetDetailsSuffix

addressDetailsStreetDetailsDirection

addressDetailsStreetDetailsStreetType

addressDetailsStreetDetailsStreetTypeBefore

addressDetailsStreetDetailsStreetTypeAttached


locationattributes=

(one of sd, streetDetails,

all) to the request or to

add locationattributes

column with value sd,

streetDetails, or all to

the input


Table 15: Miscellaneous

locationType Indicates whether the location is an [area, point,

line].

locationId A key uniquely identifying a physical location.

responseAdditionalData Additional Information about the result, e.g. wrt.

housenumber fallbacks:

houseNumberFallbackDifference=1; houseNumberFallback=true

Table 16: Parsed Request Information

parsedRequestName

parsedRequestLabel

parsedRequestCountry

parsedRequestState

parsedRequestStreet

parsedRequestCounty

parsedRequestCity

parsedRequestDistrict

parsedRequestHouseNumber

parsedRequestPostalCode

parsedRequestBuilding

parsedRequestAddressLines

parsedRequestAdditionalData

parsedRequestPosition

Cancelling a JobTo cancel a job use the cancel action with an HTTP PUT. This requires the <RequestID>.

http://batch.geocoder.cit.api.here.com/6.2/jobs/<RequestID>


?action=cancel&app_code=AJKnXv84fjrb0KIHawS0Tg&app_id=DemoAppId01082013GAL

Removing a JobAfter you have downloaded the results you can delete the job using HTTP DELETE. This requires the

<RequestID>. This removes the input, the results and also the status from the server.

http://batch.geocoder.cit.api.here.com/6.2/jobs/<RequestID>?app_code=AJKnXv84fjrb0KIHawS0Tg&app_id=DemoAppId01082013GAL

Note: Jobs are automatically removed from the server 30 days after they are processed.

ToolsWhen submitting a job using “wget” and “cURL”, check field names (e.g., &outCols=recId,…) and

field delimiter in the request for both the input and the output. wget and cURL will return a “400 Bad

Request” response in case there is a mistype or when the delimiter does not match the delimiter

in the input file. Both wget and cURL need a content type to be specified in the header. Uploading

compressed address data is currently not supported.

wget

For wget use the header

Content-Type: text/plain

Example:

wget --header="Content-Type: text/plain; charset=UTF-8" --post-file=addresses.txt "http://batch.geocoder.cit.api.here.com/6.2/jobs? &app_code=AJKnXv84fjrb0KIHawS0Tg &app_id=DemoAppId01082013GAL &action=run &header=true &inDelim=; &outDelim=, &outCols=recId,latitude,longitude,locationLabel &mailto=<my_email> &outputcombined=true


&language=de-DE"

cURL

If you use cURL, be sure to add the following header

Content-Type: text/plain

and submit the payload using the --data-binary parameter.

Example:

curl -X POST -H "Content-Type: text/plain" --data-binary @addresses.txt "http://batch.geocoder.cit.api.here.com/6.2/jobs? &app_code=AJKnXv84fjrb0KIHawS0Tg &app_id=DemoAppId01082013GAL &action=run &header=true &inDelim=; &outDelim=, &outCols=recId,latitude,longitude,locationLabel &mailto=<my_email> &outputcombined=true &language=de-DE"

Service SupportIf you need assistance with this or other HERE products, please contact your HERE representative or

Technical Customer Support.

Batch Geocoder API Developer's Guide 24► API Reference

Chapter

4

API ReferenceTopics:

• API Endpoints

• Request Parameters

• Job Status

• Error Messages

This part of the guide provides a comprehensive reference to

Batch Geocoder API.


API EndpointsTable 17: Batch Geocoder Request Endpoints

URL Request Description HTTP Method

jobs

<The HTTP Body of the request contains the data to

be geocoded.>

• Creates a batch job

• Returns a RequestID

POST

jobs/<RequestID>?action=run&params=... Starts the batch job with the given parameters. PUT

jobs?action=run&params=...

<The HTTP Body of the request contains the data to

be geocoded.>

• Creates a batch job

• Starts the job

• Returns a RequestID

(shortcut for jobs and jobs/...?

action=run)

POST

jobs/<RequestID>?action=cancel Cancels the batch job. PUT

jobs/<RequestID>?action=status Returns the status for the batch job . GET

jobs/<RequestID> Deletes the batch job.

Note that the difference between this request

and others is the HTTP type, which is DELETE.

You do not use an action to delete a job.

DELETE

jobs/<RequestID>/result Starts a download of all files.

The result file contains all geocoded results. If

"OutputCombined" is specified, this will also

contain "no-matches". Errors are not included.

GET

jobs/<RequestID>/errors Starts a download of the error file.

The errors file contains all invalid lines from

the input data.

GET

jobs/<RequestID>/no-matches Download all results that the geocoder could

not match to an address ("no-match")

Downloads the no-matches file only.

GET

jobs/<RequestID>/all Downloads all available files in one zip file

Downloads all the files:

• result,

• errors (optional)

GET


URL Request Description HTTP Method

• invalid

• report

Request ParametersTable 18: Request Parameters for Job Submission

Parameter Type Description

indelim Char Field delimeter in the input data.

mailto String, Required Email address where completion notification is sent.

The email address provided is only used to submit the notification.

outdelim Char, Required Field delimeter in the output data.

outcols Enumeration, Required List of columns to return in the output.

outputcombined Boolean, Required If true, sucessful and unsucessful addresses are combined into a

single result_YYYYMMDD-HH-MM__out.txt file, if false they are

returned in two separate files

result_YYYYMMDD-HH-MM__out.txt

result_YYYYMMDD-HH-MM__err.txt

action String Type of request, one of

run run a previously uploaded job

status inquire about job <RequestID>

cancel cancel job <RequestID>

header Boolean If true, a header row is included before the results in the output.

maxresults Integer Limits the number of items in the response. Default value is 10.

minresults Integer Ignore the specified radius until minResults results are found.

Default is 0. Currently only supported for Reverse Geocode

mode=retrieveAreas.

The following parameters can be used to define default parameters for each Geocoding request in

the input.


Table 19: Request Parameters for Geocoding


locationattributes Enumeration Query parameter to request special location attributes. For details, see

Customizing the Response with Attribute Switches in the Geocoder API

Developer's Guide.

addressattributes Enumeration Query parameter to request special address attributes. For details, see

Customizing the Response with Attribute Switches in the Geocoder API

Developer's Guide.

responseattributes Enumeration Query parameter to request special response attributes. For details,

see Customizing the Response with Attribute Switches in the Geocoder

API Developer's Guide.

mapview GeoBoundingBoxType Map view to be used for geocoding

countryfocus String Country focus to be used for geocoding

bbox GeoBoundingBoxType Bounding box filter to be used for geocoding

prox GeoProximityType Proximity filter to be used for geocoding

locationid String Location id of the requested object

gen Integer Generation parameter to be used for geocoding

additionaldata Enumeration List of KeyValuePairType elements as a generic container for attaching

additional information to the request. See details in the Additional Data

Parameter chapter in the Geocoder API Developer's Guide.

language Enumeration The preferred languages, in descending order, in which

internationalized text attributes should be returned. RFC 4647

standard.

level String Target match level of the search result. One of [country, state,

county, city, district, postalCode]. Only valid in combination

with gen=2 or higher.

sortby String Sort results by distance (default), population count, or size

(approximate area size). One of [distance, population,

size]. Currently only supported for Reverse Geocode

mode=retrieveAreas.

politicalview String xs:string (3 bytes, ISO 3166-1-alpha-3)

Specify the political view. Available territories will be seen through

the point of view of this country. If this parameter is not specified the

neutral international view is made available, where territories may have

unresolved claims.

The following views are supported:

• ARG: Argentina

• GUF: French Guyana



• GUY: Guyana

• IND: India

• PAK: Pakistan

• SUR: Suriname

• VNM: Vietnam

Note: These parameters will be taken as default parameters for the geocoding query. Defaultvalues can be overridden by non-empty input cells in the input line. E.g. a request sent withlanguage=en-US will add the language parameter with values en-US to each Geocoderrequest, unless the input data contains a column language with a non-empty string value.In this case the parameter's value is taken from the input line. Note that a value with one ormore spaces is not an empty string value.

Note: For the detailed description of these parameters' usage, please consult the GeocoderAPI Developer's Guide.

Table 20: Request Parameters for Result Retrieval


outputcompressed Boolean If true (the default) the result files available at

jobs/<RequestID>/result

jobs/<RequestID>/errors

jobs/<RequestID>/no-matches

are compressed in a zip file.

If false the above endpoints will return uncompressed text files (HTTP

Content-Type text/plain)

Job StatusAfter a job has been submitted the job status can be checked with a GET request and parameter

action=status. The job status can be one of: submitted, accepted, running, completed,

cancelled, deleted, or failed.

Job submitted and accepted

Status = accepted.

All counts are still 0.


A job can also be submitted via POST (upload of the input data) without starting it right away.

To do this do not specify the parameter action=run. The status in this case is submitted. Start

the job later with a PUT request and action=run.

Job started running

Status = running.

JobStatus shows start time.

Counts may show 0 at first but will show counts as soon as first records are processed.


Job is still running

Status = running.

JobStatus shows start time.

Counts now reflect job progress.


Job is running and nearly done

Status = running.

Counts show all records have been processed, i.e. total count = processed count.

Results are being sorted and results ZIP file is being created.

Job is completed

Status = completed.

JobFinished shows time when job has completed.

Counts show stats for job.

Files of job are ready for download.


Job is cancelled

Status = cancelled.

Job was cancelled by user with HTTP PUT command action=cancel.

Counts show stats for job at time of cancellation. Job results are not available for download.


Job is deleted

Status = deleted.

Job was deleted by user with HTTP DELETE command.

Counts show stats for job at time of deletion. Job results are not available for download anymore.

Files are removed from the Geocoder’s systems. Note: Jobs are automatically removed from the

server 30 days after they are processed.


Job failed

Status = failed.

Job failed while running. This is unusual and caused by an internal error. You can try to restart the job

with a PUT request and action=run or delete the job.

Error MessagesErrors in this table are ordered alphabetically by error text.

Table 21: Error messages

Error text Description

Email address is missing Supply an email address for notification.

Expected Format Data must be in the correct format.


Error text Description

Input delimiter is missing Supply input delimiter of the input address file.

Invalid input data Request parameters are incorrectly formatted.

Invalid output column The column requested is invalid.

Output columns are missing Supply valid output columns.

Output combined in missing User needs to supply a value for OutputCombined parameter.

Output delimiter is missing Supply output delimiter of the result files.

Permanently Prohibited User needs to supply correct authentication key in token parameter.

Request Id is missing No request id was submitted in the request.

Request Id: {1234567} Input file is

missing

The input address file is missing. Possible reasons: The file was not uploaded or

was removed for archive purposes.

Request Id:{1234567} is invalid The request id could not be found. Possible reasons: An input file was not

uploaded or directory was removed for archive purposes.

There was an error in processing your

file

The requested file was unavailable. Possible error in processing or removed for

archive purposes.

There was an error locating your file The requested file was unavailable. Possible error in processing or removed for

archive purposes.

Unable to determine search type based

upon input columns

Based upon the input columns submitted, the type of service could not be

determined.

Unable to read input file to determine

input columns

No column names were included in the header of the input address file.

Date post:	14-Jul-2020
Category:	Documents
Upload:	others
View:	10 times
Download:	0 times

Batch Geocoder APIdocumentation.developer.here.com/pdf/batch_geocoding_nlp...Batch Geocoder API is a...

Documents