API Operations


Catalog Service


The Catalog service is responsible for returning reference data – that is, data supporting the main data sets. Some examples are:

  • How different industries are split into categories and what the relationships between different categories are
  • In-depth descriptions of each category
  • The geographies (regions/countries/cities) that we research and the hierarchies we model them with

Category


This endpoint returns all product categories from Passport that your subscription has access to within a given context. It will also reveal the hierarchical structure of these categories.


URI https://api.euromonitor.com/catalog/category
Supported verbs GET
Required headers Ocp-Apim-Subscription-Key, Accept, Authorization
Supported formats JSON, XML, CSV
Parameters
CategoryContext Context in which you want categories returned: Statistics or Analysis. Always use “Statistics” for Statistics API purposes.

A successful response body will have the following structure in JSON format:

[
      {
            "id": 0,
            "name": "string",
            "parentId": 0,
            "parentName": "string",
            "level": 0,
            "industryCode": "string",
            "industryName": "string",
            "industryOrder": 0
      }
]

It is an array of Category objects, each with the following members:

id The category ID
name The category name
parentId The ID of the parent category. This member references the "id" member of a different record. For root nodes, this member will have a value of null
parentName The name associated with the parent category. For root nodes, this member will have a value of null
level The node level of the category in the hierarchy tree. For root nodes, this member will have a value of 0, for child nodes 1, for grandchildren 2 etc.
industryCode The code for the industry this category object is associated with
industryName The name of the industry this category is associated with
industryOrder Denotes the order of this category object within the related industry
Note that the category data is all Passport-specific and subject to change.
Tissue and Hygiene
        └ Away-from-Home Tissue and Hygiene
        |       └ Away-from-Home Hygiene
        └ Retail Tissue and Hygiene

Will be represented by the Categories endpoint like this:

[
        {
              "id": 1,
              "name": "Tissue and Hygiene",
              "parentId": null,
              "parentName": null,
              "level": 0,
              "industryCode": "DPP",
              "industryName": "Tissue and Hygiene",
              "industryOrder": 0
        },
        {
              "id": 10,
              "name": "Away-from-Home Tissue and Hygiene",
              "parentId": 1,
              "parentName": "Tissue and Hygiene",
              "level": 1,
              "industryCode": "DPP",
              "industryName": "Tissue and Hygiene",
              "industryOrder": 1
        },
        {
              "id": 101,
              "name": "Away-from-Home Hygiene",
              "parentId": 10,
              "parentName": "Away-from-Home Tissue and Hygiene",
              "level": 2,
              "industryCode": "DPP",
              "industryName": "Tissue and Hygiene",
              "industryOrder": 2
        },
        {
              "id": 11,
              "name": "Retail Tissue and Hygiene",
              "parentId": 1,
              "parentName": "Tissue and Hygiene",
              "level": 1,
              "industryCode": "DPP",
              "industryName": "Tissue and Hygiene",
              "industryOrder": 3
        }
  ]
Note the root node with null parents, the levels, and the relationships between parents and children.

Geographies


This endpoint returns all geographies from Passport for which your subscription has access to statistics. Geographies can be countries, regions, or cities. Like categories, our geographies are structured in a hierarchical tree, and the hierarchy data is returned by this endpoint.


URI https://api.euromonitor.com/catalog/geography
Supported verbs GET
Required headers Ocp-Apim-Subscription-Key, Accept, Authorization
Supported formats JSON, XML, CSV

A sample request might look like this:


GET https://api.euromonitor.com/catalog/geography HTTP/1.1
Host: api.euromonitor.com
Authorization: Bearer <tokenstring>
Accept: application/json; api-version=1.0
Ocp-Apim-Subscription-Key: 173bad6f0b319h23add9ad162493915e              
          

A successful response body will have the following structure in JSON format:

[
    {
        "id": 0,
        "name": "string",
        "parentId": 0,
        "parentName": "string",
        "isoAlpha2Code": "string"
    }
]

It is an array of Geography objects, each with the following members:

id The ID of the geography
name The name of the geography
parentId The ID of the parent geography. This member references the "id" member of a different record. For root nodes, this member will have a value of null
parentName The name associated with the parent geography. For root nodes, this member will have a value of null
isoAlpha2Code For records representing countries, the ISO 3166-1 alpha-2 code of the country. For other geography objects, this value will be null.
Note that, besides the isoAlpha2Code, the country data is all Passport-specific and therefore subject to change.

For example, the following tree structure:

World
Western Europe
  └ Belgium
      └ Liège

Will be returned as:

[
    {
        "id": 1,
        "name": "World",
        "parentId": null,
        "parentName": null,
        "isoAlpha2Code": null
    },
    {
        "id": 2,
        "name": "Western Europe",
        "parentId": null,
        "parentName": null,
        "isoAlpha2Code": null
    },
    {
        "id": 21,
        "name": "Belgium",
        "parentId": 2,
        "parentName": "Western Europe",
        "isoAlpha2Code": "BE"
    },
    {
        "id": 211,
        "name": "Liège",
        "parentId": 21,
        "parentName": "Belgium",
        "isoAlpha2Code": null
    }
]
Note the root node with null parents, the relationships between parents and children, and the missing ISO codes from regions and cities.

Data Type


Our datasets include data for many different data types. Each market’s data may be returned in a multitude of data types. For example, requesting brand share data for Beer in France will return several records for value (different currency conversions, current and constant, etc.) as well as several records for volume (litres, barrels, etc.). These data types will be repeated for each brand returned. To refine your request, you can specify data types you want returned. However, the data types available to select will depend on the dataset, industry and categories you request.


This endpoint allows you to query the data types available for a specific dataset, so you can use these data types to refine a request to one of the main services.

URI https://api.euromonitor.com/catalog/{MeasureType}/datatype
Supported verbs GET, POST
Required headers Ocp-Apim-Subscription-Key, Accept, Authorization
Supported formats JSON, XML, CSV
Parameters
MeasureType Required The dataset that you wish to retrieve data types for. Can be MarketSize, CompanyShare or BrandShare
IndustryCodes Required A list of industry codes you wish to retrieve data types for
CategoryIds Optional A list of Category IDs you wish to retrieve data types for

A sample GET request might look like this:

GET https://api.euromonitor.com/catalog/BrandShare/datatype?IndustryCodes=CT&CategoryIds=11069 HTTP/1.1
Host: api.euromonitor.com
Authorization: Bearer <tokenstring>
Accept: application/json; api-version=1.0
Ocp-Apim-Subscription-Key: 173bad6f0b319h23add9ad162493915e

The POST version of the same request will look like this:

POST https://api.euromonitor.com/catalog/BrandShare/datatype HTTP/1.1
Host: api.euromonitor.com
Authorization: Bearer <tokenstring>
Accept: application/json; api-version=1.0
Content-Type: application/json
Ocp-Apim-Subscription-Key: 173bad6f0b319h23add9ad162493915e
{
    "industryCodes": [
        "CT"
    ],
    "categoryIds": [
        11069
    ]
}

A successful response body will have the following structure in JSON format:

[
    {
        "id": 0,
        "name": "string"
    }
]

It is an array of DataType objects, each with the following members:

id The ID of the data type. Use a collection of these values when building requests to the main data services
name The name of the data type

Data Slices


The Passport sizes data includes a mix of lowest "research" levels and pre-calculated aggregated levels. This allows you to pick on any particular categories you are interested in. There is a potential risk though if you are taking data outside of Passport and performing your own manipulations, that you could miscalculate by double-counting data. For example, this is a very small part of the Packaged Food product hierarchy:

  • Packaged Food
    • Confectionery
      • Chocolate Confectionery
      • Gum
        • Bubble Gum
        • Chewing Gum
      • Sugar Confectionery

In the example above, data on Passport for Gum is pre-calculated to be the sum of Chewing Gum + Bubble Gum, whereas total Confectionery is the sum of Chocolate Confectionery, Sugar Confectionery, and Gum. If you pull this data from Euromonitor's stats API and introduce it into some BI tools you might end up accidentally adding together Chewing Gum plus Bubble Gum plus total Gum - ie double-counting Gum. If your intention is to pull out all the data on Passport without further manipulation, then it makes sense to pull all the rows available. If you are planning to recombine data from the lowest levels then it's better to pull only data for those lowest levels - and it’s important to know what is the lowest level on all countries.


That is where the Data Slices endpoints come to help you. A "Data Slice" in the Euromonitor API is a subset of products, combined with information about the relative product hierarchy. There are two main data slices on most industries:

  1. All products
  2. Lowest level products

In addition to these data slices 1 and 2, some industries have additional data slices which provide alternative paths through which to aggregate lowest level data.


This endpoint allows you to query the names of the data slices available for a specific industry, so you can use these data slice IDs to refine a request to either the Data Slice Category endpoint or to the Market Sizes endpoint.

URI https://api.euromonitor.com/catalog/dataslices
Supported verbs GET, POST
Required headers Ocp-Apim-Subscription-Key, Accept, Authorization
Supported formats JSON, XML, CSV
Parameters
IndustryCodes An array of Industry Codes, as retrieved from the Category catalog

A sample GET request might look like this:

GET https://api.euromonitor.com/catalog/dataslices?IndustryCodes=CT HTTP/1.1
Host: api.euromonitor.com
Authorization: Bearer <tokenstring>
Accept: application/json; api-version=1.0
Ocp-Apim-Subscription-Key: 173bad6f0b319h23add9ad162493915e

