Custom Location Extension API

Transcription

1 Custom Location Extension API Developer's Guide Version

2 Custom Location Extension API Developer's Guide 2 Contents Contents Legal Notices...4 Document Information... 5 Chapter 1: Overview... 6 What is the Custom Location Extension API?...7 Why use the Custom Location Extension API?... 7 Chapter 2: User Guide... 8 Acquiring Credentials...9 Constructing a Request... 9 Customer Integration Testing...10 Examples...10 Bounding Box Search for Custom Locations...10 Corridor Search Using Coordinates for Custom Locations...12 Corridor Search Using RouteId for Custom Locations...17 Proximity Search for Custom Locations...23 Attribute Search for Custom Locations Custom Attribute Search for Custom Locations Searching a Custom Search Index Service Support Chapter 3: API Reference...31 Location Management Resources Asynchronous XML Location Import Asynchronous Shape Import Asynchronous Import Report...37 XML Location Import...38 Location Search Resources...39

3 Custom Location Extension API Developer's Guide 3 Contents Search Resources...39 Feature Search Resources...53 Request Data Types...56 Response Data Types Errors...64

4 Custom Location Extension API Developer's Guide 4 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.

5 Custom Location Extension API Developer's Guide 5 Document Information Document Information Product Name: Custom Location Extension API Version: Version Document Name: Id: Status: Date: Custom Location Extension API Developer's Guide 285e2c FINAL 2014-Sep-30, 7:40 (GMT)

6 Custom Location Extension API Developer's Guide 6 Overview Chapter 1 Overview Topics: What is the Custom Location Extension API? Why use the Custom Location Extension API? This document introduces the Custom Location Extension API and: explains key concepts provides examples documents resources and query parameters documents request and response structures and data types

7 Custom Location Extension API Developer's Guide 7 Overview What is the Custom Location Extension API? The HERE Custom Location Extension API is a service that stores and retrieves custom locations. Upload locations as CSV files or ESRI standard compliant shapes via an administration website or as XML files via HTTP POST requests to the RESTful API. Retrieve locations by making HTTP GET requests to the RESTful API. This document discusses how to use the API. To learn more about how to upload locations using the administration website, see the Custom Location Extension API User Guide. Why use the Custom Location Extension API? The Custom Location Extension API provides solutions for the following high level use cases: Store custom sets of locations and polygons, for use with other HERE APIs. Perform a proximity search for custom points of interest and polygons around a specified location. Retrieve a set of custom points of interest (POIs) and/or polygons within a specified bounding box. Find all custom locations and polygons within an isoline route result. Find all custom locations and polygons within a specified radius of a defined route. Search custom indices generated from multiple fields from one or more layers.

8 Custom Location Extension API Developer's Guide 8 User Guide Chapter 2 User Guide Topics: Acquiring Credentials Constructing a Request Examples Service Support The articles in this section provide a guide to using the Custom Location Extension API.

9 Custom Location Extension API Developer's Guide 9 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 Custom Location Extension API includes the basic elements shown in the following table and, in addition, it may contain resource-specific parameters or data. Table 1: Basic request elements Element Value/Example Description Base URL Production environment only Staging environment only [1] Path /v1/ Resource file/import search custom/index name POST only, submit data in the body of the request GET only, specify request details via query parameters Application Code &app_code=ajknxv84fjrb0kihaws0tg Substitute your own unique app_code Application Id &app_id=demoappid gal Substitute your own unique app_id Example This example search request uses HTTP GET to request locations within 5 kilometers of a point in Berlin, Germany in layer 30, which is for Nokia Stores DE: &app_code=ajknxv84fjrb0kihaws0tg &coord= , &layerid=30

10 Custom Location Extension API Developer's Guide 10 User Guide &radius=5000 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 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. The CIT environment is not intended for general production use. Examples This section provides examples of requests along with the responding results. Bounding Box Search for Custom Locations Using a bounding box search, you can select user-defined locations that are within a specified area. Compared to a proximity search, which searches within a radius of a specific location, a bounding box search allows you to exactly specify a rectangular area in which you would like to search for userdefined locations. In this example, we search for all locations in the "Nokia Stores DE" layer that are located in an area defined by the following conditions: POI should be located south of Friedrichstraße train station in Berlin. POI should be located north of Französische Straße metro station in Berlin. POI should be located east of the Brandenburger Tor in Berlin. POI should be located west of the Deutsches Historisches Museum in Berlin.

