Timeline data

These endpoints contain data with datapoints timelines - with brands metrics, scores, volumes etc.

Formulas

These are the formulas we use in order to calculate the scoring options.

Treatment of BrandIndex Metrics
Scoring parameter value Description 3-Point Measures (pos/neg/neu) 2-Point Measures (yes/no)
"total" Includes all respondents, including unaware respondents Unaware respondents classified as 'neutral' Unaware respondents classified as 'no'
"aware" Excludes unaware respondents Unaware respondents excluded Unaware respondents excluded
"opinion" Excludes both unaware respondents and respondents who don't have a positive or negative opinion of the brand Unaware and neutral respondents excluded Unaware respondents excluded*
*Note: 2-point metrics are calculated the same in "aware" and "opinion" scoring

Timeline brands

This endpoint contains the URLs from where timeline series files can be retrieved.

By default, it lists URLs for files in the CSV format, but can also return JSON format ones (see "HTTP additional headers").

Where indicated, these URLs accept optional parts with demographic, metric and composite filters (referenced as :demo_filters, :metric_filters and :composite_filters here in the documentation) for the responses used to calculate the datapoints. :demo_filters has the following format: :/demo_filter_nickname.filter_value[/another_demo.another_value] (starting with a colon), each slash representing the start of a demo filter. :metric_filters has the following format: :/brand.brand_id.metric_nick.filter_value[/brand.another_brand_id.another_metric_nick.another_value] (starting with a colon), each slash representing the start of a demo filter. Also, you can use reflex in place of the brand ID, if you want to filter by metric but for each brand that composes the series. For example, if you use a metric filter definition like brand.reflex.buzz.1 when fetching data for a sector, it fill filter for each brand that composes that sector. :composite_filters has the following format: :/composite_filter_id[/another_composite_filter_id] (starting with a colon), each slash representing the start of a composite filter. Notice that each metric filter has to start exactly with the characters /brand (this pattern is used to differentiate between the two types of filters). You can also provide multiple values for each demo or metric filter; to do so, just put the numeric filter values as the filter_value part separated by a comma (","). For example: :/brand.1234.buzz.1,2/brand.2345.quality.9.

Besides demographic filters, metric filters and composite filters some endpoints (like the multi-brand timelines endpoints) also support passing in specific metrics (referenced as :metrics here in the documentation) in this same format; to do so, just join the metrics you want with slashes and separate them from the filters with a colon. See this page to know which metrics are available.

Full example, using all kinds of filters: :/age.1:/brand.2345.quality.9/brand.reflex.buzz.2:/abc123def456:/buzz/adaware - this format will get data for age with filter value 1, metric filter quality for respondents of brand 2345 with filter value 9, metric filter buzz for respondents of each brand in the context with filter value 2, composite filter whose ID is abc123def456 and will list values for metrics buzz and adaware.

The filters endpoint is documented here.

