API Operations

Company and Brand Shares Service

The Company and Brand Shares services are responsible for fetching data from the company shares and brand shares Passport datasets. After getting your reference data from the Catalog Service, you can now use it to query the Company and Brand Shares services to get the data you really want.

URI	https://api.euromonitor.com/statistics/companyshare/{UnitType} or https://api.euromonitor.com/statistics/brandshare/{UnitType}
Supported verbs	GET, POST
Required headers	Ocp-Apim-Subscription-Key, Accept, Authorization
Parameters
UnitType	Required	The unit type to fetch data for: Percentage, Actual or Ranking.
categoryIds	Default null	An array of Category IDs, as retrieved from the Category catalog.
geographyIds	Required	An array of Geography IDs, as retrieved from the Geography catalog.
industryCodes	Default null	An array of Industry Codes, as retrieved from the Category catalog.
shareTypeId	Required	The ID of the share type you want to query, as retrieved from the Share Type catalog.
growthType	Default None	Specifies growth transform to be applied. Currently supported values are None and YearOnYear.
dataTypeIds	Default null	An array of Data Type IDs, as retrieved from the DataType catalog. If omitted, all data types fitting your request will be returned.
unifiedCurrency	Default None	Currency to convert all value data to. Applies to value data only. Supported values: None, USD, EUR, GBP, JPY, CHF.
inflationType	Default Both	Specifies whether to return value data in Current, Constant or Both terms. Applies to value data only.
exchangeRate	Default Both	Specifies whether to perform unified currency exchange in Fixed, YearOnYear or Both terms. Applies only to Actuals unit type and value data types converted using a unifiedCurrency other than None.
localCurrency	Default false	Specifies whether to return value in local researched currency. Applies to Actuals unit type and value data types only.
offset	Default 0	Used for paging. Specifies the number records to skip from the start of the dataset.
limit	Required	Used for paging. Specifies the page size of the response.
unpivotCsv	Default false	Specifies whether to return csv data pivoted or unpivoted (true or false). Only applies to csv format.
DataSliceID	Default 1	Used to indicate which particular subset of the company/brand sizes data to return. By default all products are returned but alternative “data slices” provide other subsets, such as lowest levels only.

A sample GET request might look like this:

GET https://api.euromonitor.com/statistics/companyshare/Percentag
e?Limit=1000&GeographyIds=11&ShareTypeId=0&CategoryIds=11069&Indu
stryCodes=CT&DataTypeIds=107&ExchangeRate=Fixed&UnifiedCurrency=G
BP&LocalCurrency=true 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/statistics/companyshare/Percentage 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
{
     "limit": 100,
     "categoryIds": [
      11069
     ],
     "industryCodes": [
      "CT"
     ],
     "geographyIds": [
      11
     ],
     "dataTypeIds": [
      107
     ],
     "shareTypeId": 0,
     "exchangeRate": "Fixed",
     "unifiedCurrency": "GBP",
     "localCurrency": true
}

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

{
     "offset": 0,
     "limit": 0,
     "total": 0,
     "companyShares"/"brandShares": [
         {
             "researchYear": 0,
             "categoryId": 0,
             "categoryName": "string",
             "geographyId": 0,
             "geographyName": "string",
             "industryCode": "string",
             "industryName": "string",
             "companyName"/”brandName”: "string",
             "dataTypeId": 0,
             "dataTypeName": "string",
             "shareTypeId": 0,
             "exchangeRateName": "string",
             "shareTypeName": "string",
             "unit": "string",
             "unitMultiplier": 0,
             "data": [
                 {
                 "year": 0,
                 "value": 0.0
                 }
             ]
         }
     ]
}

The company shares response structure is as follows:

offset	The offset you requested (page offset).
limit	The limit you requested (page size).
total	The total number of CompanyShare objects returned.
companyShares/brandShares	An array of CompanyShare or BrandShare objects returned for this page.

The CompanyShare (or BrandShare) object is defined as follows:

researchYear	The year in which the data was researched.
categoryId	The category ID, as found in the Catalog Service.
categoryName	The name of the category.
geographyId	The geography ID, as found in the Catalog Service.
geographyName	The geography name.
industryCode	The industry code associated with this record.
industryName	The industry name associated with this record.
brandName/companyName	The brand or company name.
dataTypeId	The data type ID for this record.
dataTypeName	The data type name for this record.
shareTypeId	The share type ID you requested.
shareTypeName	The name of the share type you requested.
exchangeRateName	The exchange rate adjustment (fixed or year on year) applied to this record if a currency conversion took place.
unit	The unit of the data in this object.
unitMultiplier	The unit multiplier, if any, of the data in this object.
data	The data for the given category and geography - an array of Datum objects.

The Datum object is defined as follows:

year	The year of the datum.
value	The value for the associated year.

The service will usually return large responses. To keep response sizes at a manageable level, we have implemented paging. By specifying limit in your request, you can control the amount of data you need to handle per response.

The total for your request is returned with each response. This means that after your first request, you can calculate how many pages you need to request to receive the full dataset. If total < limit, you do not need any additional requests.

Take care that you do not contravene the terms of fair use when requesting many pages.

You must supply either categoryIds or industryCodes (or both). If you only supply industryCodes, data for all categories in those industries will be returned. If you only supply categoryIds, only data for those categories will be returned.

unifiedCurrency and localCurrency are independent. If you request both a unified currency and local currency, the service will return two records of value data for each market/company combination.

If you specify no currency parameter but the response includes value data, the value data will default to USD in Fixed terms.

growthType and perCapitaId, if specified, will transform the returned dataset. I.e. you will not receive the original market sizes, only the transformed values. If you specify both growthType and perCapitaId, the growth transform will be applied on the per capita values.