11 Custom Location Extension API Developer's Guide 11 User Guide The conditions listed above describe the area shown in the image below: Figure 1: Search Area in Berlin We can retrieve the latitude and longitude values for the area shown above by using the mouse geo-locator feature (enabled in the Preferences section) of here.com. For this area, we identify the latitude and longitude values for the top-left ( , ) and bottom-right ( , ) coordinates of the bounding box described. Request &app_code=ajknxv84fjrb0kihaws0tg &bbox= , ; , &layerid=30 Response "message": "OK", "status": "200 OK", "layername": "Nokia Stores DE", "layerid": 30, "limit": 200, "offset": 0, "available": 1, "bblocations": [ "city": "Berlin-Mitte", "coordinate": "latitude": , "longitude":

12 Custom Location Extension API Developer's Guide 12 User Guide ] "country": "DEU", "customattributes": [], "customerlocationid": "227242", "fax": "(null)", "name1": "_dug Berlin-Mitte Friedrichstr.", "phone": "(null)", "postalcode": "10117", "routecoordinate": "latitude": , "longitude": "street": "Friedrichstr " Corridor Search Using Coordinates for Custom Locations This example describes a corridor search, which requests custom locations within a given distance of a route. First, we request a route from Friedrichstraße train station to Französische Straße metro station, both in Berlin, using the HERE Routing API. Using response data from that request, we create an array of latitudes and longitudes. Finally, we make a request to the Custom Location Extension API

13 Custom Location Extension API Developer's Guide 13 User Guide to search for all custom locations in the "Nokia Stores DE" layer, using the array and a radius value to define a shape search area. Figure 2: Berlin Route Used in Custom POI Search Routing API Request First, we need to calculate the route, using the Routing API. We can use the latitude and longitude values contained in the response data, along with a defined radius, to set the search area for our Custom Location Extension API request. &app_code=ajknxv84fjrb0kihaws0tg

14 Custom Location Extension API Developer's Guide 14 User Guide &waypoint0=geo! , &waypoint1=geo! , &mode=shortest;car Routing API Response "Response": "MetaInfo":... "Route":[ "RouteId":"REM0iQIAAADG-ZtQiEJKQBnlmZf DxipAAAAA4IlCSkAAAABAw8YqQAAAAAAAAPB _AAAAAAAA8H850yIicbVOXI4HKQFdmfBL _RyrAAEAAACQBykBAQAAAAAdqwABAAAAAADA _weaaaaaamd_uw2d8a_k", "Waypoint":[ "LinkId":" ", "MappedPosition": "Latitude": , "Longitude": "OriginalPosition": "Latitude": , "Longitude": "Type":"stopOver" "LinkId":" ", "MappedPosition": "Latitude": , "Longitude": "OriginalPosition": "Latitude": , "Longitude": "Type":"stopOver" ], "Mode": "Type":"shortest", "TransportModes":[ "car" ],...

15 Custom Location Extension API Developer's Guide 15 User Guide ] "Leg":[... ], "Summary": "Distance":571, "TrafficTime":69, "BaseTime":69, "Flags":[ ] Although we use HTTP GET in this example, we recommend HTTP POST when submitting a large array of route coordinates. The HTTP protocol does not place any a priori limit on the length of a URL, however some browsers can only handle URLs up to 2000 characters. Custom Location Extension API Request using Route Leg Lat-Long Values &app_code=ajknxv84fjrb0kihaws0tg &route= , , , , , , , , , &radius=100 &layerid=30 Custom Location Extension API Response "message": "OK", "status": "200 OK", "corridorlocations": [ "customerlocationid": "227242", "name1": "_dug Berlin-Mitte Friedrichstr.", "street": "Friedrichstr ", "city": "Berlin-Mitte", "postalcode": "10117", "country": "DEU", "phone": "(null)", "fax": "(null)", "weburl": "(null)", "customattributes": [], "coordinate":

16 Custom Location Extension API Developer's Guide 16 User Guide "longitude": , "latitude": "routecoordinate": "longitude": , "latitude": "distance": "customerlocationid": "227212", "name1": "O2 Partner Shop", "street": "Friedrichstraße ", "city": "Berlin", "postalcode": "10117", "country": "DEU", "phone": "(null)", "fax": "(null)", "weburl": "(null)", "customattributes": [], "coordinate": "longitude": , "latitude": "routecoordinate": "longitude": , "latitude": "distance": ], "layerid": 30

17 Custom Location Extension API Developer's Guide 17 User Guide Figure 3: Berlin Map Display, Including Route and Custom POIs Corridor Search Using RouteId for Custom Locations This example describes a search of custom locations within a given distance from a previously calculated route. The search uses a predetermined routeid from the HERE Routing API response. This search requests all locations in the "Nokia Stores DE" layer that are along a route from

18 Custom Location Extension API Developer's Guide 18 User Guide Friedrichstraße train station (latitude: , longitude: ) to Französische Straße metro station (latitude: , longitude: ), both located in Berlin. Figure 4: Berlin Route Used in Custom POI Search HERE Routing API Request First, we need to calculate the route, using the HERE Routing API. We will use the routeid from that request, along with a defined radius to set the search area for our Custom Location Extension API request. &app_code=ajknxv84fjrb0kihaws0tg

