Developer's Guide Places APIdocumentation.developer.here.com/pdf/places_pub/1.0.11638/Place… · Places API Developer's Guide 2 Contents Contents Legal Notices.....4 Document Information.....5

Places APIDeveloper's Guide

Public Version 1.0.11638

Places API Developer's Guide 2► Contents

Contents

Legal Notices..........................................................................................................................................................4

Document Information.................................................................................................................................... 5

Chapter 1: Overview................................................................................................................................. 6Places API Overview....................................................................................................................................... 7

What is the Places API?.................................................................................................................... 7

Why Use Places API?..........................................................................................................................8

Places API Development Methods..................................................................................................9

Places API Main Features............................................................................................................................10

Places Search and Discovery........................................................................................................ 11

Places Information...........................................................................................................................12

Places Interaction............................................................................................................................ 13

Common Use Cases........................................................................................................................ 13

Chapter 2: Quick Start........................................................................................................................15Acquiring Credentials...................................................................................................................................16

Making Your First Request.........................................................................................................................16

Chapter 3: User Guide......................................................................................................................... 24Application Authentication......................................................................................................................... 25

Demo and Production Environments.......................................................................................................26

Utilization of Hypermedia Links................................................................................................................26

Place Sharing................................................................................................................................................. 27

JSON Response Patterns........................................................................................................................... 28

Location Contexts........................................................................................................................................ 29

External References.....................................................................................................................................33

Representation Modifiers...........................................................................................................................35

Page Size (size).............................................................................................................................. 35

Places API Developer's Guide 3► Contents

Text Format (tf).............................................................................................................................. 35

Image dimensions (image_dimensions)................................................................................. 36

Show references (show_refs).....................................................................................................36

Teasers (teasers).......................................................................................................................... 38

Pagination of Collections........................................................................................................................... 38

Localization.................................................................................................................................................... 38

Cross-Domain JavaScript Requests.........................................................................................................42

Gzip Compression........................................................................................................................................ 42

Categories...................................................................................................................................................... 43

API Implementation Check List................................................................................................................. 44

User Flow and Hypermedia Links.................................................................................................44

Source Attribution........................................................................................................................... 44

Displaying Content.......................................................................................................................... 46

Sponsored Search Results.............................................................................................................46

Client Activity Tracking...................................................................................................................46

Testing An App................................................................................................................................. 47

Prepare for Extensibility.................................................................................................................48

Search Engines................................................................................................................................. 48

Chapter 4: Reference............................................................................................................................49HTTP Request Headers...............................................................................................................................50

HTTP Request Headers...................................................................................................................50

Request Entrypoints.................................................................................................................................... 52

Search and Discovery Entrypoints...............................................................................................53

Additional Entrypoints.....................................................................................................................96

Entrypoint maturity and availability.......................................................................................... 104

Response Resources................................................................................................................................. 104

Media Types....................................................................................................................................105

Recurring JSON Structures......................................................................................................... 133

HTTP Status Codes....................................................................................................................... 158

Appendix A: Coverage.......................................................................................................................160

Places API Developer's Guide 4► Legal Notices

Legal Notices© 2015 HERE. All rights reserved.

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

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

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

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

prior written consent of HERE.

Trademark Acknowledgements

HERE and Nokia are trademarks or registered trademarks of Nokia Corporation.

Other product and company names mentioned herein may be trademarks or trade names of their

respective 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. HERE does not warrant that the content is error

free and HERE 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 the

negligence of HERE, shall HERE 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 HERE or an authorized representative has been advised of the

possibility of such damages.

Places API Developer's Guide 5► Document Information

Document Information

Product

Name: Places API

Version: Public Version 1.0.11638

Document

Name: Places API Developer's Guide

Id: 0e4b6c0-1435069816

Status: FINAL

Date: 2015-Jun-23, 14:32 (GMT)

Places API Developer's Guide 6► Overview

Chapter

1

OverviewTopics:

• Places API Overview

• Places API Main Features

This document describes the main features and characteristics of

the Places API component within the HERE Platform. Specifically, it

describes the entry points, main elements, critical resources and

other key aspects of the RESTful version of the Places API. Other

API delivery types (such as Web APIs like the Maps JavaScript API,

or Native APIs like the Hybrid places API), while still incorporating

some RESTful principles, can offer slightly different or additional

functionality.

This document is intended for API users with beginner to expert

levels of knowledge and experience with APIs . As such, the

document contains in depth descriptions of the main entrypoints

via headers, their elements, and the responses for each in the

JSON open standard. In addition, this document explores the

functions of common use cases, and exceptional or important use

cases. To help orient new clients, at the beginning of the document

there is also a quick synopsis of the HERE Platform and the Places

API role within that platform along with an explanation of how the

REST API differs from other Places API offerings.

For more introductory information about the Places API

component, and the HERE Platform in general, please see the HERE

Platform White Paper. For more advanced level instruction and

documentation for developers of all HERE components, please see

the resources at https://developer.here.com.

https://developer.here.com


Places API OverviewHERE Places API is a web service that can be accessed directly or through the Hybrid API. The API

allows users to search and explore places in the same way as, for example, in HERE Maps, but allowing

you to retain your application-specific look and feel. It is one component within many offered in the

HERE platform (such as Maps API, Positions API, Directions API, etc.) and is designed to communicate

seamlessly with the other APIs to provide full static or dynamic Place search or explore solutions.

What is the Places API?The HERE Places API is a RESTful web service API that you can call from your applications to let your

users search for and explore places in much the same way as HERE Maps, but in your application

with your own look and feel.

The Places API has a number of endpoints that center around two major features:

• Place discovery – search for places near your users

• Place description - get detailed information about the places your users are interested in

Within place discovery, the API has endpoints supporting a number of use cases, from which you can

select according to the needs of your application:

• search – location-aware search for places based on user-provided search terms

• explore – find interesting places in an area (either near the user or selected by the user)

• here – identify what place is at a given location

• around – similar to explore, but optimised for augmented reality visual exploration applicationslike Nokia LiveSight .

The API has a RESTful architecture and requests are given in a JSON representation. There are

resources representing entry points for each of the supported use cases, and responses contain

hyperlinks to related queries and place details. For example, when you submit a GET request to the

discover/search resource, you receive a JSON formatted reponse that contains a list of links to

place resources, among other things. By accessing one of the linked place resources, you can get

further detailed information about that place (again, in JSON), including ratings, images, reviews,

editorials, and owner content. This detailed place response also contains references to other related

places, allowing your users to discover other places relevant or related to their original search.

http://here.com

http://360.here.com/2012/11/13/livesight-immersive-experiences-you-can-act-on/


Why use the Places API?The HERE Places API provides a simple, future-proof way to grant your application's users access to

the latest information about tens of millions of places all over the globe.

By using the Places API, your application gains several crucial advantages, including:

• Coverage

• Reduced application complexity

• Forward-compatible API contract

Reduced Application Complexity

Collecting and — even more importantly — maintaining facts about tens of millions of places, while

simultaneously attaching useful and up-to-date information from various sources to them, is a

challenging task. Without the Places API, you would have to spend an enormous amount of your

resources just to collect, validate, standardize and maintain this data.

But having the data is only one side of the story. Once you have the data, you have to match this data

against your user's more or less arbitrary queries--which is further complicated by the many possible

interpetations of those queries. By taking implicit context information into account, you then have

to find the few matches (ideally: the one) most relevant to your users in their specific application

context.

Unless your core business is being a local search engine, it is quite unlikely that you want to invest the

massive amount of resources required to build a reliable place based search and discovery feature.

From the top down, the API comes with a set of features that make it very convenient for you to

ignore such concerns and embed our results in the best possible way into your application's UI.

We have already dealt with subtle yet critical questions like:

• What is the correct way to format addresses in Finland?

• How can I get images in sizes optimized to my UI?

• What is the most concise textual representation of a place's opening hours?

• What is the best graphical representation for a place on the map?

(and many others) so that you can focus your resources on the core domain of your application. .

Forward-Compatible API Contract

Because the nature of places in the real world are constantly changing, the API contract of the Places

API has been carefully crafted to reflect such fluidity. Although you will already find a huge amount of


valuable facts and information about places through the Places API, you should consider this as just a

starting point.

The API contract is designed in a way that allows us to introduce additional elements at any time,

without being forced to introduce a new version of the API contract. Even more importanly, when you

follow the guidance and best practices described in this document, your application user's will also

automatically receive access to those new features without you being forced to build and ship a new

version of your application.

For more information on this central feature, see Prepare for Extensibility on page 48.

Places API Development MethodsThe features of the places component are accessible via the following APIs, displayed below each

development method:

REST (only) API