The POST version of the same request will look like this:

POST https://api.euromonitor.com/catalog/dataslices HTTP/1.1
Host: api.euromonitor.com
Authorization: Bearer <tokenstring>
Accept: application/json; api-version=1.0
Content-Type: application/json
Ocp-Apim-Subscription-Key: 173bad6f0b319h23add9ad162493915e

{
    "industryCodes": [
        "CT"
    ]
}

A successful response body will have the following structure in JSON format:

[
    {
        "Id": 0,
        "Name": "string",
        "IndustryCode": "string",
        "IndustryName": "string"
    }
]

It is an array of DataSlice objects, each with the following members:

DataSliceid The ID of the data slice
DataSliceName The name of the data slice
IndustryCode The industry code
IndustryName The name of the industry

Data Slice Category Hierarchy


See the section above for a description of what we mean by Data Slices in the context of the Euromonitor statistics API. The Data Slice Category Hierarchy endpoint allows you to pull out a representation of the hierarchy of an industry split into multiple columns according product level. It even allows you to pull alternative ways of aggregating up the same data.


This endpoint allows you to query the product hierarchy for a particular data slice available for a specific industry. You can use this in conjunction with the market sizes you pull from the Market Sizes endpoint to see how data sums up through the hierarchy - and in some cases, through a choice of hierarchies.


For example, in Alcoholic Drinks, the product "Imported Premium Lager" could be considered to have the parent "Imported Lager", or the parent "Premium Lager". Passport presents the Lager hierarchy in both of these ways and a Passport user can choose one or the other. If you want to pull this data through the API and you want to see the full hierarchy path for this product then you can choose whether you want to see this with data slice 2:

DataSliceId,DataSliceName,CategoryId,CategoryName,IndustryCode,CategoryLevel0,CategoryLevel1,CategoryLevel2,CategoryLevel3,CategoryLevel4,CategoryLevel5,CategoryLevel6,CategoryLevel7

2,Lowest level products,12427,Ale,AD,Alcoholic Drinks,Beer,Dark Beer,Ale,,,,,

2,Lowest level products,13958,Sorghum,AD,Alcoholic Drinks,Beer,Dark Beer,Sorghum,,,,,

2,Lowest level products,13918,Weissbier/Weizen/Wheat Beer,AD,Alcoholic Drinks,Beer,Dark Beer,Weissbier/Weizen/Wheat Beer,,,,,

2,Lowest level products,13919,Flavoured/Mixed Lager,AD,Alcoholic Drinks,Beer,Lager,Flavoured/Mixed Lager,,,,,

2,Lowest level products,13064,Domestic Premium Lager,AD,Alcoholic Drinks,Beer,Lager,Standard Lager,Premium Lager,Domestic Premium Lager,,,

2,Lowest level products,12430,Imported Premium Lager,AD,Alcoholic Drinks,Beer,Lager,Standard Lager,Premium Lager,Imported Premium Lager,,,

Or this with data slice 6:

DataSliceId,DataSliceName,CategoryId,CategoryName,IndustryCode,CategoryLevel0,CategoryLevel1,CategoryLevel2,CategoryLevel3,CategoryLevel4,CategoryLevel5

6,Lowest levels products by origin,12427,Ale,AD,Alcoholic Drinks,Beer,Dark Beer,Ale,,,

6,Lowest levels products by origin,13958,Sorghum,AD,Alcoholic Drinks,Beer,Dark Beer,Sorghum,,,

6,Lowest levels products by origin,13918,Weissbier/Weizen/Wheat Beer,AD,Alcoholic Drinks,Beer,Dark Beer,Weissbier/Weizen/Wheat Beer,,,

6,Lowest levels products by origin,13919,Flavoured/Mixed Lager,AD,Alcoholic Drinks,Beer,Lager,Flavoured/Mixed Lager,,,

6,Lowest levels products by origin,13064,Domestic Premium Lager,AD,Alcoholic Drinks,Beer,Lager,Lager by Origin,Domestic Lager,Domestic Premium Lager,

6,Lowest levels products by origin,12431,Domestic Mid-Priced Lager,AD,Alcoholic Drinks,Beer,Lager,Lager by Origin,Domestic Lager,Domestic Mid-Priced Lager,

6,Lowest levels products by origin,12432,Domestic Economy Lager,AD,Alcoholic Drinks,Beer,Lager,Lager by Origin,Domestic Lager,Domestic Economy Lager,

6,Lowest levels products by origin,12430,Imported Premium Lager,AD,Alcoholic Drinks,Beer,Lager,Lager by Origin,Imported Lager,Imported Premium Lager,