19 Custom Location Extension API Developer's Guide 19 User Guide &waypoint0=geo! , &waypoint1=geo! , &mode=shortest;car HERE Routing API Response "Response": "MetaInfo":.. "Route":[ "RouteId":... "Waypoint":[ "LinkId":" ", "MappedPosition": "Latitude": , "Longitude": "OriginalPosition": "Latitude": , "Longitude": "Type":"stopOver" "LinkId":" ", "MappedPosition": "Latitude": , "Longitude": "OriginalPosition": "Latitude": , "Longitude": "Type":"stopOver" ], "Mode": "Type":"shortest", "TransportModes":[ "car" ],... "Leg":[

20 Custom Location Extension API Developer's Guide 20 User Guide "Start": "LinkId":" ", "MappedPosition": "Latitude": , "Longitude": "OriginalPosition": "Latitude": , "Longitude": "Type":"stopOver" "End": "LinkId":" ", "MappedPosition": "Latitude": , "Longitude": "OriginalPosition": "Latitude": , "Longitude": "Type":"stopOver" "Length":571, "TravelTime":69.1, "Maneuver":[ "_type":"privatetransportmaneuvertype", "Position": "Latitude": , "Longitude": "Instruction": "Head toward Friedrichstraße on Georgenstrasse. Go for 30 feet.", "TravelTime":1.1, "Length":9, "id":"m1" "_type":"privatetransportmaneuvertype", "Position": "Latitude": , "Longitude": "Instruction": "Turn right onto Friedrichstraße.

21 Custom Location Extension API Developer's Guide 21 User Guide ] ] ], "Summary": "Distance":571, "TrafficTime":69, "BaseTime":69, "Flags":[ ] Go for 0.3 miles.", "TravelTime":68, "Length":562, "id":"m2" "_type":"privatetransportmaneuvertype", "Position": "Latitude": , "Longitude": "Instruction": "Arrive at Friedrichstraße. The trip takes 0.4 miles and 1 min.", "TravelTime":0, "Length":0, "id":"m3" Custom Location Extension API Request using RouteId &app_code=ajknxv84fjrb0kihaws0tg &routeid=rem0iqiaaadg-ztqiejkqbnlmz fdxipaaaaa4ilcskaaaabaw8yqqaaaaaaaapb _AAAAAAAA8H850yIicbVOXI4HKQFdmfBL_RyrAAEAAACQ BykBAQAAAAAdqwABAAAAAADA_wEAAAAAAMD_UW2D8A_K &radius=100 &layerid=30 Custom Location Extension API Response "message": "OK", "status": "200 OK", "corridorlocations": [

22 Custom Location Extension API Developer's Guide 22 User Guide "customerlocationid": "227242", "name1": "_dug Berlin-Mitte Friedrichstr.", "street": "Friedrichstr ", "city": "Berlin-Mitte", "postalcode": "10117", "country": "DEU", "phone": "(null)", "fax": "(null)", "weburl": "(null)", "customattributes": [], "coordinate": "longitude": , "latitude": "routecoordinate": "longitude": , "latitude": "distance": "customerlocationid": "227212", "name1": "O2 Partner Shop", "street": "Friedrichstraße ", "city": "Berlin", "postalcode": "10117", "country": "DEU", "phone": "(null)", "fax": "(null)", "weburl": "(null)", "customattributes": [], "coordinate": "longitude": , "latitude": "routecoordinate": "longitude": , "latitude": "distance": ], "layerid": 30

23 Custom Location Extension API Developer's Guide 23 User Guide Figure 5: Berlin Map Display, Including Route and Custom POIs Proximity Search for Custom Locations The Custom Location Extension API allows you to perform a proximity search to return a list of custom locations that fall within a specified radius of a certain location. In this example, we search for all locations in the "Nokia Stores DE" layer that exist within a 0.5 kilometer radius of Franfurt Central Station ( , ).

24 Custom Location Extension API Developer's Guide 24 User Guide Proximity Request &app_code=ajknxv84fjrb0kihaws0tg &coord= , &radius=500 &layerid=30 Custom Location Extension API Response "message": "OK", "status": "200 OK", "proximitylocations": [ "customerlocationid": " ", "name1": "_dug Suhl", "street": "Steinweg 12", "city": "Suhl", "postalcode": "98527", "country": "DEU", "phone": "(null)", "fax": "(null)", "customattributes": [ "name": "CATEGORY", "value": "" ], "coordinate": "longitude": , "latitude": "routecoordinate": "longitude": , "latitude": "distance": 53.1 "customerlocationid": " ", "name1": "The Phone House", "street": "Steinweg 1", "city": "Frankfurt", "postalcode": "60313", "country": "DEU", "phone": " ", "fax": " ", "customattributes": [ "name": "CATEGORY", "value": ""

