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.ls.hereapi.com/places/v1/discover/here
?apiKey={YOUR_API_KEY}
&at=37.7942,-122.4070
&pretty
Note: This example uses a HERE API Key to authenticate your request. For the available authentication optionsy, see the Identity & Access Management Developer Guide.

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.ls.hereapi.com/places/v1/discover/here;context=Zmxvdy1pZD1lNjhhNWZhYi1jMTA1LTU0MzgtOTcyMS00NTNmMTUxMjk4YTJfMTQ4NTE5NDUzMjc2OV8xMTE...",
    "items": [
      {
        "position": [
          37.79429,
          -122.40698
        ],
        "distance": 10,
        "title": "Dung Fong Trading Company",
        "averageRating": 0,
        "category": {
          "id": "shop",
          "title": "Store",
          "href": "https://places.ls.hereapi.com/places/v1/categories/places/shop?app_...",
          "type": "urn:nlp-types:category",
          "system": "places"
        },
        "icon": "https://download.vcdn.data.here.com/p/d/places2/icons/categories/09.icon",
        "vicinity": "101 Waverly Place<br/>San Francisco, CA 94108",
        "having": [],
        "type": "urn:nlp-types:place",
        "href": "https://places.ls.hereapi.com/places/v1/places/8409q8yy-3cbbca0ce5754b1fb6d808d8fa24d8f2;context=Zmxvdy1pZD1lNjhhNWZhYi1jMTA1LTU0MzgtOTcy...",
        "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.ls.hereapi.com/places/v1/categories/places/business-services?app_...",
          "type": "urn:nlp-types:category",
          "system": "places"
        },
        "icon": "https://download.vcdn.data.here.com/p/d/places2/icons/categories/02.icon",
        "vicinity": "101 Waverly Pl<br/>San Francisco, CA 94108-1610",
        "having": [],
        "type": "urn:nlp-types:place",
        "href": "https://places.ls.hereapi.com/places/v1/places/8409q8zn-3cc7f54215184bfba144179cd5187c24;context=Zmxvdy1pZD1lNjhhNWZhYi1jMTA1LTU0MzgtOTcy...",
        "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.ls.hereapi.com/places/v1/categories/places/travel-agency?app_...",
          "type": "urn:nlp-types:category",
          "system": "places"
        },
        "icon": "https://download.vcdn.data.here.com/p/d/places2/icons/categories/02.icon",
        "vicinity": "835 Clay St<br/>San Francisco, CA 94108-1639",
        "having": [],
        "type": "urn:nlp-types:place",
        "href": "https://places.ls.hereapi.com/places/v1/places/8409q8zn-9948c0c178284eaabfdae9abf8497dde;context=Zmxvdy1pZD1lNjhhNWZhYi1jMTA1LTU0MzgtOTcy...",
        "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.ls.hereapi.com/places/v1/places/loc-dmVyc2lvbj0xO3RpdGxlPTgxOCtDbGF5K1N0O2xhdD0zNy43OTQyO2xvbj0tMTIyLjQwNztzdHJlZXQ9Q2xheStTdDto..."
    }
  }
}

Related Information