• Places API – designed to build interactive applications which integrate online searchfunctionalities for Places of Interest (POI's); offers the best way to integrate address and POI-related search & discovery

• Geocoder API – designed to support geocoding and reverse geocoding use cases

◦ Batch Geocoder API – designed to process very large volumes of geocoding requestsasynchronously; this service is available in addition to the Geocoder API

Web APIs

• Maps API for Javascript– combines many of the functions of both Places API and Geocoder API(amongst other components) using the Javascript language

Overlapping Offerings for Places API and Geocoder APIThere is an intentional overlap between several of the Places API and Geocoder API. Because there

are several different offerings, it might be confusing as when to use a specific kind of Places API or

Geocoder API. This section explains the ideal use cases for each API.

When to Use RESTful Places API

Use RESTful Places API when:

• You want to build an interactive application which implements a 1 box search with the capabilityfor address search and poi search


When to Use Geocoder API

Use Geocoder API when:

• You want just location information (geocordinates and addresses) whether through geocoding(finding a latitude and longitude of a location via an address or text) or reverse geocoding(finding an address via a lattitude and longitude). This API uses less resources than the PlacesRESTful API, so it is preffered for the retrieval of location only data

• You are retrieving location data requests in batches of up to a few at a time online from users

When to Use Batch Geocoder

Use Batch Geocoder when:

• You want to get location data via geocoding or reverse geocoding for anywhere from thousandsof locations to up to a million

• You have a series of location data in an offline list that you want to geocode at once

This document is about RESTful API

The remainder of this document is about the semantics and functionality of only the RESTful Places

API. The other kinds of Places API will also use these semantics and functionality but may also offer

additional or slightly adjusted features. If you think that your application would require different use

cases, please see the documentation for the other Geocoder or Places APIs .

Places API Main FeaturesThe HERE Places API allows developers to build rich location-aware applications for places search,

discovery, information retrieval and interaction. These applications can be built for many platforms

including web and mobile. One application can support numerous use cases.

The Places API uses JSON representation and has a RESTful architecture. There are resources

representing RESTful entry points for each of the supported use cases, and responses contain

hyperlinks to related queries and place details (which are received in JSON).

For example, when a client application submits a GET request to the Places API using a Search &

Discovery entrypoint, the application receives a response that contains a list of links to places

resources (among other information). By accessing one of the linked Place resources, the application

can get detailed information about that place, including ratings, images, reviews, editorials, and

owner content (retrieved in the JSON format). This detailed place response also contains references

to other related places, allowing the applications users to discover other places relevant or related to

their original search.


User Flow

In order to properly guide the user through the features of the Places API, client applications are

required to provide the following User Flow:

1. Places Search & Discovery – users search and explore locations and places relevant to them ;users either repeat step 1 or move to step 2

Note: For more information on the features offered in this step, see Places Search andDiscovery. For more information on the appropriate entrypoint for a particular use case,see Common Use Cases

2. Places Information – users view the information available for a location or place; users either goback to step 1 or move to step 3

Note: For more information on this feature, please see Places Information

3. Places Interaction – users access place-related data, share and contribute place specificinformation; users go back to step 1

Note: For more information on this feature, please see Places Interaction

For more detail on the User Flow, including rationale and further explanation, see User Flow and

Hypermedia Links.

Places Search & DiscoveryPlaces Search & Discovery allows users to find places or addresses. Within Places Search &

Discovery, the API has entrypoints that support a number of use cases. Client applications can select

from the following entypoints according to the needs of the application: Search, Explore, Here and

Around.

Note: These entrypoints are the start for the User Flow. Once the user has selected one of

the entrypoints, the application should guide them to Places Information on page 12 or

back to Places Search & Discovery.

Search processes textual queries based on the user's input to find specific places. It answers

questions of "where are there places matching this [search term]" for an online search where a

search term can be a POI or an address. The user's input can contain:

• A Place of Interest (POI) category name, business or place name, or combination thereof, forexample Royal Sonesta or Hotel

• An address, complete or partial, for example, 40 Edwin Land Blvd, Cambridge, MA02141 or MA 02141

As a supplementary feature, suggestions are presented as the user types the search query. This is

based on the input text and the location context


The response, depending on query type, is a list of results that can include both matching places

and suggested alternative searches . The Places API generates results using machine-learning-

based relevance ranking. The search engine includes logic to recognize and compensate for common

spelling errors.

Explore retrieves a list of relevant nearby places for a Location Context. It answers the question

"What interesting locations are at this location?" The results presented to the user are ordered by

importance and popularity.

Here answers the questions "Where am I?" and "What's right here where I am standing?" The search

results consist of a list of places with addresses that lie within the vicinity of the search location.

The feature is typically used by applications that include "check-in" or "click on map to get more

information" facilities.

Around answers the question of "What can I see?" and "What direction are the main attractions?"

This feature is similar to the Explore entrypoint, but is specifically designed y for Augmented Reality

applications. The results are based on proximity, popularity, and importance.

Places InformationPlaces Information makes it possible for the user to examine additional information about places

returned by the Search and Discovery entrypoints. The user can decide to view the full details of a

place or choose or view related places.

Note: Places Information is the second step in the User Flow. Developers should move users

from Places Search & Discovery on page 11 to Places Information. Once a User is on

Places Information, developers should move them either back to Places Search & Discovery

or to Places Interaction on page 13. Clicking on a related place is considered the same as

returning to step 1

It is through the Places information step that users experience HERE's richest set of information

relating to a place. Beyond the basics such as the place name, address, category and contact

information, the user can access an extensible collection of information aggregated from multiple

sources such as user reviews, images and editorial descriptions. Additionally, an information set

about a specific place may contain links to other related places. Extended information may also come

with a reference to the source of that information.

The following information about a place is always supported:

• Base Attributes – includes name, location, categories, contacts, and a category icon

The following attributes might be included with a place. Given several different factors (for example

different suppliers of place information) , a place will have different kinds of additional attributes:


• Extended Attributes– includes information such as opening hours, payment methods, annualclosing dates/times, and disabled access (note that this list is indicative, not complete)

• Images– includes third-party and user-provided images; source information includes imagescaling

• Reviews– includes user-generated reviews and source information

• Editorial Descriptions – consists of third-party descriptions of a place, with source information

• Related Places Nearby – lists related places that may be of interest to the user

• Sharing URI – offers a link to the best available representation of the place on any operatingsystem, platform, or device

Places InteractionPlaces Interaction refers to features of the Places API that allows a client application to implement

user interactivity and to connect their applications to other HERE applications. The supported

interactions include:

Note: Places Interaction is the final step in the User Flow. After reaching the Places

Interaction step, clients should redirect users to Places Search & Discovery on page 11

This step completes the flow. After this point, it is up to the application to decide when to

start the flow again.

• Report a Place– the user can report a place in the wrong location, errors in place data, or a placethat should be removed

• Add Reviews–the user can add a review of a place

• Add images or ratings – the user can add images of a place or provide ratings

Common Use CasesWhen the client application makes Search & Discovery requests to the Places API, it is important

to select the appropriate entrypoint and to send the appropriate parameters and location context

information. The request resources section for the various entrypoints explains the parameters and

attributes of each entrypoint , and the Location Context section explains how to send the appropriate

location context information. Below is provided each entrypoint along with the most common use

cases associated with that entrypoint, along with the key parameters.

Explore Entrypoint - Finding Interesting Places Near the User

The Explore entrypoint is designed specifically for this purpose. Be sure to:

• provide the user's position in the Geolocation header


Here Entrypoint- Allow a User to "Check In" at a Place or Location

The Here entrypoint is designed specifically for identifying places at a specific position-in other

words, a "Check In" feature for an application. Be sure to:

• provide the user's position in the Geolocation header

Around Entrypoint - Overlay Interesting Places On a Image or Video

To get a mix of interesting and visible places around the user's position and overlay them on an

image or video captured by the user's device, use the Around entrypoint. The around entrypoint is

designed for use in "visual exploration" applications. It is similar to the explore entrypoint, but is

tailored specifically to return a mix of near and important places appropriate for this type of display.

When calling the around entrypoint be sure to:

• provide the user's position in the Geolocation header.

Places API Developer's Guide 15► Quick Start

Chapter

2

Quick StartTopics:

• Acquiring Credentials

• Making Your First Request - FindingPlaces Near a Position

Getting started with Places API is actually quite easy and the

process is explained in detail in the following section. This section

describes the necessary software and applications, authorization

codes, and a first use case to help you get started.


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

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

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

more details.

Making Your First Request - Finding Places Near aPosition

Once you have application credentials, you can make your first request to the Places API.

First you need to connect to the appropriate server. As mentioned in greater detail in Testing An

App, the Places API is hosted in two environments: the demo environment and the production

environment. The demo environment is available to help you get familiar with the API and assist you

during the development of your applications. The production environment should only be accessed

from shipped applications.

Since we are working with the API for testing purposes we should make requests to the demo

environment. In order to access the demo environment, use the URL http://places.cit.api.here.com.

Making a Request for Finding Places Near a Position

Now, imagine you want to build an application for a smart device or browser where a user can click

on any point on a map to find what is interesting in that area. In order to build such an application,

we will need geolocation data for the area that the user wants to query. Let's assume the user clicks

in that app somewhere in the middle of Manhattan, where the geolocation is latitude 40.74917 and

longitude -73.98529.

Based on that geolocation information, we can implement our first feature with the Places API by

using the explore entrypoint:

Note: We are using the explore entrypoint because it was specifically designed for findingplaces near where a user indicates an explicit location of interest.

http://places.cit.api.here.com/places/v1/discover/explore ?at=40.74917,-73.98529 &app_id=DemoAppId01082013GAL &app_code=AJKnXv84fjrb0KIHawS0Tg

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


&tf=plain &pretty=true

As you can see, the request URI contains a request to the demo environment through the explore

entrypoint (http://places.cit.api.here.com/places/v1/discover/explore), followed by several query

string parameters:

at The selected geo-coordinate as latitude, longitude (in this case where the

User has clicked)

app_id, app_code The credentials required to identify the app (see Acquiring Credentials on

page 16)

tf A flag that switches the presentation of rich text elements to plain text for

better readability

pretty A flag to enable pretty printing (so that we can read the result better)

You can find out more about the various parameters that can be used to influence the returned

representation in Representation Modifiers. For now, we are using an example with some of the most

common parameters and headers.

Breaking Down the JSON Response

The default response representation for all Search & Discovery entrypoints, like the explore

entrypoint we used above, is application/json. However if you use a web browser you will get an

HTML representation which is intended for exploring the API.

Note: Note that if an Accept header is set in the request and it does not match */*,application/json or xhtml+xml an HTTP 406 error response - "Not Acceptable" will bereturned

When using the URL in your HTTP client or browser for the explore entrypoint , you will receive

a JSON document containing a result list of places and information about the search context of

this particular query. For example, below is a list of places (along with search context information)

returned from the demo environment as rendered by a browser:

{ "results": { "next": "http://...", "items": [ "{ Library Hotel }", "{ Top of the Rock }" , "{ CHRYSLER Building }", "{ Hangawi }" , "{ Inn on 23rd }" , "{ Hotel Casablanca Inc }",


"{ St Patrick's Cathedral }", "{ Gramercy Tavern }", "{ Metro Hotel }", "{ The Ginger Man }", "{ Chelsea Pines Inn }", "{ Ritz-Carlton Central Park }", "{ Frick Collection }", "{ Rudy’S }", "{ Flatiron Building }", "{ Junior's Time Square }", "{ Inn New York City }", "{ Birdland Restaurant }", "{ 5 Napkin Burger }" , "{ Museum of Modern Art }", ] } ,"search": { "context": "{ h...}" } }

As can be seen in the example above, most browsers will return expandable links for each individual

place. Once expanded, each of these links displays additional base information (Base Attributes)

about that particular place. For example, if a user or application expands the information about the

CHRYSLER Building they will see :

{ "position": [ 40.7517 , -73.97583 ], "distance": 847, "title": "CHRYSLER Building", "averageRating": 4.714285714285714, "category": { "id": "going-out", "title": "Going Out", "href": "http://...", "type": "urn:nlp-types:category" }, "icon": "http://...", "vicinity": "405 Lexington Ave at 42nd St New York City 10017", "type": "urn:nlp-types:place", "href": "http://...", "id": "840dr5ru-08bf72d1a15f41228438fb017f83a84c" }

Some important fields to note for a place media type response:

• position describes the geolocation of this particular place

• distance describes the distance from the original query location and this particular place

• title gives the name of the place

• category explains the relevant category group for that place which helps describe it. All placeshave a category, for example eat-drink, going-out,sights-museums, and more.


• icon provides a URI for the relevant icon for this place category. For example, in the above case,the icon is the one for going-out

• type is a URI that describes the kind of resource (what are called Media Types in the Places API)that will be returned by the href

• href a URI that links to to the resource from where you can fetch more data about that place.For example, this can be used when the user selects that result item. In the above case, sincethe Media Type is a place, the returned information is additional data about that place (such ascontacts, reviews, additional address information, and more)

• id is the specific id number for this place

Implementing Request Results

For now, lets concentrate on the most critical of the above fields in order to give the user the results

they desire. In order to properly use the place information sent from the server, you will need to:

First, render the entire list of items that are returned in the Search Result media type in the User

Interface of your application. The search result media type starts with results, and contains

the attributes next (a URI link to the next page of places) and items (the current list of places) as

seen in the below example:

{ "results": { "next": "http://...", "items": [ "{ Library Hotel }", "{ Top of the Rock }" , "{ CHRYSLER Building }", "{ Hangawi }" , "{ Inn on 23rd }" , "{ Hotel Casablanca Inc }", "{ St Patrick's Cathedral }", "{ Gramercy Tavern }", "{ Metro Hotel }", "{ The Ginger Man }", "{ Chelsea Pines Inn }", "{ Ritz-Carlton Central Park }", "{ Frick Collection }", "{ Rudy’S }", "{ Flatiron Building }", "{ Junior's Time Square }", "{ Inn New York City }", "{ Birdland Restaurant }", "{ 5 Napkin Burger }" , "{ Museum of Modern Art }", ] } ,"search": { "context": "{ h...}" } }


After you have displayed the list of places and a link to the next possible list of places, give users the

capability to view information about each of the places on the current list by:

• rendering each place result in your application's User Interface using title object and the iconobject URI, and

• providing a link to the href object URI which the user can select

Just follow the flow

Now that your application's users have seen the place results, hopefully one of the places is so

interesting that your users are curious enough to request further details. When a user (or your

application) selects the href URI (or other hypermedia URIs that points towards further resources,

like view, value, src and others ) of the place, a JSON response is given with further data about

that place. Each item listed in this response, just like with each individual place, contains a URI that

links you to the resource from where you fetch more information when the user selects that result

item.

So, in order to allow a user to view any of these items (and any other related items down the line) all

you should do is take the URI in the given result item and use it as the next request to the Places API.

If you have an application like the JSONView extension installed in your browser, you can simply click

the URI.

Depending on the type of the selected item, you will then either receive detailed information on the

selected place or another search result list for the refined search request.

For example, if you take the place information for the CHRYSLER Building and the user wants

more information about that place, then provide the user the option to select the href object (or

some kind of UI equivalent, like a button). Once the user makes the selection, send the entire href

URI as the next request to the Places API. The application will then receive a JSON response like the

one below:

Note: The response shown here is shortened for the sake of space. See Places Media Typefor a full example.

{ "name": "CHRYSLER Building", "placeId": "840dr5ru-08bf72d1a15f41228438fb017f83a84c", "view": "http://...", "location": { "position": [ 40.7517 , -73.97583 ], "address": { "text": "405 Lexington Ave at 42nd St New York City 10017 USA", "house": 405, "street": "Lexington Ave at 42nd St", "postalCode": 10017, "district": "Midtown Center", "city": "New York City",


"country": "USA", "countryCode": "USA" } }, "contacts": { "phone": [ { "value": "+12126823070", "label": "Phone" } ], "website": [ { "value": "http://en.wikipedia.org/wiki/Chrysler_Building", "label": "Website" } ] }, "categories": [ "{ Going Out }", "{ Landmark/Attraction }", "{ Sights & Museums }", "{ Theatre, Music & Culture }"] , "icon": "http://download.vcdn.nokia.com/p/d/places2/icons/categories/05.icon", "ratings": { "average": 4.75, "count": 8 }}

Now, you display the information received to the user and provide them with links to any further URIs

in the response. In turn, with those URIs in that response, provide any displayble information and

links to any available URIs. And so on.

Note: Almost every URI has a type field next to it that explains the kind of resource that willbe retreived. These are the above refernced media types. Some non media type objectsalso contain label fields that provide similar information

This hypermedia mechanism is the most fundamental design principle of the Places API. You start

a usage flow by constructing the URI of the entry point of the use case you want to provide (in the

above example, explore) and then display the results to your users. Users then select a hypermedia

item they want to know more about and your application just uses the href attribute of the selected

item for the next request and then gets access to the required information.

So there's no need to know the URIs for all resources in your application's code. No need to construct

a URI with complex URI templates. Just follow the link, and we'll get you where you (and your users)

want to be.

Note: Please keep in mind, as pointed out in the User Flow, applications must guide usersthrough a flow of Search &Discovery, Information, and Interaction.


What's Next

As you've learned, the Places API provides you with a simple to use and consistent skeleton for your

application's user experience, yet you still have full control over the actual user interface design.

The hypermedia approach also allows you to easily familiarize yourself with our API: just follow the

links in the responses and you'll find most of the things you can use to build your application.

There is only one detail missing before you can build your own application: request your own

credentials (see Acquiring Credentials on page 16). While you are free to explore the API on our

demo instance as long as you want, the demo credentials will only grant you limited access. For full

access, you need to sign up for your own credentials. Your credentials can then be used on both

environments: demo and production. The production domain is:

places.api.here.com

During development, you should continue to use the demo instance, but once you ship your

application, you must switch to production. While requests against both environments are subject to

the same quota limits, only those against production will be reflected in the application statistics that

you find next to your application's registration info. And you don't want to miss the information on

how your application is used.

The Remainder of This Document

While you can learn a lot about the Places API by just playing with it, we still strongly recommend

you read the remainder of this document before you start implementing your application. Your

application's extensibility and maintainability will benefit dramatically when you learn about the

fundamental design patterns and apply the best practices that we outline in this document.

Also, you may want or need to leave the regular path outlined by the hypermedia links of the system.

While your application will never have to give up the beauty of the hypermedia pattern, we provide

you with simple mechanisms to adjust the behavior of the system to your application's needs.

You'll find this information in the following chapters:

Core API Features provides an in-depth tutorial for developers that guides you through the

concepts and best practices of the Places API using several simple examples.

References includes a detailed specification of all entry points, data types and other elements

that comprise the Places API.


Additional Resources

Playground You can browse an HTML representation of the API to get a feel for what it

provides. Just point a browser to

http://places.cit.api.here.com/places

Developer Forum We would love to get your feedback about Places API. Please join the conver-

sations in the developer forum

http://places.demo.api.here.com/places/

http://www.developer.nokia.com/Community/Discussion/forumdisplay.php?293-RESTful-Places-API

http://www.developer.nokia.com/Community/Discussion/forumdisplay.php?293-RESTful-Places-API

Places API Developer's Guide 24► User Guide

Chapter

3

User GuideTopics:

• Application Authentication

• Demo and Production Environments

• Utilization of Hypermedia Links

• Place Sharing

• JSON Response Patterns

• Location Contexts

• External References

• Representation Modifiers

• Pagination of Collections

• Localization

• Cross-Domain JavaScript Requests

• Gzip Compression

• Categories

• API Implementation Check List

The User Guide section explains necessary ideas or requirements

for developers of Places API to understand in order to build

an application that will work properly with the Places API. In

the following section, there is an explanation of additional

authentication methods as well as a description of requirements

for client applications.


Application AuthenticationApplications must send credentials to identify themselves to the Places API when making requests.

These credentials are a pair of values named app_id and app_code, which are obtained as

described in Acquiring Credentials on page 16. They can be sent either as query string parameters, or

using HTTP Basic Authentication.

Query string parameter application authentication

Applications can send the app_id and app_code as query string parameters. Note that as with all

query string parameters, the values should be URL-encoded when sent in this way. For example, the

complete URL for a search request for "Italian pizza" in Berlin might look like this:

http://places.cit.api.here.com/places/v1/discover/search?at=52.5310%2C13.3848&q=Italian+pizza&app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg

Note: Your application's requests will use its own unique app_id and app_code, rather thethe ones above. To obtain the credentials for an application, see Acquiring Credentials on page16.

HTTP Basic application authentication

Instead of sending the application credentials in URL query strings, the app_id and app_code can

be sent in the Authorization header using the HTTP Basic Authentication Scheme.

The Authorization header is constructed as follows:

• app_id and app_code are combined into a string "app_id:app_code"

• The resulting string is then encoded using Base64

• The Authorization method and a space, i.e. "Basic ", is then put before the encoded string.

Example of authorization header:

Header name Header value

Authorization Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Note: To use HTTP Basic application authentication your must send HTTPS requests.

When the application uses HTTP Basic Authentication the app_id and app_code query parameters

can be omitted.

http://tools.ietf.org/html/rfc1945#section-11.1


Demo and Production EnvironmentsThere are two environments for the Places API: demo and production. As outlined in greater detail in

Testing an Application, the demo environment is the environment used for all forms of testing and

development of applications. The production environment is only use for currently live applications.

The two environments are as follows:

Demo http://places.cit.api.here.com

Production http://places.api.here.com

Utilization of Hypermedia LinksClient applications interact with the Places API JSON representations using hypermedia links in the

resources.

Place

A hypermedia link is represented as a JSON object which has an href attribute. Other link attributes

may be present which give more details about the link (see the link object definition). For example, a

place resource contains links to the category resources associated with the place:

{ "name": "Max's Pizza Place", "placeId": "360u09tv-be16478e55314b338c551aab2651c9d3",

"categories": [ { "id": "restaurant", "title": "Restaurant", "href": "http://...", "type": "urn:nlp-types:category", "icon": "http://..." } ]

}


Category

The link object in the categories array points to the following category resource. Notice the

attribute names are different since link objects are not resources. For example:

{ "categoryId": "restaurant", "name": "Restaurant", "icon": "http://..."}

Type of Resource

All links to Places API resources indicate the type of the resource being linked to with the type

attribute. If a client is only interested in a specific resource, it should filter links based on the type

attribute.

A link may also be to an external resource type, in which case the type attribute is either MIME media

type or missing, not a type URI. An example for this is the via link object in an image or review object:

{ "via": { "href": "http://www.qype.fr/place/540502", "type": "text/html" }}

In the case that a link object doesn't contain a type attribute, clients that want to use such a link

should use the most universal http client available (usually a web browser) to open that link as it may

connect to any kind of web resource.

Places API link objects follow the convention that when a link object is an attribute value the attribute

name signifies the relation type. For example, the via attribute on a review object signifies that the

link is to the original document containing the review.

Place SharingThe link in the place.view attribute can be used to enable users to share a place with their friends.

The link points to a human-friendly representation of the place. The link is dynamic and may return a

different representation depending on the platform on which it is being viewed. For example, if it is

being viewed from a desktop browser, it will link to the place page in HERE Maps.


The example below shows a typical view link on a place which can be used when sharing:

{ "name": "Antipodes", "location": { ... }, "placeId": "276u33dc-3944a4748a62499cb795cf8bee349c9c", "view": "http://here.com/p/s-aWQ9Mjc2dTMz..."}

JSON Response Patterns

Optional Properties

This section describes the information that is available in request responses.

If there is no value for an attribute of an object, the attribute is omitted altogether. For example, in

the review object, the id, language,and via attributes are not necessarily present:

{ "reviewId": "ugc-bdc277eb-de94-48f0-bcb8-9e53034ee0d7", "date": "2012-03-12T17:36:56Z", "title": "some review", "rating": 5, "description": "some review description", "user": { "name": "anonymous" }, "language": "en", "supplier": { "id": "here", "title": "HERE User", "href": "http://...", "type": "urn:nlp-types:supplier", "icon": "http://..." }, "attribution": "Provided by HERE User"}

Check the reference documentation for each specific response object for information on which

properties are guaranteed to be present. Most objects (or their attributes) are listed as required or

optional.


Rich Text Properties

Properties that are intended to be displayed to the user contain rich text. For example, the "text"

attribute of the address object. HTML is currently provided as the default, and allows switching to

plain text for the entire response and/or selected fields. In the future there migh be more supported

formats, or more specification about the subset of HTML beings used.

Rendered Representations Of Complex Properties

Some attributes, like the address attribute of a place, have complex data structures for clients that

want to do something with this data. For clients that just want to display the information to the user,

there is a "text" attribute that can be presented directly to the user. This attribute is a rich text field.

{ "address": { "street": "22 Rue du Grenier Saint-Lazare", "postalCode": "75003", "city": "Paris", "countryCode": "FRA", "country": "France", "text": "22 Rue du Grenier Saint-Lazare\n75003 Paris\nFrance" }}

Location ContextsThe HERE Places API uses location information to provide results that are as revelant as possible

to your users. Location information is provided to the Places API in the form of location contexts.

Location context information is either explicitly provided by the user, e.g. by clicking on a map, or is

implicitly available to your application, such as the user's geoposition or the map viewport currently

displayed to the user.

All HERE entry points require you to provide at least one location context. It is strongly recommended

that you always provide all of the implicit location context information avaialble to your application,

and to additionally provide an explicit location context when the user action that triggers a request

includes explicit location information. When the user does not explicitly indicate a location context,

e.g. by performing a search query from a free-text input element, the best results are achieved

by sending all available implicit location context and not sending any explicit location context

parameters. See Best Practice on page 31 for more detail about what location context to send.


Explicit Location Context

When the user explicitly indicates a location to your application, for example by clicking on a map

position to trigger a discovery query at that location, your application should provide an explicit

location context to the Places API using one of the following query string parameters:

Name Availiability Format Description

at Always Position Specifies an explicit

position as a point

in Selected request types Circle or Bounding Box

or Polygon

Specifies an explicit

area

When an explicit location context is provided in this way, we recommend that you also send any

applicable implicit location context information ( as described below). While the explicit location

context will take precedence, providing additional implicit context information will ensure you get the

best results possible.

Implicit Location Context

Your application will often have location information available to it that is not explicitly provided by

the user, such as the user's geolocation or a map area currently being displayed to the user. Sending

at least one type of implicit location context information is required in the absence of an explicit

location context, and you are strongly encouraged to send implicit location context information to

ensure you get optimal results even when providing an explicit location.

Applications should always send the following implicit location context headers when the values are

known:

Name Format Description

Geolocation Position Specifies the physical position

of a user

X#Map#Viewport Bounding Box Specifies the map area currently

displayed to the user

As an example of a case in which you should rely on implicit location context information alone,

consider a user sitting on a train, browsing a map of their destination. Looking out of the window they

see a castle and want to learn more about it, so they use your application's search function with a

query of castle. What is the most important piece of location context information for this search

query? The user has not indicated an explicit location, and the most relevant location context could


be the user's current location obtained from the device's GPS unit, or the location currently visible

on the user's map. It is not obvious to the application which is the most relevant, and by providing

all of the relevant implicit location context information to the Places API, it can try to determine and

provide the most appropriate results.

Best Practice

To get the best results, applications should always send implicit location context information when

available, and only send an explicit location context parameter when the user has explicitly indicated

a specific location. Therefore, It is recommend that applications always send the X-Map-Viewport

header when the application is displaying a map to user, and always send the Geolocation header

when the user's position is known. This is sufficient in many use cases, and an explicit location

context (via a query string parameter) is often not required.

For example, suppose the application always displays a map to the user, and provides a textbox for

free-text search backed by the search entrypoint. If the user performs a search using this textbox,

the application should supply the X-Map-Viewport header, and if the user's position is also known,

the Geolocation header as well. The user hasn't indicated an explicit location related to their

search (other than possibly positioning the map viewport), so there is no need to specify an explicit

location context.

On the other hand, suppose the application also provides the ability to click on the map and find out

what is at that location using the Here entrypoint. In this case, the user has an explicit location by

clicking on the map, which the application should provide as an explicit location context in the at

query string parameter. The application should still send the implicit context information via the X-

Map-Viewport header (and the Geolocation if the user's location is available), but the explicit

location will take precedence for determining the primary location for the request.

Distance Calculation

Places in results have a distance field, which is intended to be the distance of that place from the

user or from an explicit reference point. If an explicit location context is provided the distance will be

calculated from the given position. In the absence of an explicit location context the position given in

the Geolocation header is used. If the only available location context is from the X_Map_Viewport, no

distances are returned.

Position Format

The Geolocation header (implicit context) and at parameter (explicit context) specify a position as a

'geo' URI. The position is given as comma-separated values for latitude and longitude (in the WGS 84

http://tools.ietf.org/rfc/rfc5870

http://en.wikipedia.org/wiki/World_Geodetic_System


coordinate system), and optionally altitude (in meters above sea level), and a semicolon-separated list

of position parameters.

Applications should specify the source for the position by passing one of the following values for the

cgen parameter:

• map for points on a map, for example, geo:53.12,10.15;cgen=map.

• gps for values from a GPS device, for example,geo:53.12,10.15;cgen=gps.

• sgps for shifted GPS coordinates from a device fulfilling the legal requirements in China, forexample, geo:53.12,10.15;cgen=sgps.

Uncertainty in the geo-coordinates should be given in the u parameter as the uncertainty in meters,

for example, geo:53.12,10.15;cgen=gps;u=100. This might be the uncertainty of a GPS

coordinate fix, or uncertainty resulting from the resolution of a map. An absolutely accurate position

should be specified with u=0. If the u parameter is not provided, the uncertainty is unspecified rather

than 0. For example, 39.91,116.40;cgen=gps;u=16 specifies a position derived from a GPS

device with an uncertainty of 16 meters.

Circle Format

A circular area can be specified as a location context by providing a position (as described in Position)

and an additional radius. The radius is given by setting the r parameter to the radius in meters. For

example,53.12,10.15;r=10500 specifies an area with a 10.5km radius.

Bounding Box Format

A bounding box can be used to specify a geographic area as a location context. The rectangle

spanning the area is specified in the WGS 84 coordinate system as four comma-separated values

in the following order: west longitude, south latitude, east longitude, north latitude. For example,

13.125,52.362,13.661,52.693 specifies a bounding box for Berlin.

Polygon Format (Experimental)

A polygon area can be used to specify a location context by providing a

set of at least four comma-separated coordinate pairs where the first and

the last one are the same (see WGS 84 coordinate system) For example,

53.5869,10.0014,48.1305,11.5615,52.5171,13.3853,53.5869,10.0014 specifies a

polygon area of Hamburg-Munich-Berlin.




External ReferencesThe concept of external reference allows you to mash up Places API features with services and data

provided by other systems in a bidirectional way:

• If you want to associate a place that you have found in Places API with information from another

system, Places API provides access to identifiers used by external systems. Depending on license

agreements that you might have with some external systems, you can interact with the external

systems using their identifiers.

• If you want to interact with a place in Places API that you found in another source, you are able to

lookup the Places API place with the help of the identifier used in the external system.

With those features we allow your application to combine multiple systems in your applications,

without spending a huge amount of resources on matching and de-duplicating of place content

coming from multiple sources.

Getting access to external identifiers

By default, external references are not exposed in the Place Media Type on page 110. To request

for certain external references, client applications have to use the Show References Representation

Modifier to tell Places API which external systems client applications want to integrate with.

For example, using Explore Entrypoint on page 59 to find hotels in San Francisco:

http://places.demo.api.here.com/places/v1/discover/explore?at=37.7851%2C-122.4047&cat=accommodation&app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg

Places API would return place-details links and one of the links refers to Hotel Palomar:

{ "results": { "next": "http://...", "items": [ { ..., "title": "Hotel Palomar", ..., "href": "http://places.demo.api.here.com/places/v1/places/8409q8yy-6af3c3e50bcb4f859686797b2be5773d;context=...", }, ... ] }


}

To expose HERE Core Maps identifiers, client applications could just add representation modifier

"&show_refs=pvid" to all provided URL in the search results before they fetch the place details:

http://places.demo.api.here.com/places/v1/places/8409q8yy-6af3c3e50bcb4f859686797b2be5773d;context=...&show_refs=pvid

The response then will contain the HERE Core Maps identifiers in the references attribute:

{ "name": "Hotel Palomar", ..., "references": { "pvid": { "id": "1048649872" } }, ...}

Certain places might have more than one external identifiers that refer to same place. These

additional identifiers are exposed in the alternatives attribute:

{ "name": "Hotel Palomar", ..., "references": { "pvid": { "id": "1048649872", "alternatives": [ { "id": "19435190" } ] } }, ...}

Looking up place details by external identifiers

Client applications could find places by it's external identifiers. To retrieve place by external

identifier, please see Lookup Entrypoint on page 96.


Representation ModifiersPlaces API media types allows client applications to adjust the presentation of the returned response

to suit their needs.

Applications can activate the various tailoring options by passing a series of options as additional

query string parameters to the request.

Note: Representation modifiers are resource-specific and therefore are not propagated tolinks in the response which point to a different resource type. This means that applicationsneed to add representation modifiers to all links received in a response except for those thatlink to the same resource type. For example, the URI in the next attribute.

Please refer to the sections on the individual media types for details on which representation

modifiers are supported for each type.

Page Size (size)The option defines the page size (maximum number of items) of all paginateble collections in

the response; if not provided, each collection may define its own reasonable default. Individual

collections may define a maximum page size and then use that instead of the provided value.

For example:

• In search results, the size option determines the maximum amount of result items to show on

each result list page (default: 20).

• In media collections such as media.images, the maximum number of images to return (default:

5).

Text Format (tf)Various attributes returned in responses are defined as rich text strings. With this option, clients can

define the format in which rich text attributes are exposed.

Supported values are:

• html : (default) The rich text is rendered as an XHTML fragment using a subset of the standard

HTML elements applicable for text rendering, including a, b, br, ul, ol, li, i, p, h? or img (only

used for inline-images).

• plain : The rich text attribute is reduced to a plain text representation.


Image dimensions (image_dimensions)When a resource provides a URI of image resources (for example, photos of a place) applications

are able to request specific maximum sizes of those images to match their UI and bandwidth

requirements.

The format is that of a comma-separated list where each element specifies dimensions for a scaled

image by providing either the desired width, desired height, or both.

Valid elements are:

• w\d+

• h\d+

• w\d+-h\d+

Examples:

• image_dimensions=w32-h32,w64-h64

• image_dimensions=w32-h32,w300

• image_dimensions=h200

The provided values are used as upper boundaries for the dimensions of the returned images. The

solution will never scale up small images and will maintain the aspect ratio of the original image.

If this option is used, the image objects in media.images.items contain a dimensions attribute,

which is a map containing links to the sized variants of the original image.

For example:

{ "src": "http://...", "dimensions": { "w32-h32": "http://...", "w64-h64": "http://..." }}

Show references (show_refs)show_refs allows applications to request place/location related ids of external systems to be

included in returned response.

The format is a comma-separated list of external system names.

The option can only be used when requesting the following media types:


• Place Media Type on page 110

Places API currently support the following external systems:

Name of the system Identifier Description

HERE Core Maps pvid HERE’s core content product

provides map and POI data for

most regions of the world. This

data product provides long term

stable identifiers, called PVID.

For the subset of map features

that are available through

Places API, that external

reference allows to correlate

information available in the two

products

HERE Venue Maps venues.* HERE’s venue maps product

provides indoor maps for

thousands of venues. It

provides three type of

identifiers:

• venues: All types of venue

IDs

• venues.venue: Venue IDs

• venues.content: Venue

content IDs

• venues.destination:

Venue destination IDs

All types of identifier can

be used to associate the

corresponding objects in the

venue maps product with Places

API

Facebook facebook


For more detailed information on External References, please refer to User Guide External

References on page 33

Teasers (teasers)The maximum number of places in search results that should have teaser information (e.g image URL)

included.

The format is numeric value (default: 0).

Pagination of CollectionsLarge collections are paginated (set into a list of pages) using hyperlinks to point to the next and

previous page of items. Collections are wrapped in a paginator object that provides access to the

pagination status as well as the items on the current page.

Whether the available attribute is present and the amount of the items within a page depends on

the use case. For example, in the future, when searching for an airport, the search resource may give

a response where the first page only contains results within a maximum distance. In this scenario, a

request for the next "page" could return results with a larger maximum distance. In other words, the

amount of results on a page are dependent on both the amount of results and use case criteria.

An example of a paginator object:

{ "available": 26, "next": "http://alphabet.com/page/3", "offset": 3, "items": ["d", "e", "f"]}

LocalizationWhere possible, the Places API will attempt to present the response data in a language specified by

the Accept-Language request header.

The Accept-Language header should contain the user's language preferences according to the

HTTP 1.1 specification. These preferences are used to select the best available translation for the

resource information. The sections below describe in more detail how these preferences influence

the response.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html


Content

Content such as place reviews and editorials and extended attributes of a place will be returned in the

requested language if translations are available for it. If there are no translations available, the Places

API will fall back to the next best alternative given the preferences chosen.

Given that the Places API aggregates content from different sources with v. Depending on the

availability of translations for each content source, it may be the case that a resource contains

content in different languages. In this case, the Places API will make a selection that best satisfies the

user's request given the available content.

Place Names and Addresses

Where available, exonyms of place names and addresses are returned. For example, if a user's

preferred language is English, search results containing places in Munich would have addresses using

the names Munich, Germany instead of München, Deutschland.

If a place (for example in Munich, Germany) has an alternative name in English, the English

name would be returned as the place name and the original name would be present in the

alternativeNames attribute.

Addresses (and vicinity in search result items) are formatted according to the locality of the place.

Labels and Ready-to-Display Strings

Labels, category names and ready-to-display strings such the attribution attribute will be

translated into the requested language, if a translation is available. Otherwise the default is English.

There are currently translations for the following languages:

Language name Accept-Language header value

Afrikaans af-ZA

Albanian sq-AL

Arabic ar-SA

Azeri (Latin) az-Latn-AZ

Basque eu-ES

Belarusian be-BY

Bulgarian bg-BG

Catalan ca-ES



Chinese (China) zh-CN

Chinese (Taiwan) zh-TW

Croatian hr-HR

Czech cs-CZ

Danish da-DK

Dutch nl-NL

English (British) en-GB

English (United States) en-US

Estonian et-EE

Farsi fa-IR

Filipino tl, fil, fil-PH

Finnish fi-FI

French fr-FR

French (Canada) fr-CA

Galician gl-ES

German de-DE

Greek el-GR

Hausa ha-Latn-NG

Hebrew he-IL

Hindi hi-IN

Hungarian hu-HU

Indonesian (Bahasa) id-ID

Italian it-IT

Japanese ja-JP

Kazakh kk-KZ



Korean ko-KR

Latvian lv-LV

Lithuanian lt-LT

Macedonian mk-MK

Malay (Bahasa) ms-MY

Norwegian (Bokmål) no, nb, nb-NO

Polish pl-PL

Portuguese (Brazil) pt-BR

Portuguese (Portugal) pt-PT

Romanian ro-RO

Russian ru-RU

Serbian (Latin) sr-Latn-CS

Slovak sk-SK

Slovenian sl-SI

Spanish (Mexico) es-MX

Spanish (Spain) es-ES

Swedish sv-SE

Thai th-TH

Turkish tr-TR

Ukrainian uk-UA

Uzbek (Latin) uz-Latn-UZ

Vietnamese vi-VN


Cross-Domain JavaScript RequestsOften, browsers prevent access to certain servers due to security restrictions. Cross-Domain

Javscript Requests allows developers to work around sercurity restrictions that would prevent an

application from contacting Places API directly. For example, certain location information might not

be retrievable without enabling this method. In order to allow full accees to servers, the Places API

provides a mechanism to enable client-side cross-origin requests that allow JavaScript resources to

be fetched from another domain.

For details on how this mechanism operates, see Cross-Origin Resource Sharing. Places API currenlty

uses all headers and parameters of this mechanism.

In order to support browser platforms which do not yet implement Cross-Origin Resource Sharing,

GET requests can alternatively be made using JSONP. To use JSONP, your application simply

supplies the name of its callback function in the callback query string parameter. When making a

JSONP request, parameters that would normally be sent as HTTP headers can be passed as query

string parameters instead.

For example, to use JSONP to request German-language results with a callback named

myCallbackFunction, you could make a request like the example below:

GET http://places.cit.api.here.com/places/v1/discover/search?at=52.5044,13.3909&q=restaurant&app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&pretty&callback=myCallbackFunction&Accept-Language=de

Note: The JSONP mechanism only works for GET requests. POST requests can only be madeusing the Cross-Origin Resource Sharing mechanism discussed above.

Gzip CompressionResponses provided by the Places API can optionally be compressed in the gzip format. Developers

are strongly encouraged to make use of this option, as it can have a major positive impact on the

responsiveness and performance of the client application by significantly reducing the response size.

Applications can request a gzip-compressed response in two ways. Applications can either set

the standard Accept-Encoding header or set the x-accept-encoding header. If x-accept-

http://www.w3.org/TR/2009/WD-cors-20090317/

http://en.wikipedia.org/wiki/JSONP


encoding is set, it overides Accept-Encoding; the syntax and content of both variants are the

same. They both conform to the standard accept-encoding header specification as set by the IETF.

Header name Header value

Accept-Encoding gzip

x-accept-encoding gzip

Note: When the response is gzip compressed, the Content-Encoding response header issent with a value of gzip.

CategoriesThe Places API maintains a large selection of categories that can be used to describe and group

places. The categories that are available do actually change over time and location, i.e. not all

categories are applicable at all places and categories will be added and removed in the future.

Place Categories

The Places API provides an entrypoint that can be queried to obtain a list of place categories that are

currently used in a given location Place Categories Entrypoint on page 97.

Therefore only a subset of the categories can be used as filters (for example with the Explore

Entrypoint on page 59). These filter categories are "fixed" and will not be removed in future

releases. At the moment, the subset is:

• eat-drink

◦ restaurant

◦ coffee-tea

◦ snacks-fast-food

• going-out

• sights-museums

• transport

◦ airport

• accommodation

• shopping

• leisure-outdoor

• administrative-areas-buildings

• natural-geographical

• petrol-station



• atm-bank-exchange

• toilet-rest-area

• hospital-health-care-facility

API Implementation Check ListClient applications must honour the terms and conditions of the Places API and follow recommended

design principles and best practices as outlined in this section. The following section highlights

some specific obligations that an application's code must honour. Failure to comply with these

requirements would violate HERE Platform terms and conditions and could cause an application to fail

when the feature set is enhanced in future versions.

User Flow and Hypermedia LinksAs mentioned in Places API Main Features on page 10, the Places API entrypoints are designed to be

used in a required User Flow. For each user flow, the entrypoints specifically described as Search &

Discovery Entrypoints in the documentation are always accessed first.

Other entrypoints, the Additional Entrypoints, can be accessed only by following links returned from

these root resources and accessing these links must be triggered by a deliberate and specific user

interaction with the link. For example, it is not permissible to download all pages linked to from

a response in order to try to improve performance. Nor is it permissible to write applications (or

'robots') to access and/or analyse the content from the Places API.

More specifically, clients may use URL templating only for root resources. The hyperlinks on these

resources contain URLs to follow in order to access other endpoints in the system. Unless specifically

documented otherwise, it is not permissible to use URL templating for these other entrypoints.

This is vital because by using URI templating, a request would not include critical information that

is required to create the response for the next request. The entrypoints documented will not be

changed without clients being informed. Other entrypoint URLs may change at any time. Using the

proper workflow by following links rather than URL templating is the only way to guarantee that an

application will not create broken links.

Source AttributionThe Places API gives access to content that is provided by a number of sources. Client applications

must display the source attribution next to the content. This requirement forms part of the terms

and conditions of the API.


Types of content that require attribution include images, reviews, editorials or a place itself. Below is

an example of an image object with attribution information:

{ "src": "http://...", "via": { "href": "http://originalArticle..", "type": "text/html" }, "supplier": { "title": "Qype", "href": "http://...", "type": "urn:nlp-types:supplier", "icon": "http://..." }, "user": { "name": "Max Mustermann", "href": "http://userProfile...", "type": "text/html", "icon": "http://userIcon..." }, "attribution": "Provided by <a href=\"http://originalArticle...\">Qype</a> user <a href=\"http://userProfile...\">Max Mustermann</a>"}

Attribution information is present in the form of link objects and as a ready-to-display HTML string

in the attribution field. The amount of attribution information will vary for different pieces

of content. Developers should refer to the reference documentation for the relevant media type

definition. For example, urn:nlp-types:supplier

For Clients Using the HTML Representation (Default)

The only step is to display the rich text in the attribution field next to the content.

For Clients Using the Plain Text Representation

If the platform does not allow display of embedded HTML, client applications will need to display the

following fields along with the content in the UI:

• the text given in the attribution field

• a link to the user's profile in user.href if available

• the user's icon in user.icon if available

• a link to the original source in via.href if available

Note: Not all of this attribution information is available for all content. However, what isavailable must be displayed.


Displaying ContentAll results returned by the API must be shown to the user, and they must be presented to the user in

the order that they were returned by the API.

Note: Developers can use the size parameter to request a certain number of results. Inother words, if you are only interested in displaying 3 results, then set the size parameter (inthe particluar entrypoint you want to use) to 3.

However, unless otherwise stated, developers can choose which fields of these results to display to

the user and which not to show. For example, it is up to the developer whether to show a field like

averageRating.

There are several required fields to display. Currently, developers are required to display:

• Source Attribution on page 44 when showing elements for which source attribution is provided

• Sponsored Search Results when they are present in the responses of search media types

• Full Places Data in the view URI - the UI must provide a link that allows the user of theapplication to access the full place details as provided by HERE in a web browser (or any otherplatform component that is capable of rendering HTML web resources). This link must use theURI provided in the view attribute of the place.

As a further restriction on the display of data, the results may not be used to create 'mash-ups' or

enhanced services, if the goal is to create similar products to compete with products available from

HERE or to incorrectly attribute content from the API. Similarly, making modifications, additions,

omissions, alterations, adaptations or derivative works of the content is not allowed.

Sponsored Search ResultsResult responses using the search media type may contain items in the result list marked as

sponsored. The application UI must contain a visual indication that allows users to distinguish

standard result items from sponsored results. Such an indication, for example, could be an icon,

a distinct background color, or other means of highlighting the difference between standard and

sponsored search results.

Client Activity TrackingApplications using Places API must enable services to log user activities such as search requests,

search result choices and other interactions.

Activity Tracking aims to improve the future Search & Discovery experience for the user. This

feature is based on anonymously provided data about user activities such as search requests. More

specifically Places API relies on feedback from users in order to improve the statistical model it uses


for building relationships between places, ranking places and providing recommendations. This data

also helps HERE to debug customers' technical issues.

To this end, client applications should send certain tracking data with each request they make. The

data is anonymous and the purpose is not to track individual users but to improve the results from

the Places API. For detailed information for how to appropriately track client activity, see below:

Cookies

Cookies are small pieces of data sent from services like the Places API to its clients in HTTP response

headers. The client application remembers this data, and when it later uses the same service, it sends

the cookie data back to the service. This is used to correlate different requests from the same user.

Client applications using the Places API are required to support cookies. The Places API uses

two cookies called NLP.PS and NLP.PP, which are sent in Set_Cookie response headers. The

application should then send these cookies in Cookie request headers with each subsequent request

until the date provided in the Expires field of the cookie. If such a date is not present, the cookie

should be sent only until the end of the session. While cookie handling can be manually implemented,

most HTTP libraries have built in support for it.

If the client application sends the DNT (Do Not Track) header to the Places API, then Places API will

not use information from cookies to track user activities, but might use them for other technical

purposes.

X-Forwarded-For Header

The X-Forwarded-For header should be provided in line with the Internet Engineering Task Force

(IETF) Forwarded HTTP Extension specification.

If requests from the client application are generated on a server rather than the user's device, the

server should send the client's IP address in the X-Forwarded-For header.

User-Agent Header

The User-Agent. in header should be provided to the Places API.

Testing An AppAll testing of application must be performed against the demo environment. Unless written

permission is provided, only live production applications may use the production environment.

The only testing that is allowed to use the production environment is integration testing. Any other

testing, such as load or performance testing, may only be done against the production environment

http://tools.ietf.org/html/draft-petersson-forwarded-for


with explicit written permission. This restriction is in place because testing can create extra load on

the system that may decrease its performance for other customers.

Testing to monitor the production environment is also not allowed. For example, periodically

checking the availability of the system is prohibited.

Prepare for ExtensibilityThere are various areas where future releases of the Places API will silently extend the volume and

types of information provided.

• Code must check the type attribute of the hypermedia links to ensure that applications don't tryto access media types that may be introduced in future releases.

• Clients should iterate over all contacts attributes of a place instead of picking specific ones toensure that applications can display all available contact mechanisms to users.

• Developers should iterate over all extended attributes instead of picking specific ones to ensurethat applications can display all available facts about a place to users.

• Developers should also iterate over all related places instead of picking specific ones to ensurethat applications can display places of all related types to users.

The API contract with client applications allows for extensibility. In general, clients can rely on the fact

that anything that is documented will remain valid at least within the major version of the API to which

the documentation applies. Anything that is not documented may change at any time.

Clients should be prepared to find new elements (content and features) in new releases of the API.

Developers are free either to ignore the new elements or – if the new elements are documented – use

them by applying generic patterns, without adverse impact on existing applications.

Developers should not be surprised to find undocumented objects, attributes, or fields in our

responses. The Places API offers feature parity to all users of the API; so even experimental features

that we initially develop with certain pilot API users will be visible from the start. But we will only add

them to the public documentation once the new feature has fully matured and proven to add value

for our users.

Please note that we may change the implementation of such features at any time, or even decide

to remove them from a future release. So unless you are fully aware of the application of these

features (and how to manage potential changes), it is best to wait to use the new features until they

are publicly documented. In other words, if a feature is not mentioned in this documentation we

recommend that you do not use it.

Search EnginesApplications using the Places API may not be exposed in such a way that search engines can crawl

content provided by the Places API.

Places API Developer's Guide 49► Reference

Chapter

4

ReferenceTopics:

• HTTP Request Headers

• Request Entrypoints

• Media Types

This section provides a detailed explanation of all the resources in

the Places API, including header information, all of the entrypoints,

every media type, and an explanation of the typical JSON Objects.

There is also description of the categories feature of Places API, as

well as all relevant http status codes.


HTTP Request HeadersHTTP Request Headers are a central feature for Places API. Via headers applications send Search

& Discovery requests (the first step in the User flow) to Places API. In return, applications get

respsonses in JSON format. Headers are also used for sending additional data after the initial

request, as well as customization information about the application, client informaiton about the

user, and much more.

The following section explains each of the headers in detail. This section also covers further

important concepts or principles that involve the use of headers.

HTTP Request HeadersImportant context information is passed to the Places API using optional HTTP request headers.

Wherever applicable the service relies on established and standardized headers, complementing

these with some additional private headers. Some of these directly affect the results, while others

help to optimize search results.

Header Name Description

Accept Specifies which media types are acceptable for the response (see

Accept header specification ). This header is ignored for JSONP

requests, which always have an application/javascript

result media type. Defaults to application/json.

• application/json results in a standard JSON response

• application/xhtml+xml results in an XHTML

representation of the JSON response in our playground UI

• text/html results in an HTML representation of the JSON

response in our playground UI

If the header is specified and no supported values are supplied,

the result will be an HTTP 406 Not Acceptable error response.

Accept-Language The user or client's preferred languages (see Accept-Language

header specification). This value is used to select the language of

content in the response. Default: en.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1






Date The user's local time, for example, Mon, 08 Aug 2011

11:58:17 GMT (see Date header specification).

User-Agent A string identifying the client user agent (see User-Agent header

specification), used for statistical purposes. If the Places API is

accessed from within a web browser, the browser should send this

information automatically. For other applications, it may need to

be explicitly set by the application.

Accept-Encoding Allows clients to enable compressed transfer of responses. The

only supported value is gzip. Clients are strongly encouraged

to make use of that option, as it can have a major impact on the

responsiveness and performance of the client application (see

Accept-Encoding header specification).

Geolocation The user's current position, formatted as a 'geo' URI as described

in the Position Format documentation. (see HTTP Geolocation

Internet-Draft). In the absence of an explicit location context, this

is used to calculate the distance from the user returned in place

results, and can act as an implicit location context. To ensure the

best results possible, client applications should always send this

header if it is able to determine the user's position.

X-Map-Viewport The bounding box of the map area currently visible to the user,

formatted as described in the Bounding Box Format on page

32 documentation. The viewport can act as an implicit location

context in the absence of an explicit location context. To ensure

the best results possible, client applications should always send

this header if it is able to determine the user's position.

X-Mobility-Mode This header allows an application to indicate the user's means of

transport, which can help Places API return better results:

• walk indicates that the user is on foot.

• drive indicates that the user is driving.

• none if the user is neither on foot nor driving.

X-MapVersion If an application is using HERE map tiles and displaying a specific

version of the tiles, the application can specify the map version






http://tools.ietf.org/html/draft-thomson-geopriv-http-geolocation-00



using this header to ensure that returned place coordinates

match the tiles you are using. The header value has the form

map-type:map-version. For example, nlp-tiles:2.1, nlp-

tiles:latest, or nlp-hybrid:8.0.47.117. If this header is

not sent, Places API assumes nlp-tiles:latest.

X-NLP-Testing Used signal that a request is a test request, which won't influence

our search relevance model.

• 1 identifies the request as a test request.

• 0 causes the request to be treated normally.

Defaults to 0.

Request EntrypointsThe Places API provides various resources that represent entrypoints into the places service.Search

& Discovery Entrypoints provide the fundamental entrypoints of the Places API and are the first step

in the User Flow. Additional Entrypoints occasionally occur before or after the typical user flow.

For each of the entrypoints below, there is a description of several aspects: Resource URI, Resource

Parameters, REST Resource Method, Request Example, Response Example, Response Media Type,

and Representation Modifiers.

• Resource URI – identifies the appropriate coding to be included in a request header in order to

use the resource (along with some of the parameters). For example, with the Search Resource

URI as /discover/search?q=...&[at=...], a developer needs to include /discover/

search with the parameters of q and at. To see how to organize each resource and the resulting

parameters, see the Request Example for reach resource.

• Resource Parameters – are base parameters for each resource. Each resource has different

parameters with differing levels of requirement which is explained under each respective

resource.

• GET Method – explains the kind of information (including important considerations) an

application recieves when using GET.

• Request Example – Is an example showing the proper way to send a request for the given

Resource. Note that the each example includes the Resource URI, the appropriate parameters for

that Resource URI (for example q and at for the Search resource), the authorization credentials,


app_Id an app_code, and some additional standardized REST parameters (like pretty for

pretty printing).

• Response Media Type- is the appropriate Media Type for that Resource. Media types are

additional resources that work with their parent resource to offer additional optional information

or usability.

• Representation Modifiers- API media types allow applications to adjust the presentation of the

returned response to suit their needs. Applications can activate the various tailoring options

by passing a series of options as additional query string parameters to the request. For each

Resource there is listed a number of parameters that are appropriate for that particular

Resource.

• Response Example – is an example response from the Places API servers for the given Resource

Entrypoint (for example for the “search” Resource Entrypoint). This information is represented in

the JSON representation.

Search & Discovery EntrypointsSearch & Discovery Entrypoints are the starting point for all application interactions with the Places

API. Such entrypoints allow for the retrieval of the full description of places (with the place resource

entrypoint) along with the searching or discovery of these places (among many other functions).

This section also includes a description of the Places Categories--a method to describe and group

places.

Search EntrypointThe Search Entrypoint processes text string queries based on the user's input to find specific

places. It answers questions of "what" and "where" for an online search of POI or address.

The results of the Search Entrypoint are sets of places that match a user's search term in a specific

location context (such as near a given location, around a user's current position or on the currently

visible map).

The Search Entrypoint is a Places API Core entrypoint.

Entrypoint URI

/discover/search


Entrypoint Parameters

Parameter Type Description

at Position (format:

latitude,longitude[;cgen=(map|

gps|sgps)][;u=\d+]);

required, unless one of

the Geolocation or X-Map-

Viewport headers or the in

are set.

Coordinates of search location expressed

as latitude, longitude. Additional

parameters can be passed which provide

more context such as the uncertainty and

how the coordinates were generated. For

example, "52.5304417,13.4111201",

"52.5304417,13.4111201;cgen=gps;u=100"

or "52.5304417,13.4111201;u=100".

For a full description, see the Location

Contexts documentation.

q String; required Plain-text search term. For example,

"restaurant" or "Brandenburger Tor"

refinements Boolean; optional If this flag is set to "true", result will

contain refined searches (Experimental).

A refined search helps the search engine

to deal with ambiguity in user queries.

This allows the application to suggest

refinements to the user's search.


• false

• true

cs Comma-separated list;

optional

A comma-separated ordered list of

category systems defining which

type of category systems should be

returned in the response. For example

cs=places,cuisines

GET Method

The GET method provides access to places matching the given term.


Representation Modifiers

The following options are available in this context:


size Number (non-negative

integer); optional

The maximum number of result items in

each collection.

tf String; optional; default:

html.

Text format. Determines how rich text

properties such as location.address.text

should be rendered.


• html

• plain

show_refs Comma-separated list;

optional

A list of one or more external system

names or reference types. This parameter

exposes place related external references

in response. For a full description see

Representation Modifiers documentation.

For additional information and examples, see Representation Modifiers on page 35.

Response Media Type

Responses to requests to this endpoint will have the urn:nlp-types:search media type. See the

urn:nlp-types:search media type documentation for details about the structure and content of

the response.

Request Example

http://places.cit.api.here.com/places/v1/discover/search?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&at=52.5044,13.3909&q=restaurant&pretty


Response Example

{ "search" : { "context" : { "title" : "Paris", "location": { "position": [48.85692,2.34121], "address": { "city": "Paris", "country": "France", "text": "Paris France" }, "type" : "urn:nlp-types:place" } }, "results" : { "items" : [ { "position": [52.5031395, 13.3906403], "distance": 0, "title": "Wilhelm & Medne", "averageRating" : 5.0, "category": { "title": "Restaurant", "type": "urn:nlp-types:category", "href": "http://..." }, "icon": "http://...", "vicinity": "Hedemannstrasse 14 10969 Berlin Germany", "href": "http://...", "type": "urn:nlp-types:place", "sponsored" : true, "id": "276u33d8-efb829f5b9464e5db8f286ff5fbf5643" }, { "position": [52.5046, 13.39087], "distance": 11, "title": "Speakers Corner", "averageRating" : 0.0, "category": { "title": "Restaurant", "type": "urn:nlp-types:category", "href": "http://..." }, "icon": "http://...", "vicinity": "Friedrichstrasse 31 10969 Berlin Germany", "href": "http://...", "type": "urn:nlp-types:place", "id": "276u33d8-b08d10d141e4405fbfdabbf017571401" } ] }


}

Suggest EntrypointThe Suggest Entrypoint represents lists of suggested search terms related to a given (partial)

search term and location context. This entrypoint is used to help users to provide suggested search

terms to the user while typing.

The Suggest Entrypoint is a Places API Core entrypoint.

Entrypoint URI

/suggest









are set.






example, "52.5304417,13.4111201",

"52.5304417,13.4111201;cgen=gps;u=100"

or "52.5304417,13.4111201;u=100".





GET Method

The GET method returns the list of suggested search terms related to the partial search term.

The method allows applications to provide to application users query completion suggestions as they

type.






integer); optional


each collection.


Response Media Type

Responses to requests to this endpoint will have the urn:nlp-types:suggestions media type.

See the urn:nlp-types:suggestions media type documentation for details about the structure

and content of the response.

Request Example

http://places.cit.api.here.com/places/v1/suggest?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&at=52.5304417,13.4111201&q=rest&pretty

Response Example

{ "suggestions": [ "Restaurant", "Restaurant Fleischerei Berlin", "Restorf, Lüchow-Dannenberg", "Rest area", "Restaurant Fleischerei", "Restaurant und Caffee Marrakesch", "Simplicity Restaurant", "Restaurant \"das pfeffer\"", "Las Olas-Restaurant GmbH & Co.KG", "Ars Vini 1. Berliner Fondue Restaurant", "Yam Yam Korean Restaurant", "Restaurant Blaues Band", "Kaffeehaus & Restaurant K\u00fcrbis Inh. Simon Eder", "Kaffeehaus & Restaurant Kurbis", "Restaurant Schmitz", "Restaurant Luso",


"www.partycard.de Club Bar Restaurant Kino Food Disco Sport Berlin", "Aapka - indisches Restaurant Berlin", "Restaurant Frarosa" ]}

Explore EntrypointThe Explore Entrypoint retrieves a list of relevant places nearby a given position or area. It answers

the question "What interesting places are in the viewport of the map?" The results presented to

the user are confined to those located in the current map view or search area and are ordered by

popularity.

Users can optionally provide categories of places they are interested in.

As with other entrypoints, the location to be used should be passed as a location context.

Note: Two critical parameters for the Explore Entrypoint entrypoint, at and in, are mutuallyexclusive and can't be passed at the same time.

The Explore Entrypoint is a Places API Core entrypoint.

Entrypoint URI

/discover/explore









are set.






example, "52.5304417,13.4111201",

"52.5304417,13.4111201;cgen=gps;u=100"

or "52.5304417,13.4111201;u=100".





in Area; required, unless one

of the Geolocation or X-

Map-Viewport headers or

the at parameter are set.

This parameter limits results to the

boundary of the specified area. The

search area can be expressed as:

• circle specified as a centre point

with latitude and longitude; and a

radius around that point. Format:

latitude,longitude;r=\\d+(\\.\\d+)?

[;cgen=(map|gps|sgps)][;u=\\d+]

• bounding box specified as 4

values, denoting west longitude,

south latitude, east longitude, north

latitude.

• polygon (Experimental)

defined by the coordinates (latitude,

longitude) of each of the polygon's

point. At least 4 coordinates (8

values) are required. The first and the

last coordinate must be the same



cat Comma-separated list;

optional

A comma-separated list of categorie

ids defining an OR-filter that all places

reachable through the resource must

match. For a list of supported categories,

see the Categories documentation.

Resources without an explicit category

set will use an appropriate set of

categories to find popular places within

the given location context.

drilldown Boolean; optional If this flag is set to "true", result set

will contain links to a further discover

query based on the current query. For

example result set may contain discover



query links that restrict result set to a

certain category (category drill down). To

request a further drill down or in this case

example, to expose subcategory filters on

chosen discover query, application has to

append the drilldown=true parameter to

the chosen discovery query link.


• false

• true


optional





cs=places,cuisines

GET Method

The GET method provides access to popular places for the given location context and matching the

category filter criteria.

Depending on the location context, the number of relevant places might be large. Therefore the GET

method may not only return places, but also suggestions for additional filter criteria that allow users

to interactively refine the classes of places they are interested in.





integer); optional


each collection.


html.



should be rendered.




• html

• plain


optional







Response Media Type



the response.

Request Example

http://places.cit.api.here.com/places/v1/discover/explore?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&at=52.50449,13.39091&pretty

Response Example

{ "search": { "context": { "location": { "position": [53, 14] } } }, "results":{ "items":[ { "position": [52.498619, 13.37681], "distance": 1159,


"title": "German Museum of Technology Berlin (Deutsches Technikmuseum Berlin)", "averageRating": 5, "category": { "id": "landmark-attraction", "title": "Landmark/Attraction", "href": "http://...", "type": "urn:nlp-types:category" }, "icon": "http://...", "vicinity": "Trebbiner 9\n10963 Berlin\nGermany", "type": "urn:nlp-types:place", "href": "http://..." "id": "276u33d8-1cca7647c58a49d3a86b884a923ffa19" }, { "title": "Eat & Drink", "icon": "http://...", "type": "urn:nlp-types:search", "href": "http://..." }, { "title": "Going Out", "icon": "http://...", "type": "urn:nlp-types:search", "href": "http://..." }, { "title": "Sights & Museums", "icon": "http://...", "type": "urn:nlp-types:search", "href": "http://..." } ] }}

Browse EntrypointThe Browse Entrypoint represent sets of places within a specific location context sorted by

distance.

The Browse Entrypoint allows users to request places around a given point. The Browse Entrypoint's

location context might be an explicitly given location, it might be implicitly defined by a user's current

position, or it might be implicitly defined by the currently visible map. Optionally, the places may be

restricted to a given set of categories (which acts as a filter in terms of what places get returned).

at and in parameter are mutually exclusive and can't be passed at the same time

The Browse Entrypoint is a Places API Premium entrypoint.


Entrypoint URI

/browse









are set.






example, "52.5304417,13.4111201",

"52.5304417,13.4111201;cgen=gps;u=100"

or "52.5304417,13.4111201;u=100".


















latitude.











name String; optional Plain-text name of place to search

for (Experimental). For example,

"Brandenburger Tor"


optional











optional





cs=places,cuisines

GET Method

The GET method provides access to places for the given location context and matching the category

filter criteria.





integer); optional


each collection.




html.



should be rendered.


• html

• plain


optional







Response Media Type



the response.

Request Example

http://places.cit.api.here.com/places/v1/browse?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&in=52.521,13.3807;r=2000&cat=petrol-station&pretty

Response Example

{ "search": { "context": { "location": { "position": [52.521, 13.3807] } }


}, "results": { "items": [ { "position": [52.528678, 13.36969], "distance": 1135, "title": "Steffen Kolberg Tankstellen Verwaltungs- und Betriebs GmbH", "averageRating": 0, "category": { "id": "petrol-station", "title": "Petrol station", "href": "http://...", "type": "urn:nlp-types:category" }, "icon": "http://...", "vicinity": "Heidestr. 65-68\n10557 Berlin", "type": "urn:nlp-types:place", "href": "http://...", "id": "276u33db-f2d1758f279348c1b134676cbcffdb81" }, { "position": [52.533179, 13.37976], "distance": 1357, "title": "Total Station Inh. Hans-Jürgen Klasen", "averageRating": 5, "category": { "id": "petrol-station", "title": "Petrol station", "href": "http://...", "type": "urn:nlp-types:category" }, "icon": "http://...", "vicinity": "Chausseestr. 98\n10115 Berlin", "type": "urn:nlp-types:place", "href": "http://...", "id": "276u33db-dfb5ec1fed614c7fa7f10df85bf986cf", } ] }}

Two-Box-Search EntrypointThe Two-Box-Search Entrypoint processes text string queries based on the user's input to find

specific places. It answers questions of "what" and "where" for an online search of POI or address.

The results of the Two Box Search Entrypoint are sets of places that match a user's search term in a

specific given location term.

The Two-Box-Search Entrypoint is a Places API Premium entrypoint.


Entrypoint URI

/discover/two-box



where String; required Location-text. For example, "DEU",

"Berlin" or "Berlin Mitte"

what String; required Plain-text search term. For example,


in Area; optional This parameter limits results to the











latitude.










optional







cs=places,cuisines

GET Method






integer); optional


each collection.


html.



should be rendered.


• html

• plain


optional







Response Media Type



the response.


Request Example

http://places.cit.api.here.com/places/v1/discover/two-box?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&where=Berlin&what=restaurant&in=6.2719,47.7468,14.7732,54.9044&pretty

Response Example

{ "results": { "items": [ { "position": [ 52.530227, 13.385666 ], "distance": 34, "title": "Restaurant Reinstoff", "averageRating": 3.7, "category": { "id": "restaurant", "title": "Restaurant", "href": "http://...", "type": "urn:nlp-types:category" }, "icon": "http://...", "vicinity": "Schlegelstraße 26c 10115 Berlin Germany", "having": [], "type": "urn:nlp-types:place", "href": "http://...", "id": "276u33db-4fa5ad4c78f5488d865a534344604dcb" }, { "position": [ 52.5304, 13.3867 ], "distance": 97, "title": "Auberge Maréchal Ney", "averageRating": 0, "category": { "id": "restaurant", "title": "Restaurant", "href": "http://...", "type": "urn:nlp-types:category" }, "icon": "http://...", "vicinity": "Schlegelstraße 22 10115 Berlin Germany", "having": [ "owner" ], "type": "urn:nlp-types:place", "href": "http://...", "id": "276u33db-e79fb3eb9a254aebab75cb7febb19eff"


} ] }, "search": { "context": { "location": { "position": [ 52.530411, 13.38527 ], "address": { "text": "Invalidenstraße 117 10115 Berlin Germany", "house": "117", "street": "Invalidenstraße", "postalCode": "10115", "district": "Mitte", "city": "Berlin", "stateCode": "Berlin", "county": "Berlin", "country": "Germany", "countryCode": "DEU" }, "bbox": [ 13.383422, 52.529287, 13.387118, 52.531535 ] }, "type": "urn:nlp-types:place", "href": "http://..." } }}

Browse by Corridor EntrypointThe Browse by Corridor Entrypoint represent sets of places along a route area sorted by distance

from starting point of the route.

The Browse by Corridor Entrypoint is a Places API Premium entrypoint.

Entrypoint URI

/browse/by-corridor



route Route (format:

\[start(latitude,longitude)|

0..n(latitude,longitude)|

This parameter limits search results to

the boundary of an area around a route.

A route consists of a start coordinate,

0..n turning coordinates and an end

coordinate. An optional width in meters



end(latitude,longitude)\]

[;w=\d+]); required

can be passed to provide off the route

max distance in meters, default: 1000m

The points should describe the geometric

shape of the route with high precision.

Especially, it’s usually not sufficient to

only pass maneuvre points as they would

be shown to the driver.

There are practical limitations to URL

lengths. Thus, if the route has more

than 120 points or URL length is over

2000 characters, the corridor shortener

endpoint should be considered to POST

the route.

An alternative way to reduce URL length is

to use Google's polyline encoding format.

In this case the square brackets should

be omitted. Width is supported in normal

way. For example, route=_ky~H_oaoA?

_ibE_th~C~mbJ;w=5000


required












"Brandenburger Tor"


optional




http://developers.google.com/maps/documentation/utilities/polylinealgorithm




cs=places,cuisines

GET Method

The GET method provides access to places for the given route and matching the category filter

criteria.





integer); optional


each collection.


html.



should be rendered.


• html

• plain


optional







Response Media Type



the response.


Request Example

Find petrol stations within a route corridor area between Berlin and Hamburg with 1 km off route

distance.



In the following request example, URL encoding is omitted for better readability. An actual request

would need to be URL encoded.

http://places.cit.api.here.com/places/v1/browse/by-corridor?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&route=[52.5160,13.3771|52.5111,13.3712|52.5355,13.3634|52.5400,13.3704|52.5626,13.3307|52.5665,13.3076|52.6007,13.2806|52.6135,13.2484|52.6303,13.2406|52.6651,13.2410|52.7074,13.1926|52.7045,13.0661|52.7191,12.9621|52.7636,12.8263|52.7861,12.8000|52.8335,12.7919|52.9002,12.7451|52.9708,12.6311|53.0526,12.5392|53.0867,12.5169|53.1146,12.4687|53.1334,12.4644|53.1415,12.4225|53.1666,12.3722|53.1785,12.3050|53.2570,12.1618|53.2893,12.0618|53.3000,11.9373|53.3316,11.8724|53.3463,11.8190|53.3669,11.7328|53.3725,11.6427|53.4154,11.5505|53.4309,11.4906|53.4342,11.4000|53.4655,11.3370|53.4873,11.2631|53.4860,11.2011|53.5110,10.9647|53.5128,10.8414|53.5495,10.6892|53.5692,10.5155|53.5596,10.4259|53.5682,10.2999|53.5571,10.2020|53.5672,10.1279|53.5534,9.9924];w=1000&cat=petrol-station&pretty

Response Example

{ "results": { "items": [ { "position": [52.53723, 13.37472], "distance": 277, "title": "Total", "averageRating": 0.0, "category": { "id": "petrol-station", "title": "Petrol station", "href": "http://...", "type": "urn:nlp-types:category" }, "icon": "http://...", "vicinity": "Chausseestraße 62 10115 Berlin", "having": [], "type": "urn:nlp-types:place", "href": "http://...", "id": "276u33db-cc5a1377043842ba8fc3c6acd0b36e7d" }, { "position": [52.542679, 13.37774], "distance": 822, "title": "Esso Station Mathias Fuhrmann", "averageRating": 0.0, "category": {


"id": "petrol-station", "title": "Petrol station", "href": "http://...", "type": "urn:nlp-types:category" }, "icon": "http://...", "vicinity": "Gerichtstr. 4 13347 Berlin", "having": [], "type": "urn:nlp-types:place", "href": "http://...", "id": "276u33db-be2f5afbd0e3458b9ad8410ed578fef7" }, { "position": [52.53391, 13.36515], "distance": 839, "title": "Total", "averageRating": 0.0, "category": { "id": "petrol-station", "title": "Petrol station", "href": "http://...", "type": "urn:nlp-types:category" }, "icon": "http://download.vcdn.nokia.com/p/d/places2/icons/categories/18.icon", "vicinity": "Heidestraße 19 10557 Berlin", "having": [], "type": "urn:nlp-types:place", "href": "http://...", "id": "276u33db-6bcb7b2e4fec41e9a295bba5709b00e4" }, ... ], "search": { "context": { "location": { "position": [52.5353, 13.3773] } } } }}

Key-by-key EntrypointProvides capability to search for places by prefix, honing the result set by incrementally adding more

characters

The Key-by-key Entrypoint is a Places API Premium entrypoint.


Entrypoint URI

/browse/keybykey









are set.






example, "52.5304417,13.4111201",

"52.5304417,13.4111201;cgen=gps;u=100"

or "52.5304417,13.4111201;u=100".


















latitude.














optional





cs=places,cuisines

GET Method






integer); optional


each collection.


html.



should be rendered.


• html

• plain


optional








Response Media Type



the response.

Request Example

http://places.cit.api.here.com/places/v1/browse/keybykey?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&at=52.5044,13.3909&q=rest&pretty

Response Example

{ "search": {...}, "results": { "items": [ { "position": [52.5031395, 13.3906403], "distance": 0, "title": "Wilhelm & Medne", "averageRating": 5.0, "category": { "title": "Restaurant", "type": "urn:nlp-types:category", "href": "http://..." }, "icon": "http://...", "vicinity": "Hedemannstrasse 14 10969 Berlin Germany", "href": "http://...", "type": "urn:nlp-types:place", "sponsored": true, "id": "276u33d8-efb829f5b9464e5db8f286ff5fbf5643" }, { "position": [52.5046, 13.39087], "distance": 11, "title": "Speakers Corner", "averageRating": 0.0, "category": { "title": "Restaurant", "type": "urn:nlp-types:category", "href": "http://..." }, "icon": "http://...",


"vicinity": "Friedrichstrasse 31 10969 Berlin Germany", "href": "http://...", "type": "urn:nlp-types:place", "id": "276u33d8-b08d10d141e4405fbfdabbf017571401" } ] }}

Voice Search EntrypointThe Voice Entrypoint processes text string queries based on the user's voice input to find specific

places. It answers questions of "what" and "where" for an online search of POI or address.

The results of the Voice Entrypoint are sets of places that match a user's search term in a specific

location context (such as near a given location, around a user's current position or on the currently

visible map).

The Voice Search Entrypoint is a Places API Premium entrypoint.

Entrypoint URI

/discover/voice









are set.






example, "52.5304417,13.4111201",

"52.5304417,13.4111201;cgen=gps;u=100"

or "52.5304417,13.4111201;u=100".






















latitude.










optional





cs=places,cuisines

GET Method







integer); optional


each collection.


html.



should be rendered.


• html

• plain


optional







Response Media Type



the response.

Request Example

http://places.cit.api.here.com/places/v1/discover/voice?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&at=52.521,13.3807&q=Find+me+Munich&pretty

Response Example

{ "results": { "items": [ {


"position": [ 48.13641, 11.57754 ], "bbox": [ 11.36772, 48.06307, 11.72033, 48.24597], "distance": 504295, "title": "Munich", "category": { "id": "city-town-village", "title": "City, Town or Village", "href": "http://...", "type": "urn:nlp-types:category", "system": "places" }, "icon": "http://...", "vicinity": "Bavaria Germany", "having": [], "type": "urn:nlp-types:place", "href": "http://...", "id": "276u281z-0b68e34139d74c61ac81ce05264aa4b6" }, { "position": [ 48.3583, 11.78427 ], "distance": 476701, "title": "Munich Airport (MUC)", "averageRating": 4.8, "category": { "id": "airport", "title": "Airport", "href": "http://...", "type": "urn:nlp-types:category", "system": "places" }, "icon": "https://...", "vicinity": "Terminalstraße West 85356 Oberding", "having": [], "type": "urn:nlp-types:place", "href": "http://...", "id": "276u287h-33978e49adeb4b2fa026780cb8d88bef" }, { "position": [ 52.511929, 13.45483 ], "distance": 5133, "title": "Munich Sedcard Berlin", "averageRating": 0, "category": { "id": "business-services", "title": "Business & Services", "href": "http://...", "type": "urn:nlp-types:category", "system": "places" }, "icon": "http://...", "vicinity": "Grünberger Str. 48 10245 Berlin", "having": [], "type": "urn:nlp-types:place", "href": "http://...", "id": "2768lxx5-73767d4de52d09c962f15cb017d9ef19" }


] }, "search": { "context": { "location": { "position": [ 52.521, 13.3807 ], "address": { "text": "Luisenstraße 35 10117 Berlin Germany", "house": "35", "street": "Luisenstraße", "postalCode": "10117", "district": "Mitte", "city": "Berlin", "county": "Berlin", "stateCode": "Berlin", "country": "Germany", "countryCode": "DEU" } }, "type": "urn:nlp-types:place", "href": "http://..." } }}

Suggestions EntrypointThe search Suggestions Entrypoint represents lists of suggested search terms and search links

related to a given (partial) search term and location context. This entrypoint is used to help users to

provide suggested search terms and search links to the user while typing.

The Suggestions Entrypoint is a Places API Beta entrypoint.

Entrypoint URI

/suggestions
















are set.

example, "52.5304417,13.4111201",

"52.5304417,13.4111201;cgen=gps;u=100"

or "52.5304417,13.4111201;u=100".





GET Method

The GET method returns the list of suggested search terms and links related to the partial search

term.

The method allows applications to provide to application users query completion suggestions as they

type.





integer); optional


each collection.


Response Media Type

Responses to requests to this endpoint will have the urn:nlp-types:suggestion-search-

links media type. See the urn:nlp-types:suggestion-search-links media type

documentation for details about the structure and content of the response.

Request Example

http://places.cit.api.here.com/places/v1/suggestions?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&at=52.5304417,13.4111201


&q=rest&pretty

Response Example

{ "suggestions": [ { "title": "Restaurant", "href": "http://.../places/v1/discover/search;context=cXVl...?&at=52.531%2C13.3848&q=Restaurant&...", "type": "urn:nlp-types:search" }, { "title": "Restaurant Reinstoff", "href": "http://.../places/v1/discover/search;context=cXVl...?&at=52.531%2C13.3848&q=Restaurant+Reinstoff&...", "type": "urn:nlp-types:search" }, { "title": "Roland von Arx + Stefan Zeuner GbR Restaurant Tellerfrisch", "href": "http://.../places/v1/discover/search;context=cXVl...?&at=52.531%2C13.3848&q=Roland+von+Arx+%2B+Stefan+Zeuner+GbR+Restaurant+Tellerfrisch&...", "type": "urn:nlp-types:search" } ]}

Around EntrypointThe Around Entrypoint represents sets of places within a specific location context, usually the

location of the user. This Entrypoint is intended for applications that employ features such as

augmented reality, where places around the user's location are displayed on a device. It is intended

to provide places that are likely to be visible to the user as well as important places that are further

away.

The Around Entrypoint allows users to request places near to a given point, based on a location

precision parameter. The places around that point are returned in order of proximity.

This Entrypoint is currently somewhat experimental and its behaviour and functionality are still

evolving so some further changes should be expected. Please check future documentation for

updates on this functionality.

The Around Entrypoint is a Places API Core entrypoint.


Entrypoint URI

/discover/around









are set.






example, "52.5304417,13.4111201",

"52.5304417,13.4111201;cgen=gps;u=100"

or "52.5304417,13.4111201;u=100".


















latitude.












optional






















• false

• true


optional





cs=places,cuisines


GET Method



This method is intended for applications such as augmented reality, where places around the user's

location are displayed on a device. It is intended to provide places that are likely to be visible to the

user as well as important places that are further away.








integer); optional


each collection.


html.



should be rendered.


• html

• plain


optional








Response Media Type



the response.

Request Example

http://places.cit.api.here.com/places/v1/discover/around?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&at=52.50449,13.39091&pretty

Response Example

{ "search": { "context": { "location": { "position": [53, 14] } } }, "results":{ "items":[ { "position": [52.498619, 13.37681], "distance": 1159, "title": "German Museum of Technology Berlin (Deutsches Technikmuseum Berlin)", "averageRating": 5, "category": { "id": "landmark-attraction", "title": "Landmark/Attraction", "href": "http://...", "type": "urn:nlp-types:category" }, "icon": "http://...", "vicinity": "Trebbiner 9\n10963 Berlin\nGermany", "type": "urn:nlp-types:place", "href": "http://..." "id": "276u33d8-1cca7647c58a49d3a86b884a923ffa19" }, { "title": "Eat & Drink", "icon": "http://...", "type": "urn:nlp-types:search", "href": "http://..." },


{ "title": "Going Out", "icon": "http://...", "type": "urn:nlp-types:search", "href": "http://..." }, { "title": "Sights & Museums", "icon": "http://...", "type": "urn:nlp-types:search", "href": "http://..." } ] }}

Here EntrypointThe Here Entrypoint helps users identify places at their location or at a point selected on a map by

returning places close to a given point, sorted by distance. Normally the closest known places are

returned, but if the uncertainty in the position is high then some nearer places are excluded from the

result in favour of more popular places in the area of uncertainty.

This entrypoint can be used to help users answer questions like "Where am I?" and "What is at this

point on the map?". You can use this endpoint to implement features like "check-in" (by identifying

places at the user's current geo-position) or "click on map to get more information".

As with other entrypoints, the location to be used should be passed as a location context.

The Here Entrypoint is a Places API Core entrypoint.

Entrypoint URI

/discover/here













example, "52.5304417,13.4111201",




are set.

"52.5304417,13.4111201;cgen=gps;u=100"

or "52.5304417,13.4111201;u=100".




optional






















• false

• true


optional





cs=places,cuisines



building Comma-separated list;

optional

A comma-separated list of 3D

building ids defining an OR-filter

that all places reachable through the

resource must match., For example

building=1,9000000000000870709.

Building filter can be used for indoor

navigation, e.g. searches in big shops/

malls. Building Ids are available for clients

who use Enterprise SDKs or have access

to map content by other means.

GET Method










integer); optional


each collection.


html.



should be rendered.


• html

• plain


optional









Response Media Type



the response.

Request Example

http://places.cit.api.here.com/places/v1/discover/here?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&at=52.50449,13.39091&pretty

Response Example

{ "search": { "context": { "location": { "position": [53, 14] } } }, "results":{ "items":[ { "position": [52.498619, 13.37681], "distance": 1159, "title": "German Museum of Technology Berlin (Deutsches Technikmuseum Berlin)", "averageRating": 5, "category": { "id": "landmark-attraction", "title": "Landmark/Attraction", "href": "http://...", "type": "urn:nlp-types:category" }, "icon": "http://...",


"vicinity": "Trebbiner 9\n10963 Berlin\nGermany", "type": "urn:nlp-types:place", "href": "http://..." "id": "276u33d8-1cca7647c58a49d3a86b884a923ffa19" }, { "title": "Eat & Drink", "icon": "http://...", "type": "urn:nlp-types:search", "href": "http://..." }, { "title": "Going Out", "icon": "http://...", "type": "urn:nlp-types:search", "href": "http://..." }, { "title": "Sights & Museums", "icon": "http://...", "type": "urn:nlp-types:search", "href": "http://..." } ] }}

Additional EntrypointsWhile using the Places API, developers will most commonly use the Search & Discovery entrypoints

since they always represent the first step in the User Flow. In addition to these entrypoints, there

are also Additional Entrypoints. The agent entrypoints allow for additional functionality on top of the

typical entrypoints required for the User Flow. This section describes each additional entrypoint in

detail.

Lookup EntrypointEndpoint provides ability to find a place by its foreign ID. Successful request results in redirect (HTTP

status code 302) to the place resource with context added.

For more information how to retrieve foreign IDs, please see User Guide External References on page

33

The Lookup Entrypoint is a Places API Core entrypoint.

Entrypoint URI

/places/lookup




source String; required Name of the foreign ID source in lower

case (e.g. pvid).


• pvid: Core POI

• venues.content: Venue content ID

• venues.destination: Venue

destination ID

• venues.venue: Venue ID

id String; required The ID of the requested place in foreign

system.

GET Method

GET method provides lookup ability.

Request Example

http://places.cit.api.here.com/places/v1/places/lookup?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&source=pvid&id=1115664033

Response Example

{ "href" : "http://places.cit.api.here.com/places/v1/places/276u33dc-3944a4748a62499cb795cf8bee349c9c;context=Zmxvdy1pZD0wMjI3Y2JiNy1kYzBmLTVjYTAtYjFkMC1hM2QyMmE3YTNhYjdfMTM5MDIzMDkwMjc0NF8wXzg2NTYmcmFuaz0w?app_id=addid&app_code=appcode" }

Place Categories EntrypointThis entrypoint is used to obtain the place categories available for a given location. This entrypoint

might be used to give a user a list of categories to choose from. The Place Categories Entrypoint

represents sets of locally relevant categories that are organized in a directed acyclic graph. The


category graph may change in the future and may differ depending on the location of the request. A

set of permanent, top-level, place categories can be found at Categories.

The Place Categories Entrypoint is a Places API Core entrypoint.

Entrypoint URI

/categories/places









are set.






example, "52.5304417,13.4111201",

"52.5304417,13.4111201;cgen=gps;u=100"

or "52.5304417,13.4111201;u=100".


















latitude.











GET Method

The GET method provides access to the place categories relevant to a given position. When no such

location is provided with the request, the response contains the graph with all place categories

recognized by the API.

Response Media Type

Responses to requests to this endpoint will have the urn:nlp-types:category-graph media

type. See the urn:nlp-types:category-graph media type documentation for details about the

structure and content of the response.

Request Example

http://places.cit.api.here.com/places/v1/categories/places?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&at=52.50449,13.39091&pretty

Response Example

{ "items": [ { "id": "eat-drink", "title": "Eat & Drink", "icon": "http://...", "type": "urn:nlp-types:category", "href": "http://...", "within": [ ] }, { "id": "restaurant", "title": "Restaurant", "icon": "http://...",


"type": "urn:nlp-types:category", "href": "http://...", "within": [ "eat-drink" ] }, { "id": "snacks-fast-food", "title": "Snacks/Fast food", "icon": "http://...", "type": "urn:nlp-types:category", "href": "http://...", "within": [ "eat-drink" ] }, ... ]}

Corridor Shortener EntrypointThe Corridor Shortener Entrypoint shortens Browse by Corridor Entrypoint's route parameter using

Google's polyline encoding format and additionally simplifies it with Radial-Distance algorithm (fast)

or Douglas-Peucker (high quality) algorithm if necessary.

With most of the devices it is not possible to use Corridor Entrypoint with URL of more than 2000

characters. Additionally, it is not recommended to have unencoded routes with more than 120

coordinates. To overcome the size limits, this entrypoint could be used to reduce the length of the

URL. The result of this entrypoint contains an URL that should be used for subsequent corridor

requests.

If encoding the coordinates is not sufficient to reduce URL length, simplifying algorithm is applied. In

the process of simplification deviation can emerge. To cover the same space of a original route we

provide a new corridor width.

The Corridor Shortener Entrypoint is a Places API Premium entrypoint.

Entrypoint URI

/browse/by-corridor/short




optional




http://developers.google.com/maps/documentation/utilities/polylinealgorithm











"Brandenburger Tor"


optional





cs=places,cuisines

POST Method

The POST method provides access to the object that contains simplified corridor route and new

corridor width. The request must have a Content-Type of application/json.





integer); optional


each collection.


html.



should be rendered.


• html

• plain




optional







Response Media Type

Responses to requests to this endpoint will have the urn:nlp-types:simplified-corridor

media type. See the urn:nlp-types:simplified-corridor media type documentation for

details about the structure and content of the response.

Request Example

Shortens URL for a route corridor with more than 150 coordinates and 2 km off route distance.

http://places.cit.api.here.com/places/v1/browse/by-corridor/short?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&cat=petrol-station&pretty

Request body

{ "route": "[49.2403332,9.1021303|49.2403793,9.1014647|49.2403686,9.1013467|49.2403042,9.1010356|49.2399824,9.0998662|49.2397356,9.0991151|49.2396605,9.0987933|49.2395747,9.0982568|49.2394996,9.0956497|49.2394888,9.0953493|49.2395639,9.0953171|49.2396069,9.0952528|49.2396283,9.0951347|49.2396069,9.0950274|49.2395639,9.0949631|49.2394888,9.0949309|49.2394137,9.0942764|49.239285,9.0937293|49.2386949,9.0917552|49.2385983,9.0913475|49.2384696,9.0907252|49.2382765,9.0895021|49.2382014,9.0887403|49.2381692,9.0882146|49.2381585,9.0872383|49.2381907,9.086498|49.2382872,9.0853608|49.2389095,9.0811014|49.2390382,9.0799642|49.2390811,9.0793526|49.2390811,9.078902|49.2390597,9.0785265|49.2389739,9.0777647|49.238888,9.0773678|49.2387378,9.0767884|49.2381692,9.0771747|49.2372572,9.0777433|49.2367744,9.0779901|49.2357981,9.0784514|49.2350578,9.0787196|49.2347252,9.0788269|49.2337489,9.0790951|49.2330301,9.0792239|49.2321718,9.0793204|49.2315602,9.0793419|49.2311311,9.0793312|49.2304659,9.0792775|


49.2300153,9.0792239|49.2293608,9.0790951|49.2289102,9.0789771|49.228245,9.0787303|49.2267323,9.0781295|49.2262924,9.0780008|49.2258418,9.0778935|49.2253911,9.0778184|49.2249298,9.0777862|49.2243505,9.0777969|49.2239213,9.0778399|49.2235243,9.077915|49.2228055,9.0781081|49.2223442,9.0782797|49.2218935,9.0784943|49.2214537,9.0787303|49.2208636,9.0791166|49.2203379,9.0795457|49.218353,9.0813804|49.2178166,9.0817988|49.2174625,9.0820348|49.2169046,9.0823352|49.2165399,9.082464|49.215982,9.082582|49.2155313,9.0825927|49.2152417,9.0825605|49.2148662,9.0824747|49.2145014,9.082346|49.2141366,9.0821743|49.213568,9.0817773|49.2131495,9.0814018|49.2129028,9.0811229|49.2124414,9.0804684|49.2122912,9.0802217|49.211905,9.0794706|49.2118406,9.0793097|49.2116368,9.0787411|49.2111003,9.0768421|49.210875,9.0758657|49.2113471,9.0756083|49.2114866,9.0755332|49.2116261,9.0754151|49.2117655,9.0752649|49.211905,9.0750611|49.2119908,9.0748894|49.2121196,9.0744603|49.2121518,9.0742886|49.2121732,9.0737844|49.2121518,9.0735269|49.2120445,9.0730655|49.2119265,9.0726471|49.211905,9.0724325|49.211905,9.0722179|49.2119265,9.0720141|49.2120123,9.0715635|49.2123878,9.0706515|49.212935,9.0692139|49.2132461,9.068259|49.2135251,9.0673578|49.2138791,9.0660918|49.2142224,9.0646434|49.2144048,9.0637422|49.2147052,9.0621114|49.2148447,9.0611351|49.2149949,9.0598154|49.2150915,9.0588284|49.2151451,9.0580988|49.2152417,9.0559852|49.2152309,9.0537429|49.2151451,9.051801|49.2149734,9.0499771|49.2147911,9.0484107|49.214201,9.0437651|49.2139864,9.0418124|49.2139006,9.0408254|49.2136967,9.0379715|49.2136216,9.0360832|49.2136002,9.0352464|49.2135894,9.0322745|49.2136323,9.0307617|49.2136645,9.0303433|49.2137074,9.0290129|49.2137933,9.0277362|49.2139864,9.0250862|49.2141151,9.0236485|49.214437,9.0206659|49.2147803,9.0178871|49.2154777,9.0130484|49.217838,8.9994013|49.2180741,8.9981461|49.219265,8.991183|49.2208743,8.9820421|49.221282,8.9795423|49.2216039,8.9773428|49.221915,8.9748108];w=2000"}

Response Example

{ "href": "http://.../places/v1/corridor?size=20&offset=0&app_code=...&app_id=...&route=agpkHiwpv@GdC@VJ|@~@hFp@tCL~@PjBNhO@z@ODGJCVBTFJNDLbCXlBtBhKRpAXzBd@rFLvCFhB@bEGrCQ`F{BrYYbFIxB?xADjANvCPnA\rBpBmAtDqB~Aq@bE{ArCs@`AUbEu@lCYjDSxBCtA@dCJxAH`CXxAVdCn@lHxBvAVxATxAN|ADpBAtAGnAOnCe@zAa@xAk@vAo@tBkAhBuAjKoJjBqAdAo@nB{@hAYlBWxAAx@DjAPfAXhA`@pBnArAhAn@v@zAbC\n@lAtCJ`@h@nBhBzJl@bE}Ar@[L[V[\[f@Qb@WrAGb@CbBBr@TzAVrABh@?j@Cf@QxAiAtDmB~G}@~Dw@rDeAzFeA`Hc@rD{@dI[bE]fGSdEIpCSdL@~LPbK`@lJb@vHtB`\\j@dKNdEh@xPLxJBfDBpQIlHErAGhGQ~Fe@pOY~G_ArQeAjPiCf]wMftAo@zFmFnj@aIbx@qArN_AvL}@xN;w=1000&cat=petrol-station;w=2097&cat=petrol-station", "newCorridorWidth": 2097}


Entrypoint maturity and availabilityPlaces API entrypoints can be divided into the three following categories:

• Core entrypoints are available to all users of Places API. They are fully supported and mature.Following are Places API core entrypoints:

◦ Explore –– Find recommended places in a location.

◦ Search –– Find places using a text query.

◦ Here –– Identify places at location.

◦ Around –– Find places around a location. Similar to explore, but optimized for 3D visual-exploration overlays.

◦ Suggest –– Get autocomplete suggestions for search queries.

◦ Place Categories –– Get place categories that are supported within a region.

◦ Lookup –– Find a place by non-Places API ID, e.g. PVID.

◦ Actions –– Report user interactions

• Premium entrypoints are mature but only available on request. Please contact your salesrepresentative to get access to them. Following are Places API premium entrypoints:

◦ Browse –– Find places with certain categories around a location sorted by distance

◦ Two-Box-Search –– Find places using two text queries.

◦ Browse by Corridor –– Find places with certain categories within a corridor area

◦ Corridor Shortener –– Simplifies route required for the corridor search

◦ Health –– Monitor the availability of the Places API

• Beta entrypoints don’t have guaranteed support and some features can be removed. Followingare Places API beta entrypoints:

◦ Cuisine Categories –– Get cuisine categories that are supported within a region.

Media TypesMedia Types explains the data structure types that are recieved in responses from and sent in

requests to Places API. All responses from the places api and requests bodies sent to the Places api

are in the format defined by a media type. For example, places, images, reviews, and more are are

sent and recieved as media types.

Because JSON format uses objects, and types of these objects can contain objects of their own, the

terms object and attribute can sometimes be used for the same item depending on the context

of that item. The definition of each term is as follows:

• object - an object is a structure containing attributes. For example, place is an object


• attribute - an attribute is a name and value that is part of its parent object. An attributes value

may be a string, another object, a hyperlink, or other information. For example, the place media

type has an attribute of alternativeNames which in turn has its own attribute of language

Media TypesThe resources provided by the Places API correspond to media types.

Search Media TypeThe search media type describes a step in a user activity to find/discover places.

Media Type URI

urn:nlp-types:search

Media Type Structure

The representation provides some information about the search request, but the primary

information in the search media type is a list of result items that guide users directly or indirectly to

the place(s) they are looking for. This media type has the following format:

{ "search": { //... }, "results" : { "items": [ //... ] }}

Attribute Type Description

results Object[DiscoverResultSet] a paginateable collection of

search result items.

search Object[SearchDescription] search location context that

the service has chosen for the

query.


Search Description


context Object[SearchContext] search context information

Search Context InformationThe primary information about the search context is the location context that the service has

chosen for the query. Usually the location context is derived from the explicit location parameters

of a discover activity. But sometimes the location context is also derived from other elements,

particularly from a user's search term. For example, when a user located in "Berlin, Germany" uses

the search term is "Restaurant in Paris", the search algorithm uses "Paris" as the search location.

When the location context of a place discovery is derived from one of the explicit location

parameters, the selected one is returned in the result. Depending on the endpoint used, it may also

contain an address or area of the location:

{ "search": { "context": { "title": "Paris", "location": { "position": [52.5044, 13.3909] "address": { "city": "Paris", "country": "France", "text": "Paris France" //... } }, "type": "urn:nlp-types:place" } //... }}

Result items of type search contain the context used for the search, which includes the following

attributes:


title String (formatted text); optional A (short) textual representation

of the item



location Object[SearchLocation] The location used for the

search.

type String The type of the resource

being linked to. The value is

either a valid MIME media type

or a URI. Places API internal

links always use a URN in the

namespace "nlp-types" for the

type attribute. If missing, the

link goes to a web resource that

is best opened in a universal

http client, like a web browser.

href String (URI); optional A hyperlink that refers to the

resource represented by that

result item.

moved Boolean; optional If true, the location used for

the search is different from the

one provided in the request.

Search Location


position Array[Number] A position given by latitude

and longitude, for example

[37.785141,-122.4047775]

address Object[Address]; optional The neighborhood of the

location used for the search.

bbox Array[Number]; optional An enclosing rectangle

that describes a range of

coordinates corresponding

to the location of the place.

Bounding boxes are typically



associated with places such as

cities and countries. A bounding

box is specified as an array

([West longitude, South latitude,

East longitude, North latitude])

according to the GeoJSON

geospatial data interchange

format.

Search Results Media TypeThe search-results media type is the structure used for the search results attribute.

Media Type URI

urn:nlp-types:search-results


The representation provides a paginateable list of result items that guide users directly or indirectly

to the place(s) they are looking for.

{ "results" : { "next": "http://...", "offset": 20, "items": [ //... ] }}


previous String (URI); optional The URI to the subresource

holding the previous page of the

collection. If the current page is

the first page of the collection,

the attribute is not present.

http://geojson.org/geojson-spec.html#bounding-boxes



next String (URI); optional The URI to the subresource

holding the next page of the


the last page of the collection,


offset Number (integer); optional Pages other than the first page

of a collection may include this

attribute. If present, it contains

the index of the first item in the

current page.

items Array[PlaceLink | SearchLink] There are several different

types of result items, but

regardless of its specific type,

each result item is a link object.

The goal of all discovery resources is to guide a user to a place, but this might not always be possible

or appropriate in a single step. For example, there may be too many candidates and therefore the

user might want to define additional criteria. Therefore some result items directly link to a place,

while others link to different resources that can be presented to the user and contain further links via

which the user will be linked to a place.

Each resource item has a `type` field identifying the type of page that it links to. The current

implementation of the Places API supports two types:

Place Media

Type on page110 (urn:nlp-types:place)

A user selecting the item in a Place Link will be directed to a place.

Search Media

Type on page105 (urn:nlp-types:search)

A user selecting the item in a Search Link will trigger a refined/more pre-

cise search query. This type of result item may appear when the amount of

reasonable matches is too large and the service can offer additional criteria

that may be used to refine the query.

Upcoming releases may introduce additional types (e.g. events). Clients must be prepared to handle

that situation and ignore any results that have a `type` that they don't know how to handle.


Place Media TypeA place response, identified by media type URI urn:nlp-types:place, contains all the information

available for a single place.

The place representation is extensible, with attributes divided into four sections:

Base attributes A set of predefined attributes providing core information about a place like

name, location, and categories.

Extended attributes An extensible collection of additional facts about the place

Media collections A set of rich media types aggregated from multiple sources

Related places References to other places related to the given place

Base attributes are members of the place object itself, while extended attributes, media collections

and related places are each grouped under their own subobject:

{ "name": "Rockefeller Center", //... other base attributes

"extended": { //... extended attributes },

"media": { //... media collections },

"related": { //... related places }}

Base Attributes

Base place attributes are members of the place object that provide core information about a place.


name String The name of the place

placeId String The unique identifier of the

place.



view String (URI) A URI linking to a representation

of the place that can be viewed

by end users. Applications must

provide at least a link for every

place that is fetched.

Note: The link in the

place.view attribute

can be used to enable

users to share a place

with their friends. For

more information on

this feature, please see

Place Sharing

alternativeNames Array[AlternativeName];

optional

alternative names, including

possibly those in other

languages.

location Object[Location] A description of the physical

location of a place.

attribution String (formatted text); optional A ready-to-display string

containing the source attribution

text for this place.

via Object[Link]; optional A link object to the external

website of the supplier of the

place. Where possible, this is

a deeplink to a page specific

to the place. As documented

in Source Attribution on page

44, this link must be used

for attribution when rich text

attribution is not being used.

supplier Object[Link]; optional A link to metadata about the

supplier of the place. The object



extends the standard link object

with an optional icon attribute

that contains a URI string

pointing to the supplier's brand

icon.

contacts Object[Contacts] An object listing means of

contacting the place

categories Array[Link]; optional An array of link objects to

categories assigned to the

place. A category link object


with an optional icon attribute,


pointing to an icon appropriate

for that category.

icon String (URI) A URI linking to a representation

of the place that can be viewed

by end users. Applications must

provide for every place they

fetch at least a link.

ratings Object[Ratings]; optional An object summarizing the user

ratings for a place. Deprecated.Replaced by Rating Media

Type on page 124 in media

collections

report Object[Link]; optional A link for getting options for

reporting a place because,

for example, it contains

inappropriate content or place

does not exists. The response

will have the report-options

media type.


Additional Place Information


extended Object[ExtendedAttributes];

optional

An object that provides further

information about a place

related Object[Related] An object that contains related

places in which users may also

be interested.

media Object[Media] An object containing collections

of media (images, reviews, etc.)

relating to the place.

Alternative NameEach alternative name is an object providing the alternative name as well as information on the

language of that name.


name String the alternative name

language String[language tag] the ISO language code

LocationA location object contains attributes to describe the physical location of a place.




[37.785141,-122.4047775]

locationId String; optional A unique identifier of the

location when assigned.

address Object[Address]; optional The neighborhood of the

location used for the search.
















format.

access Array[AccessPoint]; optional Coordinates to access the

location.

RatingsA summary of how users rated a place.


average Number The average rating of the place

across all users.

count Number (integer) The number of individual votes

on the place.

Extended AttributesIf a place has no information for a given attribute, the attribute is not present. If there is no extended

content at all for a place, the extended attribute of the place is not present.

In the future, more properties may be added to the extended section. Clients can safely loop over all

properties in this section and use the label and text properties to display all available information



in this section to the user. When an attribute represents a list of options, the text field separates the

elements with newlines.

The currently available extended properties may include third-party content as described in media

collections.

Some extended attributes may provide a structured presentation in addition to the label/text

representation (e.g. transitLines). They will be documented separately.


payment Object[ExtendedAttribute];

optional

A list of available payment

methods (such as cash, credit

card, direct debit, etc.)

openingHours Object[OpeningHours]; optional A list of hours during which the

place is open for business

annualClosings Object[ExtendedAttribute];

optional

A description of annual closing

dates such as holidays or other

special occasions

price Object[ExtendedAttribute];

optional

A price list.

fuelPrices Object[ExtendedAttribute];

optional

Fuel price list.

nearestLandmark Object[ExtendedAttribute];

optional

A description of the nearest

landmark

languagesSpoken Object[ExtendedAttribute];

optional

A list of the languages that are

spoken at the place

availableParking Object[ExtendedAttribute];

optional

A list of parking options

available nearby

smoking Object[ExtendedAttribute];

optional

Whether smoking is allowed

disabledAccess Object[ExtendedAttribute];

optional

Whether disabled access is

available

transitLines Object[TransitLines]; optional A list of available public

transport transit lines.



departures Object[Departures]; optional A list of next departures for

available public transport transit

lines.

blindGuide Object[ExtendedAttribute];

optional

Whether a public transport

stop has blind guides ('tactile

paving').

disabledParkingSpaces Object[ExtendedAttribute];

optional

Whether disabled parking is

available ('tactile paving').

womenParkingSpaces Object[ExtendedAttribute];

optional

Whether women parking is


sanitationFacilities Object[ExtendedAttribute];

optional

Whether women parking is


restRoomAvailable Object[ExtendedAttribute];

optional

Whether rest room is available

in parking place ('tactile

paving').

secureParking Object[ExtendedAttribute];

optional

Whether parking is secured,

indicates a gated and CCTV

parking ('tactile paving').

securityManned Object[ExtendedAttribute];

optional

Whether security guard is

available in parking place

('tactile paving').

electricalChargingPoints Object[ExtendedAttribute];

optional

Whether electric charging point

is available in parking place

('tactile paving').

elevator Object[ExtendedAttribute];

optional

Whether a place has an elevator.

escalator Object[ExtendedAttribute];

optional

Whether a place has an

escalator.


Extended AttributeEach extended attribute object has at least the following properties:


text String (formatted text) The information in rich text

which can be displayed directly.

If the text represents a list of

items, the items are separated

by a line break entity (if the text

format is html) or newline (if the

text format is plain).

label String A localized display label for that

extended attribute



information. As documented








Departures Extended AttributeDepartures Extended Attribute is associated with public transport stop/station and contains

information about scheduled departures from the place:












extended attribute











schedule Object[Schedule]; optional List of next public transport

departures.

ScheduleInformation about the departures of public transport stop/station. Departure items are paginated

based on page size parameter.


next String (URI); optional Link to the next set of

departures, if available.

items Array[Departure] List of departures.

lines Object(map of String to

TransitLine); optional

Dictionary of lines serving

departures shown in current

departure item list using line

name as a key.



operators Object(map of String to

PTOperator); optional

Dictionary of public transport

operators operating on this

stop/station using operator ID

as a key.

DepartureInformation about single departure. All times use RFC 3339 date-time format with timezone offset


line String Reference to the line in lines

dictionary.

scheduled Object[DepartureTime] Originally scheduled departure

time.

direction String; optional Direction of the departure on its

line.

exception String; optional An indicator for some

exceptional event happened to

this departure. Possible values

are redirected, replaced,

cancelled and additional.

operator String; optional A reference to the operator in

the operators dictionary.

real Object[DepartureTime]; optional A real time information about

departure time.

extended Array[ExtendedAttribute];

optional

A dictionary describing

additional features of the

departure. Supported keys

are bikeAllowed and

barrierFree.



DepartureTimeInformation about departure time.


platform String; optional Platform for the departure.

PTOperatorPublic transport operator.


id String Id.

title String; optional Name of the operator

supplier Object[OperatorSupplier];

optional

Supplier of the operator's

schedule information

links Object(map of String to

OperatorLink); optional

Dictionary of additional links

to be display next to departure

information of the operator.

Possible keys are operator,

agency and tariff.

OperatorSupplierSupplier of the public transport operator's schedule.


title String Name

OperatorLinkAdditional link associated with operator.



text String (formatted text) Text for the link.

url Object[Link] URI of the link.

Related PlacesThe related object contains related places in which users may also be interested. The following

properties may be available:


recommended Object[Link]; optional A link list of recommended

places for the given place which

shares the same structure as

the search results.

public-transport Object[Link]; optional A link list of nearby public

transports for the given place

which shares the same structure

as the search results.

venue Object[PlaceLink]; optional Venue where place resides

stops Object[Link]; optional A link list of public transport

connections in the given place

which shares the same structure

as the search results.

Media Object StructureA Media Object Structure contains third-party content collections. This object contains the

following attributes:


images Object[MediaCollection] collection of images of a place

editorials Object[MediaCollection];

optional

collection of editorial

description about a place



reviews Object[MediaCollection] collection of reviews about a

place

links Object[MediaCollection];

optional

collection of links for

interactions with a place

ratings Object[MediaCollection] collection of rating summaries

from suppliers

Review Media TypeThe review media type represents a review of a place.

Media Type URI

urn:nlp-types:review


reviewId String An identifier for the review

date String (RFC 3339 date-time);

optional

The date the review was

uploaded.

title String; optional The review's title

rating Number; optional A rating for the place, on a scale

of 1 to 5.

description String (formatted text) The review itself.

user Object[User]; optional The user who made the review

language String (RFC 5646 language tag);

optional

The language of the review


reporting a review because,


inappropriate content. The

response will have the report-

options media type.


http://tools.ietf.org/html/rfc5646#section-2



via Object[Link]; optional

supplier Object[Link]; optional

attribution String (formatted text); optional

GET Example

To retrieve an review, a client application can use the GET method. Here is an example for how to use

GET with the review media type:

GET /places/v1/places/{placeId}/media/reviews/{reviewId}

See below for an sample of a JSON response for the GET method:

{ "reviewId": "ugc-c425eb5b-3a69-4f45-8e2f-61ebd571fb1d", "date": "2013-05-08T03:13:12Z", "rating": 2, "description": "My review", "user": { "id": "05e...", "name": "Mustermann", "href": "https://...", "icon": "https://...", "type": "text/html" }, "language": "en", "supplier": { "id": "here", "title": "HERE", "href": "http://...", "type": "urn:nlp-types:supplier", "icon": "http://..." }, "via": { "href": "http://here.com/p/s-aWQ...", "type": "text/html" }, "attribution": "Provided by <a href=\"https://here.com/profile/users/05e...\">Mustermann</a> via <a href=\"http://here.com/p/s-aWQ...\">HERE</a>", "report": { "title": "Report this review", "href": "http://...", "type": "urn:nlp-types:report-options" }}


Rating Media TypeThe rating media type summarises the ratings assigned to a place by a particular supplier.

Media Type URI

urn:nlp-types:rating


count Number (integer); optional The number of individual user

ratings that contributed to the

average rating.

average Number; optional Average user rating.




Image Media TypeThe image media type represents an image of a place.

Media Type URI

urn:nlp-types:image


The image media media type has the following attributes:


src String (URI) A URL to the actual image

imageId String Identifier of image if uploaded

via Places API (this ID is returned

from an image upload response)




optional

The date the image was

uploaded.

dimensions Object(map of String to String);

optional

A map containing links to the

sized variants of the original

image.

user Object[User]; optional Details of the user who

contributed the image.


reporting an image because,


inappropriate content. The

response will have the report-

options media type.




GET Example

GET /places/v1/places/{placeId}/media/images/{imageId}

{ "src": "http://...", "via": { "href": "http://...", "type": "text/html" }, "dimensions": { "w32-h32": "http://...", "w64-h164": "http://..." }, "supplier": { "title": "Qype", "href": "http://...", "type": "urn:nlp-types:supplier", "icon": "http://..." }, "attribution": "Vom Qype"



}

Example POST Response

Below is an example image object, obtained from a URL in the following form:

POST /places/v1/places/{placeId}/media/images

Sample body for 201 - CREATED response status code:

{ "src": "http://...", "imageId": "ugc-4e5a8b9e-e50b-4a0d-bdae-eae278293887", "supplier": { "id": "here", "title": "HERE member", "href": "http://...", "type": "urn:nlp-types:supplier", "icon": "http://..." }, "attribution": "Provided by HERE member", "user": { "name": "anonymous" }, "delete": { "title": "Delete an image", "href": "http://...", "method": "DELETE" }}

Report Options Media TypeThe report-options media type describes reporting options for current place/image/review

Media Type URI

urn:nlp-types:report-options


inappropriate Object[Link]; optional A hyperlink to submitting an

inappropriate place/image/

review report.

non-existent Object[Link]; optional A hyperlink to submitting an

non-existent place report.


Report Post Media TypeThe report post media type describes the fields that need to be provided in order to report a

place or media item.

Media Type URI

urn:nlp-types:report-post


reason String The reason that a place/media

item is being reported, chosen

from the report options list

comment String A string in which the user

describes why the place/media

item is reported.

Category Media TypeThe category media type contains meta-information about a category.

Media Type URI

urn:nlp-types:category


categoryId String A unique category identifier. For

example, eat-drink.

name String The (localized) display name of

the category. For example, Eat

& Drink.

icon String (URI); optional The link to the category icon

system String Category system of the

category


Category Graph Media TypeThe category-graph media type represents a set of categories with parent-child relationships

between them.

Media Type URI

urn:nlp-types:category-graph


The representation provides a paginateable list of result items, each of which represents a category

node. Each node contains a link to the related category resource and the category ids of its parents in

the graph.

The search results is a paginateable collection of result items.

Each result item is a CategoryGraphNode.


items Array[CategoryGraphNode]

Category Graph Node


id String A unique category identifier

title String A localized title for the resource

to which the link refers. Clients

can display this title within their

application.

icon String (URI); optional

type String; optional The type of the resource












href String (URI) A link to the category resource

represented by this graph node

system String Category system of the

category

within Array[String] An array with the category ids of

this node's parents

Supplier Media TypeThe supplier media type contains meta-information about a supplier.

Media Type URI

urn:nlp-types:supplier


supplierId String A unique supplier identifier

name String The (brand) name of the

supplier

icon String (URI); optional A link to the supplier's brand

icon

Suggestions Media TypeThe suggestions media type contains a list of suggested search terms.

Media Type URI

urn:nlp-types:suggestions



For performance reasons, this media type doesn't use hypermedia links. Instead, clients processing

suggestion resources must use the suggested search term selected by their user as the value of the

q resource parameter to access a search resource.

The suggested search terms are exposed in a simple JSON object containing one attribute:


suggestions Array[String] An array of suggested search

terms.

Action Post Media TypeThe action media type describes a user interaction made against the Places API, for example, the

user clicking to the dial the phone number of a place.

Media Type URI

urn:nlp-types:action-post


meta Object[Meta]; optional Meta information about the

operation to report actions.

actions Array[Action] The actions that are being

reported.

Meta ObjectThis object contains meta-information describing the upload of action information that is taking

place. The meta object object has the following attributes:


currentTimestamp String[DateTime]; optional The time that the upload to the

Actions resource was made,

according to the clock from



which the actions' timestamp

field values came from.

Action ObjectThe action object represents an interaction made against a place. It has the following attributes:


resource String The URL in the Places API of the

place that the reported action

took place against. For example,

if the action reported is a phone

number being called, this is the

URL of the place which had its

phone number called.

types Array[String] List of action type URNs. Each

URN represents a type of

action, and begins with "urn:nlp-

actions".

timestamp String[DateTime]; optional A date and time string

representing when the action

took place. Its format is yyyy-

MM-ddTHH:mm:ss.SSSZ.

client String; optional An identifier used to identify

different client devices, for

example in cases where cookies

can't be provided by the client

device

parameters Object(map of String to String);

optional

A map for passing any extra

information with your action

post beyond what is contained

in the other fields.


Example

{ "actions": [ { "resource": "http://places.cit.api.here.com/places/v1/places/276u33db-5e332e9253f94042a3f086a2c19ea4bb;context=Zmxvdy1pZD1kNTQwYzMzZC1kYmI1LTU2NDQtYmI5Yi1jZDZlZjY4NWY4NmJfMTQwOTMwMTcyMzc2N18wXzUxMjEmcmFuaz0w?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg", "types": [ "urn:nlp-actions:placeselected", "urn:nlp-actions:viewplaceonmap" ], "timestamp": "2013-07-12T14:34:10.763+0100" }, { "resource": "http://places.cit.api.here.com/places/v1/places/276u33db-2c192376ea8541419d3e26bc4aa4f7f9;context=Zmxvdy1pZD1kNTQwYzMzZC1kYmI1LTU2NDQtYmI5Yi1jZDZlZjY4NWY4NmJfMTQwOTMwMTcyMzc2N18wXzUxMjEmcmFuaz0x?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg", "types": [ "urn:nlp-actions:placeselected", "urn:nlp-actions:drivingdirections" ], "timestamp": "2013-07-12T14:38:10.763+0100" } ]}

Action Type URNs

The following is a list of action type URNs that we suggest to use for some of the actions that we

expect to be made with Places API places. This list is not intended to be exhaustive.

Type Description

urn:nlp-actions:placeselected Select place from a result list.

urn:nlp-actions:viewplaceonmap View place on map.

urn:nlp-actions:emailclicked Click on place e-mail.

urn:nlp-actions:websitelinkclicked Click on place website URL.

urn:nlp-actions:phonenumberclicked Click on place phone number.

urn:nlp-actions:pinnedtohomescreen Pin place to home screen.

urn:nlp-actions:shareplace Share place to external service.

urn:nlp-actions:addplacetocollection Add place to collection/favourites.

urn:nlp-actions:walkingdirections Generate walking directions to/via place.


Type Description

urn:nlp-actions:drivingdirections Generate driving directions to/via place.

urn:nlp-actions:publictransportdirections Generate public transport directions to/via place.

urn:nlp-actions:navigationstarted Start to follow navigation directions..

urn:nlp-actions:destinationreached Arrive at navigation destination.

JSON Structure Objects and AttributesJSON Structure Objects and Attributes describes the various object and attributes an application will

receive in a JSON representation.

Because JSON format uses objects, and types of these objects can contain objects of their own, the

terms object and attribute can sometimes be used for the same item depending on the context

of that item. The definition of each term is as follows:

• object - an object is a structure containing attributes. For example, place is an object

• attribute - an attribute is a name and value that is part of its parent object. An attributes value

may be a string, another object, a hyperlink, or other information. For example, the place media

type has an attribute of alternativeNames which in turn has its own attribute of language

Link Object StructureA link object is used to refer to other resources. This object contains the following attributes:


id String; optional An identifier for the linked

object.

title String; optional A localized title for the resource

to which the link refers. Clients

can display this title within their

application.

href String (URI) The URI of the resource the link

object is referring to.













system String; optional The system name of the

resource being referenced

from.

accept Array[String]; optional List of accepted content media

type for POST request.

method String; optional Common method of HTTP/1.1

icon String (URI); optional A link to the icon for the linked

object, if one exists.

labels Object(map of String to

LabelNode); optional

An object containing a set of

fields with translations required

for the UI

Label NodeA label nodeis an object containing a set of fields with translations required for the UI. The label

node contains the following attributes: This object contains the following attributes:


label String The (localized) display name of

the field

values Object(map of String to

LabelNode); optional

The (localized) values/options

user can select from. Will be

provided for fields where user

http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html



should to choose one value

from provided options.

Collection LinkA link to a collection. Additional information is included that can be displayed to the user to help them

to decide if this is the collection they are interested in.


title String The display name of this

collection item.

href String (URI) A hyperlink that refers to the


result item.

type String The type of the resource










Favourite Place LinkA link to a favourite place.




[37.785141,-122.4047775]



distance Number (integer); optional Distance to the destination in

meters calculated as described

in Search Location and Distance

Calculation.

title String The (localized) display name of

this item.

underlyingTitle String; optional The (localized) original display

name of place item.

category Object[Link] A hyperlink to the primary

category of the place.

icon String (URI) Icon associated with this item.

vicinity String (formatted text); optional The textual description of the

location of the place; usually

derived from the address of

the place, but may also contain

any other description that helps

a user understand where the

place is located.













result item.



id String The unique identifier of the

place.

Place LinkA link to a place. Additional information is included that can be displayed to the user to help them to

decide if this is the place they are interested in. It has the following attributes:

{ "position": [48.8582557, 2.2947905], "distance": 881631, "title": "Eiffel Tower", "averageRating": 5.0, "category": { "id": "landmark-attraction", "title": "Landmark/Attraction", "href": "http://...", "type": "urn:nlp-types:category" }, "icon": "http://...", "vicinity": "5 avenue Anatole France\n75007 Paris\nFrance", "type": "urn:nlp-types:place", "href": "http://...", "id": "250u09tu-4561b8da952f4fd79c4e1998c3fcf032"}


position Array[Number] The latitude and longitude

of the place, for example

[37.785141,-122.4047775].

This latitude and longitude

is suitable for displaying the

place's position on a map.















format.

distance Number (integer); optional Distance to the destination in

meters calculated as described

in Search Location and Distance

Calculation.


this search item.

averageRating Number; optional The average rating for a place; it

is set to zero for places without

ratings.

category Object[Link]; optional A hyperlink to the primary

category of the place.

categories Array[Link]; optional An array of link objects to

categories assigned to the

place. A category link object


with an optional icon attribute,


pointing to an icon appropriate

for that category.

icon String (URI) Icon associated with this item.










place is located.

contacts Object[Contacts]; optional An object listing means of

contacting the place













result item.

sponsored Boolean; optional If true, indicates that this

search result is sponsored.

Applications MUST provide

some visual differentiation for

sponsored search results from

regular (organic) ones.

distant Boolean; optional If true, indicates that this

search result is outside the

search context information.

id String The unique identifier of the

place.

openingHours Object[OpeningHours]; optional A list of hours during which the

place is open for business


Transit Lines Extended AttributeTransit Lines Extended Attribute is associated with public transport stop/station and contains

information about the lines and destinations:










extended attribute











lines Object(map of String to

TransitLine); optional

Dictionary of public transport

lines using this stop/station.

destinations Array[Destination]; optional Dictionary of destinations

served from this stop/station.

TransitLinePublic transport line.



name String Name

category Object[TransitLineCategory];

optional

Category

style Object[TransitLineStyle];

optional

Styling guidelines for the line.

operator String; optional Operator serving the line.

TransitLineCategoryCategory information for the public transport line.


id String Unique id of the category.

title String; optional Localized name of the category.

localName String; optional Locally used name for the

category.

icon String; optional Icon for the category.

TransitLineStyleStyling for the public transport line. All colors are in hex format.


color String; optional The color value assigned to a

line.

textColor String; optional The text color that should get

used when the line color is used

as background color.

outlineColor String; optional Color of the border around the

line name.



iconShape String; optional An enum identifying the shape

style of the icon.

DestinationDestination served from station/stop.


destination String Name of the destination.

line String Name of the line serving the

destination.

AccessPointAccess point for the location. Purpose of the access point is to provide location that can be used e.g.

for navigation.


position Array[Number] The latitude and longitude of

the access point, for example

[37.785141,-122.4047775]

accessType String Type of access. As for now this

is always road.

Opening HoursThe opening hours object contains opening hours information for a place. The following properties

may be available:












extended attribute











isOpen Boolean; optional Boolean flag indicating whether

the place is currently open,

based on place's time zone.

structured Array[StructuredOpeningHours];

optional

List of structured presentations

for opening hours.

Structured Opening HoursStructure for holding opening hours based on the iCalendar specification.

This structure is defined so that it can describe more complex recurrence pattern like "Every 2nd

Saturday of the month from 10am to 10pm".

Unlike the iCalendar specification, the start value in our case does not contain a date part. We omit

the date part and immediately start with the T that is time section marker. For example, instead of

19700101T132000 you should expect a simpler T132000 equivalent.



start String String with a iCalendar DATE-

TIME value

duration String String with a iCalendar

DURATION value

recurrence String String with a RECUR rule

Search LinkA link to a further search query based on the current search query. It may contain, for example,

results restricted to a certain category or results for a suggested alternative search term.

This is an example of a result item representing a further search within a specified category:

{ "title": "Sights & Museums", "type": "urn:nlp-types:search", "href": "http://...", "icon": "http://..."}

This is an example of a result item representing an alternative suggestion for a search term:

{ "title": "Hotel Adlon", "icon": "http://...", "type": "urn:nlp-types:search", "href": "http://.../discover/search?at=52.53044,13.41112&q=Hotel+Adlon", "vicinity": "Berlin Germany", "modified": true}



this element.

icon String (URI) The URI of an iconic

representation of the item.



http://tools.ietf.org/html/rfc5545#section-3.3.51















href String (URI) A hyperlink that refers to place

discovery restricted by certain

group (e.g. category).

categoryId String; optional A unique category identifier.







place is located.

Result Display

The result items are ordered by relevance criteria that are appropriate in the context of a given

discovery resource. Applications presenting the result to their users should take care to reflect that

order in the way they display the results and should direct a user's attention to the first result items

first.

Client applications might want to display different types of result items in different ways. This

might imply that the application cannot reflect the global order of all result items. Still it is highly

recommended that the absolute first result item is the one first displayed to the user and that the

application reflects the relative order of items within each type.

User Object StructureUser objects contain additional attributes to describe a user.


Since a user object contains an href attribute, it is also a link object. This object contains the

following attributes:


id String; optional id

name String username

href String (URI); optional A hyperlink to user's profile.

icon String (URI); optional A hyperlink to user's avatar.

type String; optional The MIME media type of the

user's profile.

Media CollectionA media collection object provides access to additional content for a place.

All media properties are paginateable collections. When a given media collection is not available for a

place, the attribute for that collection is not present.

Some media elements might support additional features, in which case individual media elements are

also link-objects pointing to a full media resource with hyperlinks for the available features.


available Number (integer) The total number of items

available for a place, i.e. this

would be 50 for a place with 50

images.

Note: It is not possible

to always calculate

the total number of

elements in a collection.

So the attribute might

be missing, or just

contain an estimate.

Clients MUST not

rely on the presence

of the attribute but



instead rely only on the

existence of the next

attribute to find out

if additional items are

available.

offset Number (positive integer);

optional

Pages other than the first page

of a collection may include this

attribute. If present, it contains

the index of the first item in the

current page.

previous String (URI); optional The URI to the subresource

holding the previous page of the


the first page of the collection,


next String (URI); optional The URI to the subresource

holding the next page of the


the last page of the collection,


items Array[ActionLink | PlaceArticle

| PlaceEditorial | PlaceImage

| PlaceRatingsSummary |

PlaceReview]

An array containing the objects

of the current page of the

collection (eg. images). If a

collection is empty, the items

attribute is not present. The

type of the objects in the array

depend on the collection. It may

be for example Editorial Items or

Review Items


Action LinkThis object represents a link to a Uri for interacting with a place, for example booking a table at a

restaurant.


id String; optional Identifier of the link

url String (URI) The URI of the link.

title String The title of the link

supplier Object[Link] A link to metadata about the

supplier of the link. The object


with an optional icon attribute


pointing to the supplier's brand

icon.

PlaceEditorialA Place Editorial object provides access to editorial descriptions about the place.


description String (formatted text) The editorial content.


optional

A language code indicating what

language the review is in, if

known.




PlaceImageA Place Image object provides access to an image attached to the place.




src String (URI) A URL to the actual image

id String; optional Identifier of image if uploaded


from an image upload response)


image object of this item.

type String; optional


optional

The date the image was

uploaded.

dimensions Object(map of String to String);

optional

A map containing links to the

sized variants of the original

image.


contributed the image.

title String; optional A localized title to be displayed

for this element




PlaceReviewA Place Review object provides access to review and ratings given by other users.


id String; optional Identifier of review if uploaded


from an review uploaded

response).





review object of this item.

type String; optional


optional

The review date

title String; optional The title the user gave to the

review.

rating Number; optional The rating that the writer of the

review gave to the place. Note:

Ratings may come from various

systems with different rating

schemes. The value of that

attribute may not reflect the

rating scheme of the supplier's

service, but is adjusted to the

value range of the Places API

(1..5).

description String (formatted text) The review content. Depending

on the supplier it might not

display the full content and the

full review is only available on

the resource linked by the via

property.


contributed the review.


optional

A language code indicating what

language the review is in, if

known







Object Structure For Paginateable Collections

Paginateable Collections

User objects contain additional attributes to describe a user.

Paginateble collections are represented as individual pages (a slice of all elements of the collection)

that contain mechanisms to access the next page. For example:

{ "available": 26, "next": "http://alphabet.com/page/3", "offset": 3, "items": ["d", "e", "f"]}

Paginateble collections contain the following attributes:


items Array[Object]; optional An array containing the objects of the

current page of the collection (for

example, images). If a collection is empty,

the items attribute is not present. The

type of the objects in the array depend on

the collection.

next String (URI); optional) The URI to the subresource holding the

next page of the collection. If the current

page is the last page of the collection, the

attribute is not present.

available Number (positive integer);

optional

The total number of items available for

a place ie. if a place has 50 images, this

would be 50.

Note: It is not possible to always

calculate the total number of

elements in a collection. So the

attribute might be missing, or

just contain an estimate. Clients

MUST not rely on the presence



of the attribute but instead rely

only on the existence of the next

attribute to find out if additional

items are available.

offset Number (positive integer);

optional

Pages other than the first page of a

collection may include this attribute. If

present, it contains the index of the first

item in the current page.

Address Object StructureAddress information is provided in two ways: as a displayable, formatted address string as well as a

series of structured attributes.

{ "address": { "street": "22 Rue du Grenier Saint-Lazare", "postalCode": "75003", "city": "Paris", "countryCode": "FRA", "country": "France", "text": "22 Rue du Grenier Saint-Lazare\n75003 Paris\nFrance" }}

The address object contains the following attributes:


text String (formatted text) A displayable, formatted

address as rich text.

level String; optional Contains level of place inside of

a venue

building String; optional Building name

house String; optional House or street number.

street String; optional Street name (in practice may

also contain street number).



postalCode String; optional An alphanumeric string included

in a postal address to facilitate

mail sorting (a.k.a. post code,

postcode, or ZIP code).

areas Array[String]; optional An array of named areas below

the district and above street. In

some regions such areas might

also contain street names, when

individual street segments have

names separate from the name

of the whole road.

district String; optional A division of city; typically an

administrative unit within a

larger city or a customary name

of a city's neighborhood.

city String; optional The name of the primary locality

of the place.

regions Array[String]; optional For address conventions where

more than to levels of named

areas above the city level are

in use, the regions attribute

provides an array with all

additional area names, ordered

by decreasing size (starting with

the highest subdivision below

state)

county String; optional A division of a state; typically a

secondary-level administrative

division of a country or

equivalent.

state String; optional A division of a country; typically

a first-level administrative



division of a country and/or a

geographical region.

stateCode String; optional A code/abbreviation for the

state division of a country.

country String; optional The localised country name.

countryCode String (ISO 3166-1 alpha-3

code); optional

A three-letter country code.

Alternative NameEach alternative name is an object providing an alternative name for a place as well as information on

the language of that name.


name String The alternative name.

language String (language tag) The language/locale of the name.

Note: A place only contains those alternative names that match the client's languagepreferences, plus the locally used name of the place (if this differs from the base name).

Contacts Object StructureThere are multiple mechanisms for contacting a place. For each available type of contact, the object

contains an attribute that provides a list of contact details for that type. The possible types include:


phone Array[LabeledValue]; optional A telephone number for voice

calls

fax Array[LabeledValue]; optional A telephone number

for facsimile (telecopy)

transmissions

email Array[LabeledValue]; optional An e-mail address for sending

messages to the place

http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3

http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3




website Array[LabeledValue]; optional A URL for the website operated

by the place

New types may be added at any time and client applications should iterate over all available contact

types instead of just using this predefined set, to ensure that they always display all available contact

mechanisms to their users.

The contacts within a type are ordered by relevance. So clients that are only capable of displaying a

single contact per type should always display the first entry. But in general, client applications should

iterate over all contacts and use the label assigned to the contacts to distinguish them.

When there are many items of the same type, these items can be combined. Two phone items, for

example, can be displayed as shown below:

An example of multiple phone objects could be:

"contacts": { "phone": [ { "label": "Phone", "value": "+33147206252" }, { "label": "Mobile", "value": "+33147206252" } ], ...}

Labeled ValueEach individual contact item provides two attributes:


value String A localized label to describe the

purpose of the contact.

label String A string value appropriate for

the contact method.


Error Object StructureThe error object contains information on an error that occurred when the user tried to request a

resource. For example:

{ "status": 401, "message": "Missing authentication parameters"}

A more detailed example:

The error object has the following attributes:


status Number (integer) The HTTP response status code

of the request

message String The message relating to the

most important error to show to

the user.

incidentId String; optional Unique incident identifier.

errCode String; optional The error code relating to the

most important error to show to

the user.

details Object(map of String to

Array[SubError]); optional

An object containing error

details relating to the request.

Response Status Codes

400 Bad Request The request can not be fulfilled because the request contained bad syntax

or didn't contain required parameter or header.

401 Unauthorized The client needs to authenticate in order to access the resource. Bearer to-

ken header, app_id or app_code are missing, empty or invalid.

403 Forbidden The client is not allowed to access this resource for some reasons.

404 Not Found Requested resource was not found, though its existence in the future is

possible.


405 Method Not

Allowed

The method used in the request is not supported by the resource.

406 Not Accepted The server can not generate content which is acceptable to the client ac-

cording to the request's Accept header.

408 Request

Timeout

The client did not complete its request in a reasonable timeframe.

410 Gone The resource is gone and will always be gone; the client should not request

the resource again.

415 Unsupported

Media Type

The server can not process the request body because it is of an unsupport-

ed MIME type. Please refer to HTTP Request Headers on page 50 for de-

tails.

429 Too Many Re-

quests

Request quota has been exceeded. Please contact [email protected] to

upgrade your plan.

500 Internal

Server Error

The server encountered an unexpected condition which prevented it from

fulfilling the request.

501 Not Imple-

mented

The server can not process the request method

503 Service Un-

available

The resource is temporarily unavailable.

SubErrorError detail item object.


message String The error message

errCode String The error code

Location Object StructureA location object contains attributes to describe the physical location of a place. The attributes

are:



position Array[Number] A position indicated by latitude


[37.785141,-122.4047775].

address Object[address]; optional An object containing the street address of

the place. Some places may not have an

address (for example, a mountain).

locationId String; optional A unique identifier of the location when

assigned.

Rating Object StructureProvides a summary of how users rated a place.


average Number (double) The average rating across all users.

count Number (positive integer) The number of individual votes on the

place.

Place without Ratings

Note: If the place has no ratings (yet), both the average and the count values are zero. Butif the place cannot be rated (i.e. a street), the whole rating object is not present.

HTTP Status CodesPlaces API supports the standard HTTP status codes

Error code Description

200 OK Indicates success.

201 Created Indicates success.

400 Bad request Invalid parameter value in the request, for example zoom out of range.

401 Unauthorized Invalid authentication.



Error code Description

403 Forbidden Incorrect app_code or app_id in the request. See Acquiring Credentials

on page 16 for more information.

404 Not found Unsupported parameter in the request.

410 Gone The requested resource is no longer available, for example a place that has

been removed from the system.

500 Internal error There is a server configuration issue.

503 Service Unavailable Indicates that the service is temporarily unavailable due to system

overload or maintenance.

Places API Developer's Guide 160► Coverage

Appendix

A

CoverageWhen you use the Places API to build an application, your users can

find individual locations in

• over 200 countries

• over 1.5 million different areas (cities, districts, regions)

• over 25 million streets split into 90 million and more individualsegments

In an increasing number of countries, the Places API provides

detailed, building-specific location data – currently over 200 million

point addresses.

Places API offers information about millions of named and

categorised places in more than 200 countries:

• over 40 countries with more than 100,000 places

• over 80 countries with between 1,000 and 100,000 places

Several million of those places come with rich attribution/content

like:

• editorial information for trusted content partners

• ratings, reviews and images aggregated from a variety ofonline communities

• additional business information, often provided by the owner

Documents

Developer's Guide Places APIdocumentation.developer.here.com/pdf/places_pub/1.0.11638/Place… · Places API Developer's Guide 2 Contents Contents Legal Notices.....4 Document Information.....5