Places (Search) API Developer's Guide

External References

The concept of external reference allows 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 in Places (Search) API with information from another system, Places (Search) 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 (Search) API that you found in another source, you are able to lookup the Places (Search) 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. To request for certain external references, client applications have to use the Show References Representation Modifier to tell Places (Search) API which external systems client applications want to integrate with.

For example, using Explore Entrypoint to find hotels in San Francisco:
http://places.cit.api.here.com/places/v1/discover/explore?at=37.7851%2C-122.4047&cat=accommodation&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}
Places (Search) 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.cit.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.cit.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.

Position of External References

Depending on the type of the external references, the references attribute might 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 building (3D) external system name in the representation modifier "&show_refs=pvid,building", the JSON response might contain 2 references attributes:
{
  "name": "Hotel Palomar",
  ...,
  "references": {
    "pvid": {
      "id": "1048649872",
      "alternatives": [
        {
          "id": "19435190"
        }
      ]
    }
  },
  ...,
  "location": {
    "position": [ 37.78539 , -122.40535 ],
    ...,
    "references": {
      "building": {
        "id": "9000000000000879904"
    }
  },
  ...
}

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.