URL
https://api.brandindex.com/v0/timeline/brands
Required parameters
brand - a parameter in the format region:sector_id:brand_id[:demo_filters][:metric_filters]. Can be provided multiple times - if so, multiple files will be listed in the response data. See this explanation about the optional :demo_filters and :metric_filters parts.
start_date - the starting date from when to retrieve datapoints, in the format YYYY-MM-DD.
end_date - the ending date until when to retrieve datapoints, in the format YYYY-MM-DD.
scoring - the scoring option to use, within "total" (includes all respondents, including unaware respondents), "aware" (excludes unaware respondents) and "opinion" (excludes both unaware respondents and respondents who don't have a positive or negative opinion of the brand).
Optional parameters
moving_average - the timeline moving average, in days, that will be applied to the scores, as an integer. Defaults to 1.
HTTP methods
GET
HTTP headers
Accept - if containing application/json in its value, the URLs returned will be pointing to JSON files. By default, it points to CSV ones.
HTTP statuses
200 - request successful
Response body example

For an imaginary request to https://api.brandindex.com/v0/timeline/brands?brand=foo:123:1234:/brand.3456.reputation.1&brand=bar:234:2345:/foo_filter.1/bar_filter.2&start_date=2001-01-01&end_date=2015-02-20&moving_average=4&scoring=opinion


{
    "meta": {
        "start_date": "2001-01-01",
        "end_date": "2015-02-20",
        "scoring": "opinion",
        "moving_average": 4
    },
    "data": {
        "1234": "https://api.brandindex.com/v0/timeline/file.csv?sector=123&region=foo&scoring=opinion&brand_id=1234&start_date=2001-01-01&end_date=2015-02-20&moving_average=4",
        "2345": "https://api.brandindex.com/v0/timeline/file.csv?sector=234&region=bar&scoring=opinion&brand_id=2345&start_date=2001-01-01&end_date=2015-02-20&moving_average=4"
    },
    "ok": true
}

The meta element has relevant information about the files requested, but not the URLs themselves - the actual data.

The data element is a mapping of brand IDs to URLs where timeline series files can be located. If the request is made for JSON (see "HTTP additional headers"), the URL paths will be terminating with the .json extension instead of .csv.

Single-brand timeline file

This endpoint is actually a file payload with datapoints by date and metric, so its content can be saved to a file on disk or worked on directly.

Also, it will return with a Content-Disposition header set to attachment type, so that, if the request is made via a browser, it helps the user to download the file under a specific name. This might not be useful, however, when the file is being requested from an API client that's not a browser.

URL
https://api.brandindex.com/v0/timeline/file.csv to get the file as CSV
https://api.brandindex.com/v0/timeline/file.json to get the file as JSON
Required parameters
region - the region to which the brand belongs.
sector - the sector to which the brand belongs.
brand_id - the ID of the brand from which to retrieve datapoints from.
start_date - the starting date from when to retrieve datapoints, in the format YYYY-MM-DD.
end_date - the ending date until when to retrieve datapoints, in the format YYYY-MM-DD.
scoring - the scoring option to use, within "total" (includes all respondents, including unaware respondents), "aware" (excludes unaware respondents) and "opinion" (excludes both unaware respondents and respondents who don't have a positive or negative opinion of the brand).
Optional parameters
moving_average - the timeline moving average, in days, that will be applied to the scores, as an integer. Defaults to 1.
filters - filters in the format [:demo_filters][:metric_filters]. See this explanation about the optional :demo_filters and :metric_filters parts.
metrics - specific metrics, if you don't want all of them. If you want more than one, just separate them by a forward slash (/). See this page to know which metrics are available.
HTTP methods
GET
HTTP statuses
200 - request successful
404 - when the brand is not found or it has no data to be retrieved.
Request examples
https://api.brandindex.com/v0/timeline/file.csv?scoring=total&start_date=2017-01-01&end_date=2017-02-01&moving_average=1&region=us&sector=1&brand_id=1016 to get a timeline for brand 1016 from sector 1, region "us", without a moving average.
https://api.brandindex.com/v0/timeline/file.csv?scoring=total&start_date=2017-01-01&end_date=2017-02-01&moving_average=1&region=us&sector=1&brand_id=1016&filters=brand.1007.buzz.1:bixdemo_gender.2&metrics=quality/recommend to get a timeline for brand 1016 from sector 1, region "us", with positive Buzz for brand 1007, female gender, and focusing only on Quality and Recommended metrics.
Response body example

For a CSV file, just download this example file and look at the format.

For a JSON file, just download this example file and look at the format.

When the file is a JSON one, it's a complex-structured mapping, where the first level keys are the dates, the second level keys are the metrics (each one is a datapoint) and the third level keys are the questionnaire responses and calculations (like score) - bear in mind that the latter change depending on the metric, each with its own characteristics.

If a certain datapoint is empty, that is, got no questionnaire response for that date, it will have its "third-level keys" (volume, score etc) as null.

Multi-brand timeline file

This endpoint is similar to simple timeline files, but instead of representing the data for one brand only it can contain more than one brand per file.

Also, its format is different from the single-brand timeline files.

You must provide at least one of brand, sector or custom_sector. Any combination of these is also valid.

It's also possible to roll up the data in periods - for this, see the period_type and period_size parameters. In this case, when periodizing for more than "every 1 day" (which is the default, i.e., no roll-up done), the first date of each period is used in the resulting data.

URL
https://api.brandindex.com/v0/timeline/multi-brand-file.csv to get the file as CSV
https://api.brandindex.com/v0/timeline/multi-brand-file.json to get the file as JSON
Required parameters
brand - a parameter in the format region:sector_id:brand_id[:demo_filters][:metric_filters][:metrics]. Can be provided multiple times - if so, multiple brands will be listed in the response data. See this explanation about the optional :demo_filters, :metric_filters and :metrics parts.
sector - a parameter in the format region:sector_id[:demo_filters][:metric_filters][:metrics]. Can be provided multiple times - if so, multiple sectors will be listed in the response data. See this explanation about the optional :demo_filters and :metric_filters and :metrics parts.
custom_sector - a parameter in the format region:custom_sector_id[:demo_filters][:metric_filters][:metrics]. Can be provided multiple times - if so, multiple custom sectors will be listed in the response data. See this explanation about the optional :demo_filters and :metric_filters and :metrics parts.
start_date - the starting date from when to retrieve datapoints, in the format YYYY-MM-DD.
end_date - the ending date until when to retrieve datapoints, in the format YYYY-MM-DD.
scoring - the scoring option to use, within "total" (includes all respondents, including unaware respondents), "aware" (excludes unaware respondents) and "opinion" (excludes both unaware respondents and respondents who don't have a positive or negative opinion of the brand).
Optional parameters
moving_average - the timeline moving average, in days, that will be applied to the scores, as an integer. Defaults to 1.
period_type - the type of period, if rolling up the datapoints. Can be "day", "week", "month" or "year". Defaults to "day".
period_size - the integer size of each period - e.g., 2 for rolling up "every 2 weeks". Defaults to 1.
HTTP methods
GET
HTTP statuses
200 - request successful
404 - when a brand is not found or it has no data to be retrieved.
Request examples
https://api.brandindex.com/v0/timeline/multi-brand-file.csv?scoring=total&start_date=2017-01-01&end_date=2017-02-01&moving_average=1&brand=us:1:1007&brand=us:1:1016 to get a timeline for brands 1007 and 1016 from sector 1, region "us", without a moving average.
https://api.brandindex.com/v0/timeline/multi-brand-file.csv?scoring=total&start_date=2017-01-01&end_date=2017-02-01&moving_average=1&sector=us:1&brand=us:1:1016 to get a timeline for the aggregated sector 1 and brand 1016 from sector 1, region "us", without a moving average.
https://api.brandindex.com/v0/timeline/multi-brand-file.csv?scoring=total&start_date=2017-01-01&end_date=2017-02-01&moving_average=1&brand=us:1:1016:brand.1007.buzz.1:bixdemo_gender.2:quality/recommend to get a timeline for brand 1016 from sector 1, region "us", with positive Buzz for brand 1007, female gender, and focusing only on Quality and Recommended metrics.
Response body example

For a CSV file, just download this example file and look at the format.

For a JSON file, just download this example file and look at the format.

For the CSV format, the resulting file has a "long and narrow" format instead of a "short and wide" one, that is, it's organized focusing on specifying rows more than having multiple metrics for each row. For the JSON format, the structure is about the same, except that the dates structures are kept into each brand structure - so the brand ID is the first level in the JSON response.