25 Custom Location Extension API Developer's Guide 25 User Guide ], "coordinate": "longitude": , "latitude": "routecoordinate": "longitude": , "latitude": "distance": 65.3 "customerlocationid": " ", "name1": "SMS Michel Communication GmbH", "street": "Zeilgalerie , Shop 43A", "city": "Frankfurt", "postalcode": "60313", "country": "DEU", "phone": " ", "fax": " ", "customattributes": [ "name": "CATEGORY", "value": "" ], "coordinate": "longitude": , "latitude": "routecoordinate": "longitude": , "latitude": "distance": ], "layername": "Nokia Stores DE", "layerid": 30, "limit": 200 Attribute Search for Custom Locations Custom Location Extension API allows you to perform an attribute search of user-defined locations. The following example searches for locations in the "Nokia Stores DE" layer that have the word "allee" in their street name and "partner" in their name using the query parameter.

26 Custom Location Extension API Developer's Guide 26 User Guide Request &app_code=ajknxv84fjrb0kihaws0tg &layerid=30 &query=[like]/street/allee/[and][like]/name1/partner Response "layerid": 30, "layername": "Nokia Stores DE", "locations": [ "city": "Forchheim", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "226031", "fax": " ", "name1": "O2 Partner Shop Forchheim", "phone": " ", "postalcode": "91301", "routecoordinate": "latitude": , "longitude": "street": "Hornschuchallee 26" "city": "Hamburg", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "227582", "fax": " ", "name1": "E-Plus Partnershop", "phone": " ", "postalcode": "20146", "routecoordinate": "latitude": , "longitude": "street": "Grindelallee 40"

27 Custom Location Extension API Developer's Guide 27 User Guide "city": "Norderstedt", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "225851", "fax": " ", "name1": "O2 Partner Shop", "phone": " ", "postalcode": "22850", "routecoordinate": "latitude": , "longitude": "street": "Berliner Allee 38-44" ], "message": "OK", "status": "200 OK" Custom Attribute Search for Custom Locations Custom Location Extension API allows you to search user-defined locations for custom attribute name value pairs within search geometries or as part of an attribute search. The following example searches for locations in the "Nokia Stores DE" layer that have a custom attribute called category with a value that starts with shopping using the customattributequery parameter. Note that the query parameter is required in attribute searches, which is why it is included as a parameter in the request. Request &app_code=ajknxv84fjrb0kihaws0tg &layerid=30 &query &customattributequery=[like*]/category/shopping Response "message": "OK", "status": "200 OK", "locations":[

28 Custom Location Extension API Developer's Guide 28 User Guide "customerlocationid": " ", "name1": "_dug Berlin-Mitte", "street": "Friedrichstraße 186", "city": "Berlin", "postalcode": "10117", "country": "DEU", "phone": " ", "fax": " ", "customattributes":[ "name": "CATEGORY", "value": "shopping mall" ], "coordinate": "longitude": , "latitude": "routecoordinate": "longitude": , "latitude": "customerlocationid": " ", "name1": "_dug Berlin-Mitte Friedrichstr.", "street": "Friedrichstr ", "city": "Berlin-Mitte", "postalcode": "10117", "country": "DEU", "phone": "(null)", "fax": "(null)", "customattributes":[ "name": "CATEGORY", "value": "shopping mall" ], "coordinate": "longitude": , "latitude": "routecoordinate": "longitude": , "latitude": ], "layername": "Nokia Stores DE", "layerid": 30

29 Custom Location Extension API Developer's Guide 29 User Guide Searching a Custom Search Index The Custom Location Extension API allows you to create custom search indices across multiple fields in one or more layers in the administration website. The following example searches for locations in the "HERESitesEurope" layer where the city field has Berlin as a value. For more information on the options available for the q parameter in particular as well as for other information about custom search index requests, see Custom Search Index on page 50. Prerequisite A custom search index called HERESitesEurope has been created in the administration website for layer 27 with the app_id value set to DemoAppId GAL. This means the app_id and app_code used to access the index must match. The index includes the following fields from the layer: city, country, name1, postalcode, and street. Request &app_code=ajknxv84fjrb0kihaws0tg &q=berlin Response "items": [ "score": , "layerid": 27, "location": "customerlocationid": "19", "name1": "NOKIA L&C", "street": "Invalidenstrasse 116", "city": "Berlin", "country": "DEU", "customattributes": [], "coordinate": "longitude": , "latitude": "routecoordinate": "longitude": , "latitude":

