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:


URIhttps://api.euromonitor.com/authentication/connect/tokenSupported verbsPOSTSupported request content typesapplication/x-www-form-urlencodedRequired headersOcp-Apim-Subscription-KeyRequest body parametersgrant_typeAlways use "password"usernameYour Passport username (confirm with your account manager that your user is API enabled)passwordYour Passport password


Given the following parameter value set:

Requested ParametersExample Valuegrant_typepasswordusernamejohn.doe@organization.compasswordPa$$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>


OAuth 2.0:


We have enabled OAuth 2.0 support to generate token securely. The Authentication Service allows you to obtain a Json Web Token (JWT) which is required to access all the APIs securely.

Step 1:

Select Authorization endpoints, click on try it and then select Authorization Code from the drop-down.

Step 2:

When Authorization code is selected, as pop-up window is displayed with the sign-in form of the OAuth 2.0 provider. The sign-in form is provided by Azure Active Directory.

*NOTE-

1) If your browser pop-ups are disabled, then you will be prompted to enable them by the browser. After you enable them, select Authorization code again and the sign-in form will be displayed.

2) Auto login – If user is already logged into the system, then it’s get auto logged in.

Step 3:

Once you have signed in, the Request headers are populated with an Authorization: Bearer header that authorizes the request.


*NOTE-

OAuth 2.0 is enabled for all the API’s endpoints. you can configure the other values in given field and submit the request to get data.

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).

© 2024 Euromonitor is privately owned & trademarked