Batch Geocoder API. Developer's Guide. Version

Transcription

1 Batch Geocoder API Developer's Guide Version

2 Batch Geocoder API Developer's Guide 2 Contents Contents Legal Notices...3 Document Information... 4 Chapter 1: Overview... 5 What is the Batch Geocoder API?...6 Why use the Batch Geocoder API?...6 Chapter 2: Quick Start... 7 Batch Geocoder Example...8 Chapter 3: User Guide...11 Acquiring Credentials...12 Constructing a Request Customer Integration Testing...12 Input Data Output Data...16 Cancelling a Job...20 Removing a Job Tools Service Support Chapter 4: API Reference...23 API Endpoints Request Parameters Error Messages... 27

3 Batch Geocoder API Developer's Guide 3 Legal Notices Legal Notices 2014 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.

4 Batch Geocoder API Developer's Guide 4 Document Information Document Information Product Name: Batch Geocoder API Version: Version Document Name: Id: Status: Date: Batch Geocoder API Developer's Guide 53fa FINAL 2014-Nov-03, 14:30 (GMT)

5 Batch Geocoder API Developer's Guide 5 Overview Chapter 1 Overview Topics: 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.

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

7 Batch Geocoder API Developer's Guide 7 Quick Start Chapter 2 Quick Start Topics: 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.

8 Batch Geocoder API Developer's Guide 8 Quick Start 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. 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 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. &mailto=<my_ > &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=demoappid gal Example input: recid searchtext country 0001 Invalidenstraße Berlin DEU 0002 Am Kronberger Hang Schwalbach DEU W Randolph St Chicago IL USA 0004 One Main Street Cambridge MA USA S Mathilda Ave Sunnyvale CA USA If you want to reverse geocode from a set of geographic coordinates, see the following example.

9 Batch Geocoder API Developer's Guide 9 Quick Start?action=run &mailto=<my_ > &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=demoappid gal Example input: recid prox , , , , , , , , , , , , , , , , , , , , 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=" Search-Batch/1"> <Response> <MetaInfo> <RequestID> </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>

10 Batch Geocoder API Developer's Guide 10 Quick Start 3. Optionally, check the job status with a GET request &app_code=ajknxv84fjrb0kihaws0tg &app_id=demoappid gal 4. Download a zip file containing the results from the following link: &app_id=demoappid gal 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

11 Batch Geocoder API Developer's Guide 11 User Guide Chapter 3 User Guide Topics: 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).

12 Batch Geocoder API Developer's Guide 12 User Guide Acquiring Credentials All 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 for more details. Constructing a Request A 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 Production environment only CIT environment: see Customer Integration Testing on page 12 Path /6.2/ Resource /jobs An endpoint from API Endpoints on page 24 Application Code &app_code=ajknxv84fjrb0kihaws0tg Substitute your own unique app_code Application Id &app_id=demoappid gal Substitute your own unique app_id Customer Integration Testing HERE 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

13 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 22. The CIT environment is not intended for general production use. Input Data Input 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 W Randolph St, Chicago Illinois USA 2 31 St James Ave Boston MA USA Berlin Invalidenstrasse 117 DEU The following is an example of the same addresses in fully qualified form: recid street city postalcode country Randolph St Chicago USA 2 31 St James Ave Boston USA 3 Invalidenstrasse 117 Berlin DEU

14 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, 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

15 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 addressattributes query parameter needed for requesting special output fields, e.g. mapreferenceid and mapreferencemapversion are activated using the value mr for locationattributes query parameter to request special address attributes

16 Batch Geocoder API Developer's Guide 16 User Guide responseattributes mapview countryfocus bbox prox locationid additionaldata gen query parameter to request special response attributes map view to be used for geocoding country focus to be used for geocoding bounding box filter to be used for geocoding proximity filter to be used for geocoding location id of the requested object additional query paramters to be used for geocoding generation parameter to be used for geocoding For the detailed description of these parameters, please consult the Geocoder API Developer's Guide. Output Data The 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 W Randolph St Chicago USA E Randolph St Chicago USA Saint James Ave Boston USA

17 Batch Geocoder API Developer's Guide 17 User Guide Invalidenstraße Berlin DEU Basic Output Fields Table 7: General recid seqnumber seqlength Identifies your input address in the response Numbers consecutively the different results for the corresponding input record starting with 1 Number of results for the corresponding input record Table 8: Geographical Location displaylatitude displaylongitude navigationlatitude (same as latitude) navigationlongitude (same as longitude) mapviewbottomrightlatitude mapviewbottomrightlongitude mapviewtopleftlatitude (same as latitude) mapviewtopleftlongitude (same as longitude) Latitude of display position Longitude of display position Latitude of navigation position Longitude of navigation position Latitude of mapview's bottom right corner Longitude of mapview's bottom right corner Latitude of mapview's top left corner Longitude of mapview's top left corner Table 9: Address Details street housenumber building Refers to the street name. 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 Name

18 Batch Geocoder API Developer's Guide 18 User Guide district city postalcode county state country Includes the subdivision level below the city. Use of this field is optional if a second subdivision level is not available. Refers to the locality of the address. Postal code Includes the second subdivision level(s) below the country. Use of this field is optional if a second subdivision level is not available. Includes the first subdivision level(s) below the country. Where commonly used, this is a state code (i.e., CA for Califonia). ISO 3166-alpha-3 country code addresslines Table 10: Formatted Localized Address locationlabel Assembled address value for displaying purposes. Table 11: Address Match Information relevance matchtype 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. Quality of the location match. pointaddress: Location matches exactly as point address. interpolated: Location was interpolated. matchcode matchlevel Code indicating how well the result matches the request. Enumeration [exact, ambiguous, uphierarchy, ambiguousuphierarchy]. The most detailed address field that matched the input record