30 Custom Location Extension API Developer's Guide 30 User Guide ], "indexname": "HERESitesEurope" Service Support If you need assistance in using the API, contact your HERE representative or Technical Customer Support via at

31 Custom Location Extension API Developer's Guide 31 Chapter 3 API Reference Topics: Location Management Resources Location Search Resources Errors This section provides descriptions of the resources, parameters, return types and error codes of the HERE Custom Location Extension API.

32 Custom Location Extension API Developer's Guide 32 Location Management Resources This section explains how to import location data. XSD Schemas There are XSD schemas for both XML request and response formats: Name Asynchronous XML import request Included by asynchronous request and response XML import request XML import response Included by request and response URL Asynchronous XML Location Import This endpoint is used to import locations from an XML file using an HTTP POST request. The request itself is asynchronous and non-blocking. If the request is accepted, the response indicates that the server has begun processing the import request. For example: <FileImportAsyncResponse> <Message>Import Started</Message> <Status>OK</Status> <FileName>test.xml</FileName> <ImportId> </ImportId> <ReportURL>DIRECT LINK TO ASSOCIATED IMPORT REPORT</ReportURL> </FileImportAsyncResponse> The import report is continuously updated in the course of processing the request in order to reflect the number of processed locations, the number of locations not imported, etc. When the processing completes successfully, the report is ed to the address provided in the body of the XML file submitted with the original request. Other responses indicate errors (see also Errors on page 64).

33 Custom Location Extension API Developer's Guide 33 Request To import new locations you need: valid user credentials the relevant layer id in the database an xml file defined the required fields Note: Previously imported locations not contained in the XML are deleted. Resource method and URI POST /file/import/async/xml Query Parameters Parameters Required? Description xmlfile Yes A POSTED multipart/form-data XML file, which can optionally be zip compressed. Input XML File Elements and Attributes The input XML file must contain the following elements and attribute Element or attribute Required? Type Description authentication Yes Wrapper element for the authentication block. username Yes String Element for the username for importing content to layer, this value is configured by the system administrator for the layer in the administration website described in the Custom Location Extension API User Guide. password Yes String Element for the password for authenticating the username credential, this value is configured by the system administrator for the layer in the administration website described in the Custom Location Extension API User Guide. app_id Yes String Element for the app_id. For more information about application credentials, see Acquiring Credentials on page 9. app_code Yes String Element for the app_code. For more information about application credentials, see Acquiring Credentials on page 9. information Yes Wrapper element for the information about the import file. file_date No Date Element to identify the file date.

34 Custom Location Extension API Developer's Guide 34 Element or attribute Required? Type Description file_time No Time Element to identify the file time. UTC No String Element indicating the offset from UTC time (for example, +1 or -1). contact_ Yes String Element containing an address to which the system sends an report on the import when the report_attachment attribute is set to true. synchronize Yes Wrapper element indicating how the system handles the import, contains the location element. layerid Yes String Attribute indicating the layer to which the system imports locations. geocode No String Defines whether import locations should be geocoded. The possible values are force which forces geocoding to be done, changed, which indicates that only locations with different addresses are geocoded, and false, which indicates that geocoding is only tried if there are no coordinates in the import file or in the already existing Custom Location Extension API database. overwriteaddress No Boolean Defines if the address data of the location should be overwritten with the result from the geocoder operation. The possible values are true, which means the address is overwritten by the geocoding results, and false, which means only the coordinates are updated. The default behavior is false. report_attachment No Boolean Defines if the system should send a report about the import to the address defined in the contact_ element. The possible values are true, which means the system sends a report, and false, which means the system does not send a report. location Yes LocationType on page 60 Information defining the location. For information on the XSD URLs, see Location Management Resources on page 32.

35 Custom Location Extension API Developer's Guide 35 Example Input XML File This is an example XML file showing the minimum fields required to successfully import a location. This file can be imported using a curl statement or using a simple HTML web page as provided below. <?xml version="1.0"?> <request> <authentication> <username>your_username</username> <password>your_password</password> <app_id>your_app_id</app_id> <app_code>your_app_code</app_code> </authentication> <information> <file_date> </file_date> <file_time>13:11:51</file_time> <UTC>+1</UTC> <contact_ >tcsplatform@here.com</contact_ > </information> <synchronize layerid="30" geocode="changed" overwriteaddress="false"> <location> <customer_location_id>de12345</customer_location_id> <address> <city>berlin</city> <street>invalidenstrasse 116</street> <postalcode>10115</postalcode> <country>deu</country> </address> <name1>nokia House 1</name1> <phone> </phone> <fax/> < >developer.jobs.berlin@nokia.com</ > <description>mo. - Fr.: #08:00-19:00 Sat., Sun: closed</description> <logo_url/> <url/> <custom_fields> <field name="division">here</field> </custom_fields> </location> </synchronize> </request> Example curl Request to Upload XML File curl F xmlfile=@path/to/xmlfile.xml async/xml Example Web Page to upload XML File <!DOCTYPE html> <html xmlns=" <head> <meta http-equiv="content-type" content="text/html; charset=utf-8" /> <title>here - [Custom Location Service] - XML File Upload Example</title> </head> <body> <h1>xml File Upload Example</h1> <form action=" enctype="multipart/form-data" method="post">

