Custom Location Service API

Transcription

1 Custom Location Service API Developer's Guide Version 1.0.0

2 Custom Location Service API Developer's Guide 2 Contents Contents Legal Notices...3 Document Information... 4 Chapter 1: Overview... 5 What is the Custom Location Service API?... 6 Why use the Custom Location Service API?...6 Chapter 2: User Guide... 7 Acquiring Credentials...8 Constructing a Request... 8 Examples... 9 Atrribute Search...9 Bounding Box Search...11 Corridor Search using Coordinates Corridor Search using RouteId Proximity Search Service Support Chapter 3: API Reference...26 Location Management...27 XML File Location Import Location Search Resources...28 Request Parameter Data Types Response Data Types Errors...41

3 Custom Location Service API Developer's Guide 3 Legal Notices Legal Notices 2013 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 Custom Location Service API Developer's Guide 4 Document Information Document Information Product Name: Custom Location Service API Version: Version Document Name: Id: Status: Date: Custom Location Service API Developer's Guide 5f370a FINAL 2013-Sep-25, 10:42 (GMT)

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

6 Custom Location Service API Developer's Guide 6 Overview What is the Custom Location Service API? HERE Custom Location Service API is a service that allows storage and retrieval of user-defined locations. Storing of locations can either be done by uploading a CSV file via an administration website or by using HTTP POST to upload an XML file via the service. Retrieval of locations is done by making calls to a RESTful API. In this document we discuss using the API. To learn more on how to upload locations using the administration website, please refer the Custom Location Service API User Guide. Why use the Custom Location Service API? Custom Location Service API provides solutions for the following high level use cases: Store a user-defined set of locations, for use with other HERE APIs. Perform a proximity search for user-defined points of interest around a specified location. Retrieve a set of user-defined points of interest within a specified bounding box. Find all user-defined locations within an isoline route result. Find all user-defined locations within a certain radius of a defined route, using its routeid.

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

8 Custom Location Service API Developer's Guide 8 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 Service 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 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 [1] The staging environment allows you to test your software against a newer version of the service before HERE brings that version into production. Note that the same application id can be used in both environments, but staging may require a dedicated application code. If this is the case, please contact us as described under Service Support on page 25. The staging environment is not intended for production use and HERE SLAs do not apply for this environment.

9 Custom Location Service API Developer's Guide 9 User Guide Here is an example of a search request, which uses the HTTP GET method: &app_code=ajknxv84fjrb0kihaws0tg &coord=50.112, &layerid=27 &radius=50000 Examples This section provides examples of requests along with the responding results. Search on Custom POIs on an Attribute Custom Location Service API allows you to perform an attribute search of user-defined points of interest. In following example, we search 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. 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",

10 Custom Location Service API Developer's Guide 10 User Guide "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" "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"

11 Custom Location Service API Developer's Guide 11 User Guide Search on Custom POIs Within a Defined Area Using a bounding box search, you can select user-defined points of interest 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 user-defined POIs. 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. 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

12 Custom Location Service API Developer's Guide 12 User Guide &bbox= , ; , &layerid=30 Response "bblocations": [ "city": "Berlin-Mitte", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "227242", "fax": "(null)", "name1": "_dug Berlin-Mitte Friedrichstr.", "phone": "(null)", "postalcode": "10117", "routecoordinate": "latitude": , "longitude": "street": "Friedrichstr " ], "layerid": 30, "layername": "Nokia Stores DE", "message": "OK", "status": "200 OK" Search Custom POIs along a Route This example describes a route corridor search, which requests custom POIs 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 Service API

13 Custom Location Service API Developer's Guide 13 User Guide to search for all custom POIs in the "Nokia Stores DE" layer, using 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 will 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 Service API request. &app_code=ajknxv84fjrb0kihaws0tg

