Places (Search) API Developer's Guide

External References

External references allow you to mash up Places (Search) 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 through Places (Search) API with information from another system, Places (Search) API provides access to identifiers used by external systems. Depending on license agreements you have with the external systems, you can interact with them, using their identifiers.
If you find a place in an external system, but would like to interact with it using Places (Search) API, you can look up the place in Places (Search) API with the help of the identifier from the external system.

The features outlined above allow your application to combine multiple systems, without the overhead of matching and de-duplication of place content coming from multiple sources.

Getting Access to External Identifiers

By default, external references are not exposed in the Place Media Type. To obtain external references, client applications must use the Show References (show_refs) (DEPRECATED) modifier.

For example, when an application uses the Explore Entrypoint to find hotels in San Francisco:


https://places.ls.hereapi.com/places/v1/discover/explore?at=37.7851%2C-122.4047&cat=accommodation&apiKey={YOUR_API_KEY}

Note: This example uses a HERE API Key to authenticate your request. For the available authentication options, see the Identity & Access Management Developer Guide.

Places (Search) API returns place-details links and one of the links refers to Hotel Palomar:

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

To expose HERE Core Maps identifiers, client applications need to add the representation modifier "&show_refs=pvid" to all provided URL in the search results before they fetch the place details:


https://places.ls.hereapi.com/places/v1/places/8409q8yy-6af3c3e50bcb4f859686797b2be5773d;context=...&show_refs=pvid

The resulting response contains the HERE Core Maps identifiers in the references attribute:

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

Certain places have more than one external identifier referring to same place. The 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 can find places on the basis of external identifiers. For further information, please see Lookup Entrypoint.

Position of External References

Depending on the type of the external references, the references attribute may appear in different parts of JSON response:

Place external references, references attribute is a direct children attribute of Place Media Type
Location external references, references attribute is within the location attribute.

For example, adding the building (3D) name from an external system in the representation modifier "&show_refs=pvid,building", the JSON response may contain two references attributes as shown below:

{
  "name": "Hotel Palomar",
  ...,
  "references": {
    "pvid": {
      "id": "1048649872",
      "alternatives": [
        {
          "id": "19435190"
        }
      ]
    }
  },
  ...,
  "location": {
    "position": [ 37.78539 , -122.40535 ],
    ...,
    "references": {
      "building": {
        "id": "9000000000000879904"
    }
  },
  ...
}