36 Custom Location Extension API Developer's Guide 36 <label>xmlfile</label> <input type="file" name="xmlfile"><br/> <input type="submit" value="send"> </form> </body> </html> Asynchronous Shape Import Import polygons, polylines and shapes in ESRI format from an XML file using an HTTP POST request. As this is an asychronous request, the response is not returned immediately, a report is ed to the address provided in the request. Note: Custom Location Extension API does not currently support the importation of pointbased shapefiles. Resource method and URI POST /file/import/async/shape Query Parameters Parameters Required? Description zipfile Yes A multipart/form-data ZIP file of ESRI data, containing only one.shp file. username Yes Custom Location Extension API username. password Yes Custom Location Extension API password. customerid Yes Custom Location Extension API customer ID used to uniquely identify the account with which the system associates locations and users. HERE provides the customerid during the registration process. layerid Yes Layer the shapes are imported to. properties No Comma separated list of property field names in the ESRI shapes to import. Use all to import all properties. No Comma-separated list of addresses that should receive a report when the import is done. Example Response Note that the link in the example response is not a current working link. <?xml version="1.0"?> <FileImportAsyncResponse> <Message>Import Started</Message> <Status>OK</Status> <ArchiveName>pgc2007.zip</ArchiveName> <FileName>pgc2007.shp</FileName>

37 Custom Location Extension API Developer's Guide 37 <ImportId> </ImportId> <ReportURL> token=71fec81eb34aab588b1f13b8ebcc7782&customerid=1&importid= </ReportURL> </FileImportAsyncResponse> Asynchronous Import Report Get status reports on asynchronous shape or location imports. Specify the import using one of the following: importid: from the import request response. userid: by user. layerid: by layer. fromdate: after the specified date. todate: before the specificed date. Resource method and URI POST /file/import/async/report Query Parameters Parameters Required? Description token Yes Token in the valid report URL in the response to an file import request. Tokens can also be requested by using one of the following HTTP GET queries: Production environment: customlocation.api.here.com/v1/admin/user/login? username=[username&password=[password Staging environment: stg.api.customlocation.nokia.com/v1/admin/user/login? username=[username&password=[password, where the USERNAME and PASSWORD are the credentials for the Custom Location Extension API administration website. Note that tokens expire which may lead to a need to request another token. customerid Yes Custom Location Extension API customer ID used to uniquely identify the account with which the system associates locations and users. HERE provides the customerid during the registeration process. importid No Specify the import by import Id.

38 Custom Location Extension API Developer's Guide 38 Parameters Required? Description userid No Specify the import by user. layerid No Specify the import by layer Id. fromdate No Specify the import after a date. todate No Specify the import before a date. Note: The format of the fromdate and todate fields in the import report search is yearmonth-day: YYYY-MM-DD XML Location Import Import locations from an XML file using HTTP POST requests. To import new locations you need: valid user credentials the relevant layer id in the database an xml file in the correct format Note: This endpoint has been deprecated please use Asynchronous XML Location Import on page 32 instead. Resource method and URI POST /file/import/xml Query Parameters Parameters Required? Description xmlfile Yes A POSTED multipart/form-data XML file. Example XML File <?xml version="1.0"?> <request> <authentication> <username>your_username</username> <password>your_password</password> <app_id>your_app_id</app_id> <app_code>your_app_code</app_code> </authentication> <information> <file_date> </file_date> <file_time>13:11:51</file_time> <UTC>+1</UTC> <contact_ >tcsplatform@here.com</contact_ > </information> <synchronize layerid="30" geocode="changed" overwriteaddress="false"> <location> <customer_location_id>de12345</customer_location_id>

39 Custom Location Extension API Developer's Guide 39 <address> <city>berlin</city> <street>invalidenstrasse 116</street> <postalcode>10115</postalcode> <country>deu</country> </address> <name1>nokia House 1</name1> <phone> </phone> <fax/> <description>mo. - Fr.: #08:00-19:00 Sat., Sun: closed</description> <logo_url/> <url/> <custom_fields> <field name="division">here</field> </custom_fields> </location> </synchronize> </request> Location Search Resources Location Searches are interfaces which fetch locations to be displayed with an integrated mapping application. Location Searches are also the publicly facing interface for Custom Location Extension API. This section provides descriptions of the resources (along with parameters and examples of those resources) to make such searches. Search Resources There are six Search Resources: Attribute, Bounding Box, Proximity, Corridor Using RouteId, Corridor Using Coordinates, and custom/index name. Attribute Search Search for custom locations on their attributes only, without any geographical restrictions. Resource URI GET /search/attribute

