Overview


What is the Euromonitor International API?


The Euromonitor International API is a set of HTTP-based web services that grants access to the statistics data in your Passport subscription. Each of these services has a particular responsibility that will be laid out in this guide.


Prerequisites


In order to use the Euromonitor International API, you will need the following:

  • A valid Passport subscription.
  • A user in your subscription with permission to access the API (speak to your account manager).
  • Familiarity with consuming web services over HTTP. You’ll need to understand HTTP verbs and request/response composition.
  • Understanding of JSON, XML and CSV content types.
  • Tools to consume our web services (cURL, Postman, or a programming language of your choice).

API Key


Access to the Euromonitor International API is controlled by an API Key, which can be obtained from your Profile page in the API developer portal. This key is unique to your Passport subscription and is used to control and monitor your usage of the API. This key should be treated like a password and kept secure.


The key should be added to every request in a special HTTP header, called Ocp-ApimSubscription-Key.

For example:

Ocp-Apim-Subscription-Key: <api-key-subscription-key-guid> 

Versioning


The Euromonitor International API is subject to change. To enable smooth upgrades as our services evolve, we have implemented a versioning strategy. You will need to specify the version of each service you wish to address. As a result, any dependencies you have on our services will not be affected when we perform upgrades.


The version needs to be specified in the Accept header in every HTTP request you make to any of our services, in the following format:

Accept: application/json; api-version=1.0

Euromonitor will notify clients of version upgrades and provide documentation to assist you in keeping up to date.


Authentication


Data will only be provided to authenticated requests. We rely on the OAuth 2.0 Authorization framework to achieve this. All requests to any of our services need to be accompanied by an access token in order to pass authorization. If you do not possess a valid access token, your request will be declined with HTTP status code 401 (Unauthorized).


An access token can be obtained from the Euromonitor Authentication service’s token endpoint. This endpoint supports only the OAuth 2.0 password grant:


URI https://api.euromonitor.com/authentication/connect/token
Supported verbs POST
Supported request content types application/x-www-form-urlencoded
Required headers Ocp-Apim-Subscription-Key
Request body parameters
grant_type Always use "password"
username Your Passport username (confirm with your account manager that your user is API enabled)
password Your Passport password

Given the following parameter value set:

Requested Parameters Example Value
grant_type password
username john.doe@organization.com
password Pa$$word123

The request to the token endpoint will look like this:

POST https://api.euromonitor.com/authentication/connect/token HTTP/1.1
Host: api.euromonitor.com
Content-Type: application/x-www-form-urlencoded
Ocp-Apim-Subscription-Key: 173bad6f0b319h23add9ad162493915e

grant_type=password&username=john.doe@organization.com&password=Pa$$word123

A successful response body will have the following JSON structure:

{
"access_token": "<tokenstring>",
"expires_in": 0,
"token_type": "Bearer"
}

The access_token member is the access token that will grant you access to all the other services in the Euromonitor International API. The expires_in member is the lifetime – in seconds – of the access token. When this timespan has passed, the token will expire and you will need to obtain a new token. The token_type member will always return “Bearer” and indicates that the token is of the bearer token type. This defines the use of the token in other service requests.


To use this token in subsequent calls to our other services, set it in the Authorization HTTP header, like this:

Authorization: Bearer <tokenstring>

Data Formats


Currently, the Euromonitor International API supports three formats: JSON, XML and CSV. There are two ways to select the response content type when you request data:

  • 1. Query string: Add a format parameter to your query string with one of the following values:
    • json
    • xml
    • csv
  • 2. Accept Header: Set the corresponding MIME type in your request’s Accept header:
    • application/json
    • application/xml
    • text/csv

The query string method takes precedence over the Accept header method. If you do not specify a content type, all our service will default to JSON format.


For example, to request CSV using the query string method, use:

https://api.euromonitor.com/catalog/category?format=csv

Or to request XML content using the Accept header method:

Accept: application/xml; api-version=1.0
Note the api-version field that always has to appear in the Accept header (see versioning above).