14 Custom Location Service 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 Service 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 Service API Request using Route Leg Lat-Long Values &app_code=ajknxv84fjrb0kihaws0tg &route= , , , , , , , , , &radius=100 &layerid=30 Custom Location Service API Response "corridorlocations": [ "city": "Frankfurt", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "227364", "distance": ,

16 Custom Location Service API Developer's Guide 16 User Guide "fax": " ", "name1": "Handys007", "phone": " ", "postalcode": "60311", "routecoordinate": "latitude": , "longitude": "street": "Hasengasse 2" "city": "Remscheid", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "226542", "distance": , "fax": " ", "name1": "_dug Remscheid", "phone": " ", "postalcode": "42853", "routecoordinate": "latitude": , "longitude": "street": "Theodor-Heuss-Platz 7 (Allee-Center)" ], "layerid": 30, "message": "OK", "status": "200 OK"

17 Custom Location Service API Developer's Guide 17 User Guide Figure 3: Berlin Map Display, Including Route and Custom POIs Search Custom POIs using RouteId This example describes a search of custom POIs 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 Friedrichstraße train

18 Custom Location Service API Developer's Guide 18 User Guide 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 Service API request. &app_code=ajknxv84fjrb0kihaws0tg

19 Custom Location Service 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" ],...

20 Custom Location Service API Developer's Guide 20 User Guide "Leg":[ "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": ,

21 Custom Location Service API Developer's Guide 21 User Guide ] ] ], "Summary": "Distance":571, "TrafficTime":69, "BaseTime":69, "Flags":[ ] "Longitude": "Instruction": "Turn right onto Friedrichstraße. 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 Service API Request using RouteId &app_code=ajknxv84fjrb0kihaws0tg &routeid=rem0iqiaaadg-ztqiejkqbnlmz fdxipaaaaa4ilcskaaaabaw8yqqaaaaaaaapb _AAAAAAAA8H850yIicbVOXI4HKQFdmfBL_RyrAAEAAACQ BykBAQAAAAAdqwABAAAAAADA_wEAAAAAAMD_UW2D8A_K &radius=100 &layerid=30

22 Custom Location Service API Developer's Guide 22 User Guide Custom Location Service API Response "corridorlocations": [ "city": "Frankfurt", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "227364", "distance": , "fax": " ", "name1": "Handys007", "phone": " ", "postalcode": "60311", "routecoordinate": "latitude": , "longitude": "street": "Hasengasse 2" "city": "Remscheid", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "226542", "distance": , "fax": " ", "name1": "_dug Remscheid", "phone": " ", "postalcode": "42853", "routecoordinate": "latitude": , "longitude": "street": "Theodor-Heuss-Platz 7 (Allee-Center)" ], "layerid": 30, "message": "OK", "status": "200 OK"

23 Custom Location Service API Developer's Guide 23 User Guide Figure 5: Berlin Map Display, Including Route and Custom POIs Proximity Search on Custom POIs The Custom Location Service API allows you to perform a proximity search to return a list of custom POIs 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 Service API Developer's Guide 24 User Guide Proximity Request &app_code=ajknxv84fjrb0kihaws0tg &coord= , &radius=500 &layerid=30 Custom Location Service API Response "layerid": 30, "layername": "Nokia Stores DE", "message": "OK", "proximitylocations": [ "city": "Suhl", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "226880", "distance": 53.1, "fax": "(null)", "name1": "_dug Suhl", "phone": "(null)", "postalcode": "98527", "routecoordinate": "latitude": , "longitude": "street": "Steinweg 12" "city": "Frankfurt", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "226801", "distance": 65.3, "fax": " ", "name1": "The Phone House", "phone": " ", "postalcode": "60313", "routecoordinate":

25 Custom Location Service API Developer's Guide 25 User Guide "latitude": , "longitude": "street": "Steinweg 1" "city": "Frankfurt", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "224632", "distance": 245.8, "fax": " ", "name1": "SMS Michel Communication GmbH", "phone": " ", "postalcode": "60313", "routecoordinate": "latitude": , "longitude": "street": "Zeilgalerie , Shop 43A" ], "status": "200 OK" Service Support If you need assistance in using the API, contact your Nokia representative or Technical Customer Support via at

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

27 Custom Location Service API Developer's Guide 27 API Reference Location Management This section provide an explanation of how to import location data. XML File Location Import Resource URI /file/import/xml XSD Schemas Name Request Response URL The service accepts an XML file by HTTP POST. In order to be able to import new locations data: A valid user credentials must be available The layer id used must exist in the database Query Parameters Parameters Required? Description xmlfile Yes A POSTED multipart/form-data XML file. Example XML File Below is an example of an import 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>

28 Custom Location Service API Developer's Guide 28 API Reference <UTC>+1</UTC> </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/> <description>mo. - Fr.: #08:00-19:00 Sat., Sun: closed</description> <iconurl/> <url/> <custom_fields> <field name="division">here</field> </custom_fields> </location> </synchronize> </request> Location Search 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 Service API. This section provides descriptions of the resources (along with parameters and examples of those resources) to make such searches. Search Resources There are five types of Search Resources: Attribute, Bounding Box, Proximity, Corridor Using RouteId, Corridor Using Coordinates. Attribute Search Search for user-defined locations on their attributes only, without any geographical restrictions. Resource URI /search/attribute

29 Custom Location Service API Developer's Guide 29 API Reference Resource Parameters Parameters Required? Description app_id Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 8 for information on getting credentials. app_code Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 8 for information on getting credentials. customattributes[] No Optional set of custom location attribute fields to further filter the results. Every parameter value is to contain a field value pair (pipe delimited). For example: customattributes[]= FuelType Diesel&customAttributes[] =Category GasStation jsoncallback No Specifies the name of a user-defined function used to wrap the JSON response. layerid Yes Provide layer Id to target the search to a specific layer. limit No The maximum amount of locations returned in the response. Default is 100. Maximum allowed is 300. query No See QueryType Response Example Below is an example of a Attribute Search response: "layerid": 30, "layername": "Nokia Stores DE", "locations": [ "city": "Berlin", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "224807", "fax": " ", "name1": "Fera Funk GmbH", "phone": " ", "postalcode": "12435", "routecoordinate": "latitude": , "longitude":

30 Custom Location Service API Developer's Guide 30 API Reference "street": "Neue Krugallee 39"... ], "message": "OK", "status": "200 OK" Proximity Search Search for user-defined locations that are within a given radius around a center. Resource URI /search/proximity Resource Parameters Parameters Required? Description app_id Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 8 for information on getting credentials. app_code Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 8 for information on getting credentials. customattributes[] No Optional set of custom location attribute fields to further filter the results. Every parameter value is to contain a field value pair (pipe delimited). For example: coord Yes Is the search coordinate. customattributes[]= FuelType Diesel&customAttributes[] =Category GasStation 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, jsoncallback No Specifies the name of a user-defined function used to wrap the JSON response.

31 Custom Location Service API Developer's Guide 31 API Reference Parameters Required? Description layerid Yes Provide layer Id to target the search to a specific layer. limit No The maximum amount of locations returned in the response. Default is 100. Maximum allowed is 300. query No See QueryType radius Yes The search radius in meters. Response Example Below is an example of a Proximity Search response: "layerid": 30, "layername": "Nokia Stores DE", "message": "OK", "proximitylocations": [ "city": "Frankfurt", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "227364", "distance": 80.2, "fax": " ", "name1": "Handys007", "phone": " ", "postalcode": "60311", "routecoordinate": "latitude": , "longitude": "street": "Hasengasse 2"... "city": "Mainburg", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "225300", "distance": , "fax": " ", "name1": "Bachner Elektrohandel GmbH", "phone": " ", "postalcode": "84048", "routecoordinate": "latitude": , "longitude": "street": "Bahnhofstr. 15"

32 Custom Location Service API Developer's Guide 32 API Reference ], "status": "200 OK" Corridor (Using Coordinates) Search Search for user-defined POIs within a distance along a route specified by range of coordinates. Resource URI /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 HTTP protocol does not place any a priori limit on the length of a URL some browsers can only handle URLs upto 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 8 for information on getting credentials. app_code Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 8 for information on getting credentials. customattributes[] No Optional set of custom location attribute fields to further filter the results. Every parameter value is to contain a field value pair (pipe delimited). For example: customattributes[]= FuelType Diesel&customAttributes[] =Category GasStation jsoncallback No Specifies the name of a user-defined function used to wrap the JSON response. layerid Yes Provide layer Id to target the search to a specific layer. limit No The maximum amount of locations returned in the response. Default is 100. Maximum allowed is 300. query No See QueryType radius Yes The search radius in meters. For example, half the corridor width.

33 Custom Location Service API Developer's Guide 33 API Reference Parameters Required? Description route Yes The coordinates of the polyline used as a corridor center line. For example: Latitude, longitude, latitude, longitude... Response Example Below is an example of Corridor (Using Coordinates) Search response: "corridorlocations": [ "city": "Remscheid", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "226542", "distance": , "fax": " ", "name1": "_dug Remscheid", "phone": " ", "postalcode": "42853", "routecoordinate": "latitude": , "longitude": "street": "Theodor-Heuss-Platz 7 (Allee-Center)" ], "layerid": 30, "message": "OK", "status": "200 OK" Corridor (Using RouteId) Search Search for user-defined POIs within a distance along a route specified by routeid. Resource URI /search/route/corridor

34 Custom Location Service API Developer's Guide 34 API Reference Resource Parameters Parameters Required? Description app_id Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 8 for information on getting credentials. app_code Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 8 for information on getting credentials. customattributes[] No Optional set of custom location attribute fields to further filter the results. Every parameter value is to contain a field value pair (pipe delimited). For example: customattributes[]= FuelType Diesel&customAttributes[] =Category GasStation jsoncallback No Specifies the name of a user-defined function used to wrap the JSON response. layerid Yes Provide layer Id to target the search to a specific layer. limit No The maximum amount of locations returned in the response. Default is 100. Maximum allowed is 300. 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 Below is an example of a Corridor (Using RouteId) Search response: "corridorlocations": [ "city": "Remscheid", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "226542", "distance": , "fax": " ", "name1": "_dug Remscheid", "phone": " ", "postalcode": "42853", "routecoordinate":

35 Custom Location Service API Developer's Guide 35 API Reference "latitude": , "longitude": "street": "Theodor-Heuss-Platz 7 (Allee-Center)" ], "layerid": 30, "message": "OK", "status": "200 OK" Bounding Box Search Search for user-defined POIs within a specified rectangular geographic area. Resource URI /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 8 for information on getting credentials. app_code Yes A URL-safe encoded string obtained during the application registration. See Acquiring Credentials on page 8 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 customattributes[] No Optional set of custom location attribute fields to further filter the results. Every parameter value is to contain a field value pair (pipe delimited). For example: customattributes[]= FuelType Diesel&customAttributes[] =Category GasStation jsoncallback No Specifies the name of a user-defined function used to wrap the JSON response. layerid Yes Provide layer Id to target the search to a specific layer. limit No The maximum amount of locations returned in the response. Default is 100.

36 Custom Location Service API Developer's Guide 36 API Reference Parameters Required? Description Maximum allowed is 300. query No See QueryType Response Example Below is an example of a Bounding Box Search response: "bblocations": [ "city": "Frankfurt", "coordinate": "latitude": , "longitude": "country": "DEU", "customattributes": [], "customerlocationid": "227470", "fax": "(null)", "name1": "O2 Shop Frankfurt", "phone": "(null)", "postalcode": "60329", "routecoordinate": "latitude": , "longitude": "street": "Kaiserstr "... ], "layerid": 30, "layername": "Nokia Stores DE", "message": "OK", "status": "200 OK" Request Parameter Data Types QueryType Using the query parameter one can tell the Custom Location Service API to only return search results that fit a given condition or set of conditions. Note that all filtering conditions are applied as case insensitive. The syntax is: <Condition>/<attribute name>/<value> Multiple attribute conditions may be added:

37 Custom Location Service API Developer's Guide 37 API Reference <Condition>/<attribute name>/<value>/<operator>/<condition2>/<attribute name2>/<value2> Conditions Condition [x] Description Exact match [>] Greater than [<] Less than [<=] Less or equal [like] [like*] [*like] [null] [not] Handled as: like %value% Handled as: like value% Handled as: like %value Value of attribute is null Value of attribute is not equal to Operators Operator [AND] [OR] Description Logical AND between given conditions Logical OR between given conditions Attributes The following attributes can be used within the query parameter: name1 name2 name3 customerlocationid customerid displaylat (latitude in coordinate attribute) displaylon (longitude in coordinate attribute) navlat (longitude in routecoordinate attribute) navlon (longitude in routecoordinate attribute) description housenumber street

38 Custom Location Service API Developer's Guide 38 API Reference city state postalcode country county countryname phone fax Examples Below is an example of a querytype searching for stores in layer Nokia Stores that are in Berlin which have the word "phone" in their name: &app_code=ajknxv84fjrb0kihaws0tg &coord=52.51,13.4 &radius=20000 &layerid=30 &query=[like]/name1/phone/ Below is an example of a querytype searching for stores in layer Nokia Stores that are in Berlin which have as postal code either or 10178: &app_code=ajknxv84fjrb0kihaws0tg &coord=52.51,13.4 &radius=20000 &layerid=30 &query=[x]/postalcode/10117/[or]/[x]/postalcode/10178/ Response Data Types Articles in this section provide a comprehensive reference to Response Data Types used throughout the Custom Location Service API. LocationType The LocationType specifies the attributes of a POI.

39 Custom Location Service API Developer's Guide 39 API Reference Attributes Attribute Type Description coordinate GeoCoordinateType Geo-location of the location. city String Densely populated municipality. country String Name of the state as an ISO 3166-alpha-3 country code. county String Second subdivision level below the country For example: USA: County Germany: Kreis customerattributes Array Array of string for custom attributes. customerlocationid String Unique identifier set by customer for the location. description String The description of the location. distance Number The address of the location. String The address of the location. fax String The fax number of the location. housenumber String The house number of the location. name1 String Name of the location. name2 String Field to store additonal information to the name of location. name3 String Field to store additonal information to the name of location. phone String The phone number of the location. postalcode String Postal code as defined by the government of the country. state String Includes the first subdivision level below the country. Where commonly used, this is a state code such as CA for Califonia. street String The street name. routecoordinate GeoCoordinateType Geo-location of the location for use in calculation of a route to the location Usually the same as coordinate but it is possible coordinate is not accesible from the road. Example Below is an example of a locationtype resource with many of the above attributes: "customattributes": [

40 Custom Location Service API Developer's Guide 40 API Reference name: "division", value: "HERE" ], "name1": "Nokia House 1", "street": "Invalidenstrasse 116", "city": "Berlin", "postalcode": "10115", "phone": " ", "fax": " ", "customerlocationid": "12345", "routecoordinate": "latitude": , "longitude": "coordinate": "latitude": , "longitude": "country": "DEU", "description": "Mo. - Fr.: #08:00-19:00 Sat., Sun: closed" GeoCoordinateType The GeoCoordinateType represents a geographical position. Such a location is a place on Earth north or south of the equator. Latitude or Longitude is a xs:double type with the following restrictions: Must satisfy: -90 value 90 Unit: decimal degrees Reference System: WGS 84 Precision: 7 positions after decimal point, additional positions are ignored Example Below is an example of a GeoCoordinateType response: "locations": [... "coordinate": "latitude": , "longitude": "routecoordinate": "latitude": ,

41 Custom Location Service API Developer's Guide 41 API Reference ].. "longitude": Errors Custom Location Service API can return several types of errors: Error Message Description Bad Request Missing Parameters Required Parameters have not been provided. Bad Request There was a unique key violation. Check data input. Duplicate entry [value] for key [field] Bad Request Invalid Authentication Incorrect authentication credentials given in the request. See Acquiring Credentials on page 8 for more information. Unauthorized User not authorized for this action. User does not have permission rights for export. Error Examples Below you can find several examples of errors in JSON or XML: Missing parameters "status" : "Bad Request", "message" : "Missing parameters", "error" : "Required parameters have not been provided." Unique key violation "status" : "Bad Request", "message" : "There was a unique key violation. Check data input.", "error" : "Duplicate entry 'D ' for key 'unique_customer_loc_id'" Invalid authentication "status" : "Bad Request", "message" : "Error occurred", "error" : "Invalid authentication." Invalid search

42 Custom Location Service API Developer's Guide 42 API Reference <response> <message>unable to complete request.</message> <status>bad Request</status> <error>could not execute query</error> </response>