40 Custom Location Extension API Developer's Guide 40 Resource Parameters Parameters Required? Description app_id Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials. app_code Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials. customattributes[] No Optional set of custom location attribute fields to further filter the results. Every parameter value contains a field value pair (pipe delimited). For example: customattributes[]=fueltype Diesel &customattributes[]=category GasStation Note: If you want to search for a custom location based on its custom attributes, we recommend that you use the customattributequery parameter. customattributequery No See CustomAttributeQueryType. jsoncallback No Specifies the function used to wrap the JSON response. layerid Yes Layer Id identifying the layer to be searched. limit No The maximum amount of locations returned in the response. Default is 200. Maximum is 500. query yes See QueryType Response Example To see an example of an attribute search response, see Attribute Search for Custom Locations on page 25. Proximity Search Search for custom locations that are within a given radius around a center. Resource URI GET /search/proximity

41 Custom Location Extension API Developer's Guide 41 Resource Parameters Parameters Required? Description app_id Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials. app_code Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials. customattributes[] No Optional set of custom location attribute fields to further filter the results. Every parameter value contains a field value pair (pipe delimited). For example: customattributes[]=fueltype Diesel &customattributes[]=category GasStation Note: If you want to search for a custom location based on its custom attributes, we recommend that you use the customattributequery parameter. coord Yes The center of the circular search area give in latitude, longitude in decimal degrees: Must satisfy: -90 value 90 Unit: decimal degrees Reference System: WGS 84 Precision: 7 positions after decimal point, additional positions are ignored Example: coord=47.731, customattributequery No See CustomAttributeQueryType. jsoncallback No Specifies the function used to wrap the JSON response. layerid Yes Layer Id identifying the layer to be searched. limit No The maximum amount of locations returned in the response. Default is 200. Maximum is 500. query No See QueryType. radius Yes The search radius in meters.

42 Custom Location Extension API Developer's Guide 42 Response Example To see an example of a proximity search response, see Proximity Search for Custom Locations on page 23. Corridor (Using Coordinates) Search Search for custom POIs within a distance along a route specified by a range of coordinates. Resource URI GET /search/corridor Corridor search resource supports both HTTP GET and HTTP POST, however we recommend HTTP POST when you have a large number of values for the route parameter. Although the HTTP protocol does not place any a priori limit on the length of a URL some browsers can only handle URLs up to 2000 characters. Resource Parameters Parameters Required? Description app_id Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials. app_code Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials. customattributes[] No Optional set of custom location attribute fields to further filter the results. Every parameter value contains a field value pair (pipe delimited). For example: customattributes[]=fueltype Diesel &customattributes[]=category GasStation Note: If you want to search for a custom location based on its custom attributes, we recommend that you use the customattributequery parameter. jsoncallback No Specifies the function used to wrap the JSON response. layerid Yes Layer Id identifying the layer to be searched. limit No The maximum amount of locations returned in the response. Default is 200. Maximum is 500.

43 Custom Location Extension API Developer's Guide 43 Parameters Required? Description query No See QueryType. customattributequery No See CustomAttributeQueryType. radius Yes The search radius in meters. For example, half the corridor width. route Yes The coordinates of the polyline used as a corridor center line. For example: Latitude, longitude, latitude, longitude... Response Example To see an example of a corridor search response when you use coordinates, see Corridor Search Using Coordinates for Custom Locations on page 12. Corridor (Using RouteId) Search Search for custom POIs within a distance along a route specified by a routeid. Resource URI GET /search/route/corridor Resource Parameters Parameters Required? Description app_id Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials. app_code Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials. customattributes[] No Optional set of custom location attribute fields to further filter the results. Every parameter value contains a field value pair (pipe delimited). For example: customattributes[]=fueltype Diesel &customattributes[]=category GasStation Note: If you want to search for a custom location based on its custom attributes, we recommend that you use the customattributequery parameter.