6,Lowest levels products by origin,13065,Imported Mid-Priced Lager,AD,Alcoholic Drinks,Beer,Lager,Lager by Origin,Imported Lager,Imported Mid-Priced Lager,

6,Lowest levels products by origin,12433,Imported Economy Lager,AD,Alcoholic Drinks,Beer,Lager,Lager by Origin,Imported Lager,Imported Economy Lager,

Not that data slice 2 - the "lowest levels" subset of the data, returns the product categories that exist on all countries. In some industries we have deeper breakouts that exist only on a handful of countries. While these are available in the "all products" data slice 1, they don't count as "lowest levels" in data slice 2. Instead we select just the lowest common denominator - product categories that exist on all geographic levels.

URI https://api.euromonitor.com/catalog/dataslices /[DataSliceID]/category
Supported verbs GET, POST
Required headers Ocp-Apim-Subscription-Key, Accept, Authorization
Supported formats JSON, XML, CSV
Parameters
DataSliceID One integer to represent the choice of "data slice" for the industry or industries selected
IndustryCodes An array of Industry Codes, as retrieved from the Category catalog

A sample GET request might look like this:

GET https://api.euromonitor.com/catalog/dataslices/2/IndustryCodes=CT HTTP/1.1
Host: api.euromonitor.com
Authorization: Bearer <tokenstring>
Accept: application/json; api-version=1.0
Ocp-Apim-Subscription-Key: 173bad6f0b319h23add9ad162493915e

The POST version of the same request will look like this:

POST https://api.euromonitor.com/catalog/dataslices/2/category HTTP/1.1
Host: api.euromonitor.com
Authorization: Bearer <tokenstring>
Accept: application/json; api-version=1.0
Content-Type: application/json
Ocp-Apim-Subscription-Key: 173bad6f0b319h23add9ad162493915e

{
    "industryCodes": [
        "CT"
    ]
}

A successful response body will have the following structure in JSON format:

[
    {
        "DataSliceId": 0,
        "DataSliceName": "string",
        "CategoryId": 0,
        "CategoryName": "string",
        "IndustryCode": "string",
        "CategoryLevel0": "string",
        "CategoryLevel1": "string",
        "CategoryLevel2": "string",
        "CategoryLevel3": "string",
        "CategoryLevel4": "string",
        "CategoryLevel5": "string",
        "CategoryLevel6": "string",
        "CategoryLevel7": "string"
    }
]

It is an array of product hierarchy entries, each with the following members:

DataSliceid The ID of the data slice
DataSliceName The name of the data slice
CategoryId The ID of the product category
CategoryName The name of the category
CategoryLevel0 The name of the top level product to which this category contributes (eg Packaged Food)
CategoryLevel1 The name of the next level product to which this category contributes (eg Confectionery)
CategoryLevel2 The name of the next level product to which this category contributes (eg Gum)

Share Type


Our datasets include data for different share types – that is, different levels of ownership. Share types control the way you see data for brands changing hands.


This endpoint allows you to query the share types available for a specific shares dataset, so you can use these data types to refine a request to one of the main services.

URI https://api.euromonitor.com/catalog/ {MeasureType}/sharetype
Supported verbs GET, POST
Required headers Ocp-Apim-Subscription-Key, Accept, Authorization
Supported formats JSON, XML, CSV
Parameters
MeasureType Required The dataset that you wish to retrieve share types for. Can be CompanyShare or BrandShare
IndustryCodes Required A list of industry codes you wish to retrieve share types for
CategoryIds Optional A list of Category IDs you wish to retrieve share types for

A sample GET request might look like this:

GET https://api.euromonitor.com/catalog/BrandShare/sharetype?IndustryCodes=CT&CategoryIds=11069 HTTP/1.1
Host: api.euromonitor.com
Authorization: Bearer 
Accept: application/json; api-version=1.0
Ocp-Apim-Subscription-Key: 173bad6f0b319h23add9ad162493915e

The POST version of the same request will look like this:

POST https://api.euromonitor.com/catalog/BrandShare/sharetype HTTP/1.1
Host: api.euromonitor.com
Authorization: Bearer 
Accept: application/json; api-version=1.0
Content-Type: application/json
Ocp-Apim-Subscription-Key: 173bad6f0b319h23add9ad162493915e
{
    "industryCodes": [
        "CT"
    ],
    "categoryIds": [
        11069
    ]
}

A successful response body will have the following structure in JSON format:

[
    {
        "id": 0,
        "name": "string",
        "definition": "string"
    }
]

It is an array of DataType objects, each with the following members:

id The ID of the share type. Use a collection of these values when building requests to the main data services
name The name of the share type
definition The full definition of the share type