19 Batch Geocoder API Developer's Guide 19 User Guide matchqualitystreet matchqualityhousenumber matchqualitybuilding matchqualitydistrict MatchQuality provides detailed information about the match quality of a result at attribute level. Match quality is a value between 0.0 and represents a 100% match. matchqualitycity matchqualitypostalcode matchqualitycounty matchqualitystate matchqualitycountry Table 12: Misc locationtype locationid mapreferenceid mapreferencemapversion mapreferencesideofstreet Indicates whether the location is an [area, point, line]. A key uniquely identifying a physical location. Note: Requires to add locationattributes column with value mr to the input mapreferencespot mapreferencecountryid mapreferencestateid mapreferencecountyid mapreferencecityid mapreferencedistrictid addressadditionaldata Example: CountryName=Vereinigte Staaten; StateName=Illinois

20 Batch Geocoder API Developer's Guide 20 User Guide responseadditionaldata Additional Information about the result, e.g. wrt. housenumber fallbacks: housenumberfallbackdifference=1; housenumberfallback=true Table 13: Parsed Request Information parsedrequestname parsedrequestlabel parsedrequestcountry parsedrequeststate parsedrequeststreet parsedrequestcounty parsedrequestcity parsedrequestdistrict parsedrequesthousenumber parsedrequestpostalcode parsedrequestbuilding parsedrequestaddresslines parsedrequestadditionaldata parsedrequestposition Cancelling a Job To cancel a job use the cancel action with an HTTP PUT. This requires the <RequestID>. &app_code=ajknxv84fjrb0kihaws0tg &app_id=demoappid gal

21 Batch Geocoder API Developer's Guide 21 User Guide Removing a Job After 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. &app_id=demoappid gal Note: Jobs are automatically removed from the server 30 days after they are processed. Tools When 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" --postfile=addresses.txt " &app_code=ajknxv84fjrb0kihaws0tg &app_id=demoappid gal &action=run &header=true &indelim=; &outdelim=, &outcols=recid,latitude,longitude,locationlabel &mailto=<my_ > &outputcombined=true &language=de-de"

22 Batch Geocoder API Developer's Guide 22 User Guide 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" " &app_code=ajknxv84fjrb0kihaws0tg &app_id=demoappid gal &action=run &header=true &indelim=; &outdelim=, &outcols=recid,latitude,longitude,locationlabel &mailto=<my_ > &outputcombined=true &language=de-de" Service Support If you need assistance with this or other HERE products, please contact your HERE representative or Technical Customer Support via at

23 Batch Geocoder API Developer's Guide 23 API Reference Chapter 4 API Reference Topics: API Endpoints Request Parameters Error Messages This part of the guide provides a comprehensive reference to Batch Geocoder API.

24 Batch Geocoder API Developer's Guide 24 API Reference API Endpoints Table 14: 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> jobs/<requestid>/result jobs/<requestid>/errors jobs/<requestid>/no-matches jobs/<requestid>/all 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. 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. Starts a download of the error file. The errors file contains all invalid lines from the input data. Download all results that the geocoder could not match to an address ("no-match") Downloads the no-matches file only. Downloads all available files in one zip file Downloads all the files: result, errors (optional) DELETE GET GET GET GET

25 Batch Geocoder API Developer's Guide 25 API Reference URL Request Description HTTP Method invalid report Request Parameters Table 15: Request Parameters for Job Submission Parameter Type Description indelim Char Field delimeter in the input data. mailto String, Required address where completion notification is sent. The 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 16: Request Parameters for Geocoding Parameter Type Description locationattributes Enumeration Query parameter to request special location attributes

26 Batch Geocoder API Developer's Guide 26 API Reference Parameter Type Description addressattributes Enumeration Query parameter to request special address attributes responseattributes Enumeration Query parameter to request special response attributes 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. 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. Note: These parameters will be taken as default parameters for the geocoding query. Default values can be overridden by non-empty input cells in the input line. E.g. a request sent with language=en-us will add the language parameter with values en-us to each Geocoder request, 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 or more spaces is not an empty string value. Note: For the detailed description of these parameters' usage, please consult the Geocoder API Developer's Guide. Table 17: 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.

27 Batch Geocoder API Developer's Guide 27 API Reference Parameter Type Description If false the above endpoints will return uncompressed text files (HTTP Content-Type text/plain) Error Messages Errors in this table are ordered alphabetically by error text. Table 18: Error messages Error text address is missing Expected Format Input delimiter is missing Invalid input data Invalid output column Output columns are missing Output combined in missing Output delimiter is missing Permanently Prohibited Request Id is missing Request Id: { } Input file is missing Request Id:{ } is invalid There was an error in processing your file There was an error locating your file Unable to determine search type based upon input columns Unable to read input file to determine input columns Description Supply an address for notification. Data must be in the correct format. Supply input delimiter of the input address file. Request parameters are incorrectly formatted. The column requested is invalid. Supply valid output columns. User needs to supply a value for OutputCombined parameter. Supply output delimiter of the result files. User needs to supply correct authentication key in token parameter. No request id was submitted in the request. The input address file is missing. Possible reasons: The file was not uploaded or was removed for archive purposes. The request id could not be found. Possible reasons: An input file was not uploaded or directory was removed for archive purposes. The requested file was unavailable. Possible error in processing or removed for archive purposes. The requested file was unavailable. Possible error in processing or removed for archive purposes. Based upon the input columns submitted, the type of service could not be determined. No column names were included in the header of the input address file.