44 Custom Location Extension API Developer's Guide 44 Parameters Required? Description customattributequery No See CustomAttributeQueryType. jsoncallback No Specifies the function used to wrap the JSON response. layerid Yes Layer Id identifying the layer to be searched. limit No The maximum amount of locations returned in the response. Default is 200. Maximum is 500. query No See QueryType. routeid Yes The routeid given back in the response of a Routing API. radius Yes The search radius in meters. For example, half the corridor width. Response Example To see an example of a corridor search response when you use a route ID, see Corridor Search Using RouteId for Custom Locations on page 17. Bounding Box Search Search for custom POIs within a specified rectangular geographic area. Resource URI GET /search/bbox Resource Parameters Parameters Required? Description app_id Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials. app_code Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials. bbox Yes The bounding box upper left, and lower right coordinates. In the format: latitude, longitude; latitude, longitude bbox=37.8,-122.1;37.2, WGS-84 decimal degrees

45 Custom Location Extension API Developer's Guide 45 Parameters Required? Description customattributes[] No Optional set of custom location attribute fields to further filter the results. Every parameter value contains a field value pair (pipe delimited). For example: customattributes[]=fueltype Diesel &customattributes[]=category GasStation Note: If you want to search for a custom location based on its custom attributes, we recommend that you use the customattributequery parameter. customattributequery No See CustomAttributeQueryType. jsoncallback No Specifies the function used to wrap the JSON response. layerid Yes Layer Id identifying the layer to be searched. limit No The maximum amount of locations returned in the response. Default is 200. Maximum is 500. offset No This parameter indicates the index from which relevant locations should query No See QueryType. be included in the response. You can use this parameter and the limit parameter to implement pagination for the responses to your searches. Response Example To see an example of a bounding box search response, see Bounding Box Search for Custom Locations on page 10. Quadkey Search Search for custom locations by quadkey tile. Resource URI GET /search/quadkey

46 Custom Location Extension API Developer's Guide 46 Resource Parameters Parameters Required? Description app_id Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials. app_code Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials. customattributequery No See CustomAttributeQueryType. quadkey Yes The quad key of the map tile area to search from. jsoncallback No Specifies the function used to wrap the JSON response. customattributes[] No Optional set of custom location attribute fields to further filter the results. Every parameter value contains a field value pair (pipe delimited). For example: customattributes[]=fueltype Diesel &customattributes[]=category GasStation Note: If you want to search for a custom location based on its custom attributes, we recommend that you use the customattributequery parameter. layerid Yes Layer Id identifying the layer to be searched. limit No The maximum amount of locations returned in the response. Default is 300. Maximum is 500. offset No This parameter indicates the index from which relevant locations should be included in the response. You can use this parameter and the limit parameter to implement pagination for the responses to your searches. Response Example "message": "OK", "status": "200 OK", "locations": [ "customerlocationid": "227488", "name1": "Mobilcom-Shop im Hertie", "street": "Hauptstrasse 142", "city": "Berlin", "postalcode": "10827", "country": "DEU", "phone": "(null)", "fax": "(null)", "customattributes": [],

47 Custom Location Extension API Developer's Guide 47 "coordinate": "longitude": , "latitude": "routecoordinate": "longitude": , "latitude": "customerlocationid": "227425", "name1": "O2 Shop Berlin Charlottenburg", "street": "Westfälische Straße 47/48", "city": "Berlin", "postalcode": "10711", "country": "DEU", "phone": " ", "fax": " ", "customattributes": [], "coordinate": "longitude": , "latitude": "routecoordinate": "longitude": , "latitude": ], "layername": "Nokia Stores DE", "layerid": 30, "limit": 2, "offset": 0, "available": 18 Polygon Search Search for locations inside a user-defined polygon by specifying a polygon in one of the following three formats: wktpolygon polygon geomeryid Resource URI GET /search/polygon Resource Parameters Parameters Required? Description app_id Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials.

48 Custom Location Extension API Developer's Guide 48 Parameters Required? Description app_code Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 9 for information on getting credentials. customattributes[] No Optional set of custom location attribute fields to further filter the results. Every parameter value contains a field value pair (pipe delimited). For example: customattributes[]=fueltype Diesel &customattributes[]=category GasStation Note: If you want to search for a custom location based on its custom attributes, we recommend that you use the customattributequery parameter. customattributequery No See CustomAttributeQueryType. jsoncallback No Specifies the function used to wrap the JSON response. layerid Yes Layer Id identifying the layer to be searched. limit No The maximum amount of locations returned in the response. Default is 300. Maximum is 500. wktpolygon No A WKT (Well Known Text) formatted Polygon. polygon No A list of coordinates defining the polygon. First coordinate must be the same as the last one. Accepted format: lat,lon lat,lon lat,lon... geometryid No The geometryid of a polygon stored in the Custom Location Extension API database. Response Example See the following example response: "message": "OK", "status": "200 OK", "locations": [ "customerlocationid": " ", "name1": "Teleprofi Vogedes", "street": "Stromberger Straße 51", "city": "Oelde", "postalcode": "59302", "country": "DEU", "phone": " ", "fax": " ", "customattributes": [ "name": "CATEGORY", "value": ""