Places (Search) API Developer's Guide

Explore Nearby Places

The user of an application on a mobile device is in the Chinatown district of San Francisco (37.7942°N, 122.4077°W), and wants to find places of various categories in the vicinity around the user's precise location. As a second step, the user wants to find out more information about one of the suggested places (so-called media types).

Note: This example demonstrates how to form a complex request, first generally addressing entrypoints and concluding with detailed hypermedia access.

Request

The request based on the above user story needs to be made against the endpoint named discover/here. In this example, we use an explicit location context (the parameter at) and we name the search category (the type of place to find) through the parameter named cat.

Here is the complete request:

https://places.cit.api.here.com/places/v1/discover/here
        ?app_id={YOUR_APP_ID}
        &app_code={YOUR_APP_CODE}
        &at=37.7942,-122.4070
        &pretty
      

Response

The response contains a list of places in the area, including links with additional information on these places the application can offer to the user via an icon. next contains a request URL with the next set of suggestions. Note that parts of the response have been modified as described in the introduction to Examples.

{
  "results": {
  "next": "https://places.demo.api.here.com/places/v1/discover/here;context=Zmxvdy1pZD1lNjhhNWZhYi1jMTA1LTU0MzgtOTcyMS00NTNmMTUxMjk4YTJfMTQ4NTE5NDUzMjc2OV8xMTEwXzYxNCZvZmZzZXQ9MjAmc2l6ZT0yMA?at=37.7942%2C-122.407&app_...",
  "items": [
    {
    "position": [
      37.79429,
      -122.40698
    ],
    "distance": 10,
    "title": "Dung Fong Trading Company",
    "averageRating": 0,
    "category": {
      "id": "shop",
      "title": "Store",
      "href": "https://places.demo.api.here.com/places/v1/categories/places/shop?app_...",
      "type": "urn:nlp-types:category",
      "system": "places"
    },
    "icon": "https://download.vcdn.cit.data.here.com/p/d/places2_stg/icons/categories/09.icon",
    "vicinity": "101 Waverly Place<br/>San Francisco, CA 94108",
    "having": [],
    "type": "urn:nlp-types:place",
    "href": "https://places.demo.api.here.com/places/v1/places/8409q8yy-3cbbca0ce5754b1fb6d808d8fa24d8f2;context=Zmxvdy1pZD1lNjhhNWZhYi1jMTA1LTU0MzgtOTcyMS00NTNmMTUxMjk4YTJfMTQ4NTE5NDUzMjc2OV8xMTEwXzYxNCZyYW5rPTE?app_...",
    "id": "8409q8yy-3cbbca0ce5754b1fb6d808d8fa24d8f2"
    },
    ...,
    {
    "position": [
      37.794304,
      -122.406998
    ],
    "distance": 12,
    "title": "Tung Fung Trading Co",
    "averageRating": 0,
    "category": {
      "id": "business-services",
      "title": "Business & Services",
      "href": "https://places.demo.api.here.com/places/v1/categories/places/business-services?app_...",
      "type": "urn:nlp-types:category",
      "system": "places"
    },
    "icon": "https://download.vcdn.cit.data.here.com/p/d/places2_stg/icons/categories/02.icon",
    "vicinity": "101 Waverly Pl<br/>San Francisco, CA 94108-1610",
    "having": [],
    "type": "urn:nlp-types:place",
    "href": "https://places.demo.api.here.com/places/v1/places/8409q8zn-3cc7f54215184bfba144179cd5187c24;context=Zmxvdy1pZD1lNjhhNWZhYi1jMTA1LTU0MzgtOTcyMS00NTNmMTUxMjk4YTJfMTQ4NTE5NDUzMjc2OV8xMTEwXzYxNCZyYW5rPTU?app_...",
    "id": "8409q8zn-3cc7f54215184bfba144179cd5187c24"
    },
    ...,
    {
    "position": [
      37.794034,
      -122.407022
    ],
    "distance": 19,
    "title": "Golden Gate Travel",
    "averageRating": 0,
    "category": {
      "id": "travel-agency",
      "title": "Travel Agency",
      "href": "https://places.demo.api.here.com/places/v1/categories/places/travel-agency?app_...",
      "type": "urn:nlp-types:category",
      "system": "places"
    },
    "icon": "https://download.vcdn.cit.data.here.com/p/d/places2_stg/icons/categories/02.icon",
    "vicinity": "835 Clay St<br/>San Francisco, CA 94108-1639",
    "having": [],
    "type": "urn:nlp-types:place",
    "href": "https://places.demo.api.here.com/places/v1/places/8409q8zn-9948c0c178284eaabfdae9abf8497dde;context=Zmxvdy1pZD1lNjhhNWZhYi1jMTA1LTU0MzgtOTcyMS00NTNmMTUxMjk4YTJfMTQ4NTE5NDUzMjc2OV8xMTEwXzYxNCZyYW5rPTE5?app_...",
    "id": "8409q8zn-9948c0c178284eaabfdae9abf8497dde",
    "openingHours": {
      "text": "Mon-Fri: 09:00 - 17:00",
      "label": "Opening hours",
      "isOpen": true,
      "structured": [
      {
        "start": "T090000",
        "duration": "PT08H00M",
        "recurrence": "FREQ:DAILY;BYDAY:MO,TU,WE,TH,FR"
      }
      ]
    }
    }
  ]
  },
  "search": {
  "context": {
    "location": {
    "position": [
      37.7942,
      -122.407
    ],
    "address": {
      "text": "818 Clay St<br/>San Francisco, CA 94108<br/>USA",
      "house": "818",
      "street": "Clay St",
      "postalCode": "94108",
      "district": "Chinatown",
      "city": "San Francisco",
      "county": "San Francisco",
      "stateCode": "CA",
      "country": "United States",
      "countryCode": "USA"
    }
    },
    "type": "urn:nlp-types:place",
    "href": "https://places.demo.api.here.com/places/v1/places/loc-dmVyc2lvbj0xO3RpdGxlPTgxOCtDbGF5K1N0O2xhdD0zNy43OTQyO2xvbj0tMTIyLjQwNztzdHJlZXQ9Q2xheStTdDtob3VzZT04MTg7Y2l0eT1TYW4rRnJhbmNpc2NvO3Bvc3RhbENvZGU9OTQxMDg7Y291bnRyeT1VU0E7ZGlzdHJpY3Q9Q2hpbmF0b3duO3N0YXRlQ29kZT1DQTtjb3VudHk9U2FuK0ZyYW5jaXNjbztjYXRlZ29yeUlkPWJ1aWxkaW5nO3NvdXJjZVN5c3RlbT1pbnRlcm5hbA;context=c2VhcmNoQ29udGV4dD0x?app_..."
  }
  }
}

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.