Get Started For Free Get Started For Free

Places (Search) API

Places (Search) API Developer's Guide

Authentication

The Places (Search) API offers the following authentication methods when submitting requests:
  • including your app_id and app_code in the query parameters

    For more information about using these parameters, see Constructing a Request.

  • including your app_id and app_code in the Authorization header using Basic Application Authentication
  • including an OAuth 1.0 signature in the Authorization header

    If you are using Places (Search) API Premium services, you must use an OAuth 1.0 signature.

These methods are mutually exclusive.

For information on how to get your app_id and app_code credentials, see Acquiring Credentials.

HTTP Basic Application Authentication

If you want to send your app_id and app_code credentials in the request HTTP Header, use HTTP Basic Authentication Scheme.

To construct your Authorization header:

  1. Combine your app_id and app_code in a string as follows "{YOUR_APP_ID}:{YOUR_APP_CODE}".
  2. Encode the resulting string using Base64.
  3. Set the Authorization header parameter to Basic {encoded value}.

    The result is as follows: Authorization:Basic {encoded value}

  4. Send the request using HTTPS.

OAuth 1.0 Request Signing

When signing your request with an OAuth 1.0 signature, you need the public key of a public key/private key pair created by HERE. To get your public key, contact your HERE Customer Representative.

To sign your request with an OAuth 1.0 signature:
  • set the oauth_consumer_key parameter to your app_id value
  • set the oauth_signature parameter to the shared secret you get from your HERE Customer Representative
  • set realm parameter to FIXME
  • determine which signature method you wish to use and set the oauth_signature_method parameter to your preferred method.

    The supported signature methods are HMAC-SHA1 and PLAINTEXT.

  • set the oauth_version parameter to 1.0
  • if you use the HMAC-SHA1 signature method, set the oauth_nonce parameter to a generated value to uniquely identify your request
  • if you use the HMAC-SHA1 signature method, set the oauth_timestamp parameter to a time stamp FIXME

The Places (Search) API only uses the OAuth 1.0 method to authenticate applications. This means you should not use the oauth_token parameter when following the OAuth 1.0 procedure for Making Requests.

The examples below illustrate the signature methods. 

Authorization: OAuth realm="Example",
oauth_signature_method="HMAC-SHA1",
oauth_version="1.0",
oauth_nonce="01TKi",
oauth_timestamp="1361198411",
oauth_consumer_key="{YOUR_APP_ID}",
oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D"
Authorization: OAuth realm="Example",
oauth_signature_method="PLAINTEXT",
oauth_version="1.0",
oauth_consumer_key="{YOUR_APP_ID}",
oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D"
Note: To use the PLAINTEXT OAuth Signature Method, you must send HTTPS requests.