Upload
others
View
29
Download
0
Embed Size (px)
Citation preview
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 API Developer's Guide 8► Quick Start
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
Batch Geocoder API Developer's Guide 9► Quick Start
?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>
Batch Geocoder API Developer's Guide 10► Quick Start
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).
Batch Geocoder API Developer's Guide 12► User Guide
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
Batch Geocoder API Developer's Guide 13► User Guide
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
Batch Geocoder API Developer's Guide 14► User Guide
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
Batch Geocoder API Developer's Guide 15► User Guide
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
Batch Geocoder API Developer's Guide 16► User Guide
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
Batch Geocoder API Developer's Guide 17► User Guide
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
Batch Geocoder API Developer's Guide 18► User Guide
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.
Batch Geocoder API Developer's Guide 19► User Guide
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
Note: Requires to add
locationattributes= (one of dt,
Batch Geocoder API Developer's Guide 20► User Guide
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
Note: Requires to add
locationattributes=
(one of sd, streetDetails,
all) to the request or to
add locationattributes
column with value sd,
streetDetails, or all to
the input
Batch Geocoder API Developer's Guide 21► User Guide
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>
Batch Geocoder API Developer's Guide 22► User Guide
?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
Batch Geocoder API Developer's Guide 23► User Guide
&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.
Batch Geocoder API Developer's Guide 25► API Reference
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¶ms=... Starts the batch job with the given parameters. PUT
jobs?action=run¶ms=...
<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
Batch Geocoder API Developer's Guide 26► API Reference
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.
Batch Geocoder API Developer's Guide 27► API Reference
Table 19: Request Parameters for Geocoding
Parameter Type Description
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
Batch Geocoder API Developer's Guide 28► API Reference
Parameter Type Description
• 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
Parameter Type Description
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.
Batch Geocoder API Developer's Guide 29► API Reference
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.
Batch Geocoder API Developer's Guide 30► API Reference
Job is still running
Status = running.
JobStatus shows start time.
Counts now reflect job progress.
Batch Geocoder API Developer's Guide 31► API Reference
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.
Batch Geocoder API Developer's Guide 32► API Reference
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.
Batch Geocoder API Developer's Guide 33► API Reference
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.
Batch Geocoder API Developer's Guide 34► API Reference
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.
Batch Geocoder API Developer's Guide 35► API Reference
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.