From 7169038aa44b5bbbc873a4d64a88891545bac57a Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Fri, 23 Oct 2026 23:18:55 +0200 Subject: [PATCH 01/23] Update MCP connector docs to match the current servers Bring the BAV, Best Countries and Financial Data pages up to date with the tools the servers register, add Market Share, concepts, MCP Apps and connecting clients pages, and update the Social Data page from Sightly's documentation. Co-Authored-By: Claude Opus 5.5 --- docs/ai/agents.md | 6 + docs/ai/intro.md | 8 +- docs/ai/mcp/access-authorization.md | 83 +++- docs/ai/mcp/bav.md | 235 ++++++++++-- docs/ai/mcp/best-countries.md | 56 +-- docs/ai/mcp/concepts.md | 118 ++++++ docs/ai/mcp/connecting-clients.md | 147 ++++++++ docs/ai/mcp/financial-data.md | 45 ++- docs/ai/mcp/intro.md | 34 +- docs/ai/mcp/market-share.md | 116 ++++++ docs/ai/mcp/mcp-apps.md | 79 ++++ docs/ai/mcp/social.md | 561 +++++++++++++++++++++++----- docs/ai/mcp/wpp-open.md | 30 -- 13 files changed, 1303 insertions(+), 215 deletions(-) create mode 100644 docs/ai/mcp/concepts.md create mode 100644 docs/ai/mcp/connecting-clients.md create mode 100644 docs/ai/mcp/market-share.md create mode 100644 docs/ai/mcp/mcp-apps.md delete mode 100644 docs/ai/mcp/wpp-open.md diff --git a/docs/ai/agents.md b/docs/ai/agents.md index 5d344e0..ed81c47 100644 --- a/docs/ai/agents.md +++ b/docs/ai/agents.md @@ -22,3 +22,9 @@ analysis. These agents can help users with tasks such as competitive analysis, c market segmentation. Please [get in touch with us](mailto:bavsupport@wpp.com) for access to these agents. + +## Building your own agents + +If you want to build your own agents, you can connect them directly to BAV data using our +[MCP servers](mcp/intro.md). In WPP Open, the MCP servers are available as tools in the Creative Studio agent builder, +see [connecting clients](mcp/connecting-clients.md#wpp-open). diff --git a/docs/ai/intro.md b/docs/ai/intro.md index 2443522..7df887d 100644 --- a/docs/ai/intro.md +++ b/docs/ai/intro.md @@ -25,8 +25,10 @@ You can use the agents standalone or as part of a larger agentic team. [Read more](agents.md) -## MCP Server +## MCP Servers -Your AI models and agents can use the official BAV MCP server to access BAV data in both a simple and secure way. +Your AI models and agents can use the official BAV MCP servers to access BAV data, Best Countries, financial data and +Euromonitor market share data in both a simple and secure way. The servers work with any MCP client that supports +remote servers, including Claude, ChatGPT, Copilot and the agent builder in WPP Open. -[Read more](mcp/index.md) \ No newline at end of file +[Read more](mcp/intro.md) diff --git a/docs/ai/mcp/access-authorization.md b/docs/ai/mcp/access-authorization.md index 44300d4..e363845 100644 --- a/docs/ai/mcp/access-authorization.md +++ b/docs/ai/mcp/access-authorization.md @@ -6,8 +6,8 @@ sidebar_label: Access & Authorization ## Access (as a user) -Everyone with a WPP Okta account has access to the MCP servers. When you connect to it you will be asked to authorize -your AI application to access the data on your behalf. +Everyone with a WPP Okta account has access to the MCP servers. When you connect to it you will be asked to sign in and +authorize your AI application to access the data on your behalf. :::warning Authorized Agent Environments Please note that you may only connect to the BAV MCP server from authorized agent environments that have been @@ -15,25 +15,86 @@ vetted by WPP legal. This is to ensure the data security and compliance around o not sure whether your environment is authorized, please reach out. ::: +### Tools depend on your permissions + +The tools on each server are permission-gated per user. When your AI application lists the tools on a server, it only +sees the tools that you have access to. This means that two users connecting to the same server may see different tool +lists. For example, the [Market Share server](./market-share.md) requires access to Euromonitor data, and the city tools +on the [Best Countries server](./best-countries.md) require access to Best Countries city data. + +If you are missing a tool you expected to see, please [get in touch with us](mailto:bavsupport@wpp.com). + ## Authorization (for developers) These instructions cover how authorization works and is geared towards a developer integrating an AI model or agent with our MCP servers. +### OAuth + All our MCP servers work with OAuth 2.0 using the -standard [MCP authorization flow](https://modelcontextprotocol.io/docs/tutorials/security/authorization). +standard [MCP authorization flow](https://modelcontextprotocol.io/docs/tutorials/security/authorization). Most MCP +clients handle this flow for you automatically, so you only need to provide the server URL. We highly recommend OAuth as the authorization mechanism as it allows you to act as the user and access data on their behalf. -You may also use personal API keys as well, but please note that API keys are tied to a specific user and do not allow -your application to act on behalf of other users. +The servers support the discovery and registration mechanisms in the MCP specification: + +- **Protected resource metadata:** An unauthenticated request returns a `401` with a `WWW-Authenticate` header that + points to the protected resource metadata at `/.well-known/oauth-protected-resource`. +- **Authorization server metadata:** The authorization, token and registration endpoints are published at + `/.well-known/oauth-authorization-server`. +- **Dynamic client registration:** Clients can register themselves using the registration endpoint, so you do not need + to create an OAuth client up front. + +The authorization code grant is used with PKCE (`S256`), and refresh tokens are supported. + +### Personal Access Tokens + +You may also use personal access tokens, but please note that they are tied to a specific user and do not allow +your application to act on behalf of other users. Personal access tokens can be created from +the [API section in The Fount](https://fount.wppbav.com/api). + +If you are using a personal access token, just pass it as a Bearer token in the Authorization header when making +requests to the MCP server: + +``` +Authorization: Bearer YOUR_API_KEY +``` + +### Applications + +If you are building an application for the group, we can set you up with an application. Applications can +authenticate in a few different ways: + +- **OAuth on behalf of a user:** Users authorize your application through the OAuth flow, and your application acts on + their behalf with their permissions. +- **Application tokens:** An access token belonging to the application itself. Requests are made as the application. +- **Client credentials:** Applications approved for it can request a token using the OAuth client credentials grant. + This works like an application token. + +Applications that have been approved to act on behalf of users can pass the e-mail address of the user in the +`X-Act-As-User` header together with an application token or a client credentials token. The token must explicitly +include the `act-as-user` scope. The request is then made as that user, with their permissions. The legacy +`X-User-Email` header is still accepted but we recommend moving to `X-Act-As-User`. + +``` +Authorization: Bearer YOUR_APPLICATION_TOKEN +X-Act-As-User: jane.doe@wpp.com +``` + +:::note +Tokens issued to a user through OAuth cannot act as another user. The `X-Act-As-User` header is only accepted with +application tokens. +::: -If you are using an API key, just pass it as a Bearer token in the Authorization header when making requests to the MCP -server: +Applications can be restricted to only accept requests from a set of allow-listed IP addresses. When an application +has an IP allow-list, every request it makes, whether for itself or on behalf of a user, must come from one of those +addresses. This also applies when requesting a token with the client credentials grant. -```Authorization: Bearer YOUR_API_KEY``` +For internal applications it is possible to skip the consent screen by having your application specifically +allow-listed as a trusted application. Consent is only skipped when the request comes from one of the application's +allow-listed IP addresses. We recommend this approach for internal tools as it provides a smoother user experience. +Please reach out if you would like to have your application set up. -For internal applications it is possible to use skip the consent screen by having your application specifically -allow-listed. We recommend this approach for internal tools as it provides a smoother user experience. Please reach out -if you would like to have your application allow-listed. \ No newline at end of file +See the [authentication documentation](../../authentication.md) for more information on applications and tokens. diff --git a/docs/ai/mcp/bav.md b/docs/ai/mcp/bav.md index 2905778..11a736b 100644 --- a/docs/ai/mcp/bav.md +++ b/docs/ai/mcp/bav.md @@ -8,13 +8,12 @@ The BAV MCP Server provides access to the WPP BAV proprietary brand data through called by AI agents. This allows you to build AI applications that can leverage the rich brand data collected by BAV to provide insights, recommendations, and analysis. -The tools (see below) span both research data on brands, as well as metadata around coverage, imagery, and -other assets. +The tools (see below) span research data on brands, metadata around coverage and taxonomy, audiences, collections, +AURA (AI brand research), media performance and interactive charts. ## Connecting to the server -Our remote MCP server supports both SSE (Server-Sent Events) and Streamable HTTP. -To connect to the BAV MCP server, you need to use the following URL: +Our remote MCP server supports Streamable HTTP. To connect to the BAV MCP server, you need to use the following URL: ``` https://mcp-beta.wppbav.com/v1/bav @@ -27,50 +26,216 @@ period so you can update your applications accordingly. For authorization, please see the [access and authorization](./access-authorization.md) section. +If you are building an agent on top of the server, we recommend reading [Concepts for agents](./concepts.md) as well. It +explains how studies, score types and data generation work, which is what most agents trip over. + ## Available Tools -The BAV MCP server provides two sets of tools: +The tools are grouped by the job they do: + +- **Metadata and lookup tools:** Find brands, markets, studies, sectors, categories, audiences and metric definitions. +- **Brand data tools:** Fetch the BAV brand data itself, one data model per tool. +- **Collection tools:** Create, update and share brand collections. +- **Audience tools:** Build, deploy and size audiences, and read how a population answered survey questions. +- **AURA tools:** How large language models perceive brands, and how that differs from consumers. +- **Media performance tools:** Campaign performance data and benchmarks. +- **Display tools:** Render interactive charts in clients that support [MCP Apps](./mcp-apps.md). + +### Which tools you will see -- **Data Tools:** These tools allow you to fetch various types of brandscape data, or simply put "the BAV data". -- **Metadata Tools:** These tools provide access to metadata about the BAV data, such as available brands, markets, - years, audiences and more. +Each tool is only registered for users who have permission to use it. Two people connecting to the same server can +therefore see a different list of tools. If a tool below is missing from your client, the signed-in user does not have +access to that part of the platform. Most tools are available to every BAV user, while some data models and products +need additional access. The access column in the tables below describes what each tool requires. **Tip:** You can always ask the agent to list the available tools interactively, or you can use the [list tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#listing-tools) mechanism as defined in the MCP specification. This will return the full tool definitions including parameters and descriptions. -### Data Tools - -- `get-pillar-data` -- `get-powergrid-data` -- `get-imagery-data` -- `get-personality-data` -- `get-usage-data` -- `get-preferences-data` -- `get-recommendation-data` -- `get-brand-worth-data` -- `get-customer-experience-data` -- `get-influence-data` - -### Metadata Tools +### Metadata and Lookup Tools + +| Tool | What it does | Access | +|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------| +| `get-markets` | Lists the markets and years with BAV data, and the **study IDs** you need to request data. Each study is labelled with its type, and the recommended one is marked. | Users who can view studies. | +| `get-brands` | Searches brands and returns their details (website, social links, sector, company, tags) and a summary of the markets and years each brand was studied in. | Users who can view brands. | +| `list-brand-tags` | Lists the brand tags (such as luxury, direct-to-consumer or family owned) and their keys, for use with the `tags` filter on `get-brands`. | Users who can view brands. | +| `get-sectors` | Lists the sectors in the BAV taxonomy. | Users who can view BAV categories. | +| `get-categories` | Lists the categories in the BAV taxonomy, optionally filtered by search, sector, study, country or year. | Users who can view BAV categories. | +| `get-audiences` | Lists the audiences you can segment brand data by. The default audience is "All Adults". | Users who can view brand data. | +| `get-glossary` | Returns definitions of brand metrics, brand measures or audience questions (`type` is required), optionally limited to what was measured in given studies. | Users who can view at least one of metrics, measures or questions. Each `type` needs its own access. | + +#### Finding brands with `get-brands` + +`get-brands` accepts the following parameters, all optional: + +- `search` - Free text search on the brand name. This is the best way to find a brand by name. +- `brands` - A list of brand IDs. +- `sectors` - A list of sector names or IDs. +- `countries` - A list of country codes (ISO 3166-1 alpha-2) or IDs. Only returns brands with data in these markets. +- `years` - A list of years or IDs. Only returns brands with data in these years. +- `studies` - A list of study names or IDs. Only returns brands included in these studies. +- `tags` - A list of brand tag keys or IDs from `list-brand-tags`. Passing several tags returns brands carrying *any* + of them, not all of them. +- `include_study_history` - Set to `true` to list every study each brand appears in. By default each brand only + carries a `study_coverage` summary (years, and per market the number of studies, first and latest year and the latest + study), because long-running brands are in over a thousand studies. +- `page` - The page number. Results are returned 50 brands per page. + +### Brand Data Tools + +These tools return the BAV brand data, each for one data model. Every one of them takes the shared +[data selection parameters](#selecting-data) below, and some take a few extra parameters of their own. + +| Tool | What it does | Extra parameters | Access | +|---------------------------------|------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|----------------------------------------------| +| `get-pillar-data` | The four pillars of brand equity: Differentiation, Relevance, Esteem and Knowledge. | `metrics` | BAV users. | +| `get-powergrid-data` | Brand Strength and Brand Stature, the PowerGrid position. | `metrics` | BAV users. | +| `get-imagery-data` | Imagery (perception) attributes describing how people see a brand. | `metrics`, `score_type` | BAV users. | +| `get-personality-data` | Personality, a higher-level summary built from the imagery attributes. | `metrics`, `score_type` | BAV users. | +| `get-archetypes-data` | The twelve brand archetypes. Supports a competitive mode. | `comparison_categories`, `comparison_collections` | BAV users. | +| `get-commitment-funnel-data` | The Commitment Funnel: the behavioural and emotional relationship between brands and consumers. | - | BAV users. | +| `get-usage-data` | Usage on a scale from Never Used to Regularly Use. | `metrics`, `score_type` | BAV users. | +| `get-preferences-data` | Preference on a scale from Would Never Use to One I Prefer. | `metrics`, `score_type` | BAV users. | +| `get-recommendation-data` | Whether consumers would recommend the brand to a friend. | `metrics`, `score_type` | BAV users. | +| `get-brand-worth-data` | The Brand Worth Map: "worth paying more for" versus "providing good value". | - | BAV users. | +| `get-perception-swot-data` | A Brand Perception SWOT of the brand against its category or a collection, across imagery attributes. Requires `brands`. | `comparison_categories`, `comparison_collections`, `enable_drivers`, `x_axis_driver`, `y_axis_driver` | BAV users. | +| `get-category-drivers-data` | Which imagery attributes drive the equity pillars within a category or collection. | `categories`, `collections`, `driver_metrics`, `x_axis_metric`, `y_axis_metric` | BAV users. | +| `get-correspondence-map-data` | A correspondence (perception) map of brands against imagery attributes, for positioning and whitespace analysis. | `categories`, `collections`, `selectedMetricKeys` | BAV users. | +| `get-toplist-data` | The top-ranking brands for one or more metrics, by percentile rank. No `brands` parameter. | `metrics` (required), `categories`, `amount` (1-200, default 10) | BAV users. | +| `get-influence-data` | How influential a brand is and what makes it influential. | `metrics` | Users with access to Influence. | +| `get-customer-experience-data` | Perceived customer experience through the Super CX analysis. | - | Users with access to Super CX. | +| `get-creative-premium-data` | The Creative Premium rank, creativity and influence scores. | - | Users with access to Creative Premium. | +| `get-partnership-exchange-data` | Compares the imagery of a brand and a potential partner to find partnership opportunities. | Takes a single `brand` and `partner` (both required) instead of `brands`. | Users with access to the Imagery Exchange Map. | + +#### Selecting data + +The brand data tools share these parameters: + +- `studies` - A list of study IDs. **This is how data is selected, and it is required to get data back.** A study is + one market and year of one study type. Get the study IDs from `get-markets`. +- `brands` - A list of brand names or IDs. +- `audiences` - A list of audience names or IDs to segment the data by. If left out, the "All Adults" audience is used, + and the response says that it was assumed. +- `countries` - A list of country names or codes (e.g. `GB`). +- `years` - A list of years (e.g. `2025`). + +`countries` and `years` do **not** return data on their own. A market and year can be covered by more than one type of +study (for example the standard BAV study and a SnapBAV study), and these are not interchangeable. Rather than guess, +the tool responds with the matching studies, the recommended one marked, and asks the agent to call it again with an +explicit `studies` value. If `studies` is given, any `countries` and `years` are ignored. The server never picks a +study on the agent's behalf. See [studies](./concepts.md#studies-not-markets-and-years) for more on how this works. + +Studies the user does not have access to are dropped from the request. If none are left, the tool responds as if no +study had been given. + +#### Limiting metrics with `metrics` + +Many brand data tools accept an optional `metrics` parameter, a list of metric keys that limits the response to a +subset of the model's metrics. If it is left out, all of the model's metrics are returned. The allowed keys are listed in +each tool's definition, so your agent can see them without another call. `get-glossary` with `type` set to `metrics` +explains what each key means. + +For `get-toplist-data`, `metrics` is required and decides which metrics the brands are ranked on. + +#### Choosing scores with `score_type` + +`get-imagery-data`, `get-personality-data`, `get-usage-data`, `get-preferences-data` and `get-recommendation-data` +accept an optional `score_type`: + +- `rank` - Percentile rank scores from 0 to 100, ranked against all brands in the study. +- `percentage` - The percentage of respondents. + +Imagery and personality default to `rank`. Usage, preferences and recommendation default to `percentage`. The default +is stated in each tool's definition. See [rank vs percentage](./concepts.md#rank-vs-percentage-scores) for how to read +the two. + +#### Data that is still generating + +Brand data is aggregated on demand. The first time anyone asks for a particular study and audience combination, the +data may not exist yet. Instead of returning an empty result, the tool starts generating it and replies with a +message starting `DATA GENERATING`, asking the agent to tell the user and call the tool again shortly with the same +parameters. This usually takes a minute or two. + +If only part of a request is still generating, the tool returns the data it has and prepends a notice listing what is +still being prepared. See [data generation](./concepts.md#data-generation) for details. + +### Collection Tools + +Collections are saved lists of brands. The collection IDs can also be used as `comparison_collections` or +`collections` in the brand data tools. + +| Tool | What it does | Access | +|---------------------------------|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| +| `create-collection` | Creates a collection from a `name` and a list of `brand_ids`. Set `is_public` to make it public (private by default). | Users who can create collections. | +| `update-collection` | Updates a collection's name and/or public status. | Users who can update collections and may edit that collection. | +| `add-brands-to-collection` | Adds brands to a collection. | Users who can update collections and may manage its brands. | +| `remove-brands-from-collection` | Removes brands from a collection. | Users who can update collections and may manage its brands. | +| `share-collection` | Shares a collection with up to 10 people by email, with `view` (default) or `edit` permission. | Users who can share collections and collaborate on that collection. | + +### Audience Tools + +These tools let an agent build audiences (custom respondent segments) and then use them to segment the brand data. +See [audiences](../../audiences/audiences.md) for more about how audiences are structured. + +| Tool | What it does | Access | +|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------| +| `get-audience-metrics` | Lists the metrics that can be used as audience criteria, with their IDs, types and value dictionaries. Call this before creating or updating an audience. | Users who can view audiences. | +| `get-audience-groups` | Lists the groups audiences can be organised into. | Users who can view audiences. | +| `get-audience-studies` | Lists the studies an audience is available in, with its respondent count and projected population in each, to size it before analysis. | Users who can view audiences. | +| `create-audience` | Creates an audience with its definitions, segments and metrics in one call. | Users who can create audiences. | +| `update-audience` | Updates an audience's name, description or group. Does not change its definitions. | Users who can build audiences. | +| `add-audience-definition` | Adds a definition (for example a market-specific override) to an existing audience. | Users who can build audiences. | +| `update-audience-definition` | Replaces all segments and metrics of a definition with the structure provided. | Users who can build audiences. | +| `deploy-audience` | Deploys an audience (making it active and starting processing) or undeploys it. | Users who can build audiences. | +| `get-audience-question-data` | How a market's population answered BAV survey questions about themselves, such as demographics and attitudes. Takes up to 25 `questions` plus the shared data selection parameters (without `brands`). | Users with access to Audience 360. | + +### AURA Tools + +AURA is WPP Open's AI brand research, powered by WPP BAV. It fields BAV surveys to large language models instead of +human respondents, so the numbers describe how AI models perceive a brand rather than how consumers do. + +| Tool | What it does | +|-------------------------------|----------------------------------------------------------------------------------------------------------------------| +| `get-aura-studies` | Lists the markets and waves with AURA data and their study IDs. AURA is fielded often (often monthly), so `latest_only` returns just the most recent wave per market. | +| `get-aura-audiences` | Lists the AI perspectives to segment by: "All LLMs" (the default), individual AI providers and individual models. | +| `get-aura-pillar-data` | How AI models perceive a brand across the four pillars. | +| `get-aura-powergrid-data` | How AI models position a brand on the PowerGrid. | +| `get-aura-personality-data` | The personality attributes AI models associate with a brand. | +| `get-aura-imagery-data` | The imagery attributes AI models associate with a brand. | +| `get-aura-drift-data` | The drift score: the gap between how AI models and consumers perceive a brand. Up to 25 brands, grouped by `brand` or `country`. | + +All AURA tools require access to AURA. -- `get-brands` -- `get-markets` -- `get-sectors` -- `get-categories` -- `get-audiences` +The AURA data tools take the same `brands`, `countries`, `years`, `audiences`, `studies` and `metrics` parameters as the +brand data tools, with two differences: `audiences` takes AI perspectives from `get-aura-audiences`, and `studies` is +optional. If no AURA studies are given, the tool uses the latest AURA study per market (or every AURA study in the given +`years`). `get-aura-drift-data` takes `ai_audiences` and `consumer_audiences` instead of `audiences`. + +### Media Performance Tools + +| Tool | What it does | +|--------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `get-media-performance-funnels` | Lists the funnel stages campaigns are classified by. | +| `get-media-performance-business-units` | Lists business units (franchises), optionally for given brands. | +| `get-media-performance-media-sub-types` | Lists media sub-types, optionally for given brands. | +| `get-media-performance-campaign-classifications` | Lists campaign classifications, optionally for given brands. | +| `get-campaign-performance-data` | Weekly campaign performance (impressions, clicks, costs, visits, conversions, revenue) per brand, country, funnel, business unit, media sub-type and classification. Use `fields` to limit the metrics returned. Derived metrics such as CPM are not included. | +| `get-campaign-performance-benchmarks` | Aggregated performance with derived metrics (CPM, CPC, CTR, ROI and more) already calculated. Use `group_by` to aggregate by country, funnel, business unit, media sub-type, campaign classification, month, week or in total. | -### Tool Parameters +The media performance tools are only available to users who have access to media performance data for at least one +brand. -Each tool accepts a set of parameters that your agent will try to extract from the user input. This includes: +### Display Tools -- Brands -- Countries (with a note to prefer using ISO 3166-1 alpha-2 codes) -- Years -- Audiences +The display tools render interactive charts directly in the conversation, in clients that support MCP Apps. They take +the same data selection parameters as the brand data tools. See [MCP Apps](./mcp-apps.md) for details. -Behind the scenes the BAV systems will automatically handle fallbacks and make assumptions should a parameter not be -provided. +| Tool | What it does | Access | +|-------------------------------------|----------------------------------------------------------------------|------------| +| `display-pillar-chart` | A column chart of the four pillars. | BAV users. | +| `display-imagery-chart` | A chart of imagery attributes. | BAV users. | +| `display-powergrid-chart` | A PowerGrid scatter chart with its quadrants. | BAV users. | +| `display-brand-relationship-chart` | Preferences, recommendation and usage, with a toggle between them. | BAV users. | :::note Unstable Responses We do not promise that MCP server responses will be stable over time, in contrast to traditional API responses. The diff --git a/docs/ai/mcp/best-countries.md b/docs/ai/mcp/best-countries.md index b7d13ba..0d4ec3c 100644 --- a/docs/ai/mcp/best-countries.md +++ b/docs/ai/mcp/best-countries.md @@ -5,12 +5,12 @@ sidebar_label: Best Countries Server # Best Countries MCP Server The Best Countries MCP Server provides access to the WPP BAV proprietary Best Countries data through a set of tools that -can be called by AI agents. This allows you to build AI applications that can leverage the rich brand data collected -by BAV to provide insights, recommendations, and analysis. +can be called by AI agents. This allows you to build AI applications that can leverage how people around the world +perceive countries and cities to provide insights, recommendations, and analysis. ## Connecting to the server -Our remote MCP server supports both SSE (Server-Sent Events) and Streamable HTTP. +Our remote MCP server uses the Streamable HTTP transport. To connect to the Best Countries MCP server, you need to use the following URL: ``` @@ -22,45 +22,57 @@ The domain will change to `mcp.wppbav.com` in the future. We'll communicate this period so you can update your applications accordingly. ::: -For authorization, please see the [access and authorization](./access-authorization.md) section. +For authorization, please see the [access and authorization](./access-authorization.md) section. For step-by-step +instructions for your client, see [connecting clients](./connecting-clients.md). ## Available Tools -The BAV MCP server provides two sets of data tools: +The Best Countries MCP server provides two sets of data tools: - **Country Data**: Tools that provide insights into how countries are perceived. - **City Data**: Tools that provide insights into how cities are perceived. +Which tools you see depends on your permissions. Each group of tools is enabled separately, so a user without access to +city data will not see the city tools at all. + **Tip:** You can ask the agent to list the available tools interactively, or you can use -the [list tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#listing-tools) mechanism as +the [list tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#listing-tools) mechanism as defined in the MCP specification. This will return the full tool definitions including parameters and descriptions. ### Country Data Tools -- `get-country-factors-data` -- `get-country-perceptions-data` -- `get-country-doing-business-data` -- `get-country-education-data` -- `get-country-visit-consideration-data` -- `get-product-origin-data` +| Tool | Description | Requires access to | +|----------------------------------------|------------------------------------------------------------------------------------------------------------------------------|--------------------| +| `get-country-factors-data` | How people perceive countries across the 10 high-level factors that correlate with GDP growth, including the overall Best Country rank. | Country data | +| `get-country-perception-data` | How people perceive countries on a wide range of imagery attributes. | Country data | +| `get-country-doing-business-data` | Whether business decision makers would consider doing business in countries. | Country data | +| `get-country-education-data` | Whether people would consider going to university in countries. | Country data | +| `get-country-visit-consideration-data` | Whether people would consider visiting countries for vacation. | Country data | +| `get-product-origin-data` | Whether people would consider buying products from countries across various product categories. | Origin Index data | ### City Data Tools -- `get-city-perceptions-data` -- `get-city-doing-business-data` -- `get-city-visit-consideration-data` +| Tool | Description | Requires access to | +|-------------------------------------|-----------------------------------------------------------------------------|--------------------| +| `get-city-perception-data` | How people perceive cities on a wide range of imagery attributes. | City data | +| `get-city-doing-business-data` | Whether business decision makers would consider doing business in cities. | City data | +| `get-city-visit-consideration-data` | Whether people would consider visiting cities for vacation. | City data | ### Tool Parameters -Each tool accepts a set of parameters that your agent will try to extract from the user input. This includes: +All tools accept the same set of optional parameters, which your agent will try to extract from the user input: -- Countries (with a note to prefer using ISO 3166-1 alpha-2 codes) -- Cities -- Years -- Audiences -- Score Types +- `countries` (country tools) - ISO 3166-1 alpha-2 country codes or country IDs. When left empty, all studied countries + are returned. +- `cities` (city tools) - Complete city names or city IDs. When left empty, all studied cities are returned. +- `years` - Year numbers or year IDs. Data from 2022 onwards is supported. +- `audiences` - Audience names or IDs. +- `scoreType` - Either `rank` (how the country or city ranks against all others) or `score` (a 100-point score from + worst to best against all others). -Behind the scenes the BAV systems will automatically handle fallbacks should a parameter not be provided. +Behind the scenes the BAV systems will automatically handle fallbacks should a parameter not be provided. If neither +countries nor years are given, the latest year of Best Countries data is used. If no audience is given, the default +audience is used. :::note Unstable Responses We do not promise that MCP server responses will be stable over time, in contrast to traditional API responses. The diff --git a/docs/ai/mcp/concepts.md b/docs/ai/mcp/concepts.md new file mode 100644 index 0000000..0fa391a --- /dev/null +++ b/docs/ai/mcp/concepts.md @@ -0,0 +1,118 @@ +--- +sidebar_label: Concepts for Agents +--- + +# Concepts for Agents + +This page explains the handful of BAV concepts that matter most when you build an agent on top of the +[BAV MCP server](./bav.md). The tool descriptions and responses already explain most of this to the model, but knowing +it yourself makes it much easier to write good system prompts and to understand why an agent behaves the way it does. + +## Studies, not markets and years + +In BAV, data is collected in **studies**. A study is one market and one year (or period) of one **study type**. Most +markets are surveyed at most once a year, the US is generally surveyed three times a year, and some markets less often +than yearly. + +A market and year can be covered by more than one study type, and they are not interchangeable: + +| Type | What it is | +|--------------|-------------------------------------------------------------------------------------------------------------| +| `syndicated` | The full, standard BAV study. Marked as `recommended`, and the one to use unless the user asks for something else. | +| `snap` | SnapBAV. Covers fewer brands and is more volatile between waves. | +| `fused` | AO+BAV. Probabilistically modelled to enable Audience Origin audience targeting. Not comparable to the standard study. | +| `custom` | A bespoke study with a tailored sample, brand set or questions. | + +Because of this, the brand data tools select data by **study ID**, not by market and year. The typical flow is: + +1. Call `get-markets` (optionally with `countries` and `years`) to list the available studies. +2. Pick the study marked `recommended`, unless the user asked for a different kind. +3. Call the data tool with that study ID in `studies`. + +If an agent calls a data tool with only `countries` and `years`, the tool does not guess. It replies with a message +starting `NEEDS SELECTION`, listing the matching studies, and the agent calls the tool again with the study it chose. +This is a normal, successful response rather than an error, so the agent keeps going instead of giving up. + +A few more things to keep in mind: + +- If a study carries a `caveat`, the agent should tell the user which study was used and relay the caveat. +- Each study has a `methodology` (the version of the BAV model, such as BAV 3). Metrics are calculated differently + between versions, so comparisons across methodologies should be flagged. +- Every data response starts with a `request` block that echoes the filters used, including `studies_used` and an + `assumed` list of anything that was defaulted (such as the "All Adults" audience). +- AURA studies are kept separate. The brand data tools never return AURA data, and the AURA tools never return consumer + data. AURA studies are listed by `get-aura-studies`, not `get-markets`. + +## Rank vs percentage scores + +Most BAV metrics can be reported as more than one score type. The two an agent will meet most often are: + +- **Percentile rank** - A score from 0 to 100 (where 100 is best) showing where the brand sits among all brands in the + study. It is **not** a percentage and should never be shown with a `%` sign. In responses, these keys end in + `_percentile_rank`. +- **Percentage** - The percentage of respondents who rated the brand a certain way. + +Some guidance worth passing on to your agent when it reads ranks: + +- A change in rank can come from the brand changing, from other brands changing, or both. +- Ranks are evenly distributed, so year-to-year moves are often bigger in the mid-range (30-70). A change of around 20 + ranks is noteworthy but not dramatic. +- As a rule of thumb, 75+ is great, 50-75 is good, 25-50 is not great and below 25 is very poor. + +Tools that support both score types take a `score_type` parameter (`rank` or `percentage`). The default depends on the +data model and is stated in the tool's definition. + +Some data models are **category-specific**: respondents saw both the brand and the category it was surveyed in, so the +category should be part of any analysis, and a brand can appear once per category in a study. Others are +**category-agnostic**: respondents only saw the brand name, which lets you look at the brand in culture as a whole +rather than within a narrow category. Each data response includes instructions that say which kind it is. + +## Data generation + +Brand data is aggregated on demand for each combination of study and audience. The first time anyone asks for a +combination, it may not have been built yet. When that happens the tool starts generating it and replies with a +message starting `DATA GENERATING`, telling the agent to let the user know and to call the tool again shortly with the +same parameters. Generation usually takes a minute or two. + +There are two variants: + +- **Pending** - Nothing that was asked for is ready yet. The response only contains the generating notice. +- **Partial** - Some combinations are ready and some are not. The response contains the data that is ready, with a + notice in front listing the combinations that are still generating. + +Neither is an error, and the agent should not tell the user that the data does not exist. This is different from a row +with a `message` such as "No data available for Brand X in Germany 2025", which means the brand was not covered in that +study. + +If your agent runs unattended, make sure it retries after a short wait rather than ending the task. + +## Brand names and variations + +A brand can be known by different names, for example in different markets or languages. The brand data responses +include several name fields: + +- `brand` - The brand's global name. +- `brand_variation` - The name variation the brand was surveyed under in that study. +- `local_name` - The brand's local name in that market, where there is one. +- `brand_name` - The name to show: the global, local or translated name depending on the user's brand name display + setting, without qualifiers. + +Empty fields are left out of the response, so not every row carries all of these. + +When searching with `get-brands`, names may not match exactly. A good agent offers close matches and asks the user +before including them. When two different brands share a name, the `qualifier` field tells them apart. + +## Using the glossary + +`get-glossary` returns definitions for three kinds of items, chosen with `type`: + +- `metrics` - The computed brand metrics the data tools return, with their keys, groups and available score types. +- `measures` - The core survey questions respondents answer about brands. Used to build audiences. +- `questions` - The survey questions respondents answer about themselves. Used to build audiences and with + `get-audience-question-data`. + +Pass `studies` whenever you can, so the agent only sees what was actually measured in the studies it is working with. + +The metric keys from the glossary are what the other tools expect, for example in `metrics` on the brand data tools, +the required `metrics` on `get-toplist-data` and `driver_metrics` on `get-category-drivers-data`. Encourage your agent to +look up a definition before interpreting an unfamiliar metric, rather than inferring its meaning from the key. diff --git a/docs/ai/mcp/connecting-clients.md b/docs/ai/mcp/connecting-clients.md new file mode 100644 index 0000000..cb674ed --- /dev/null +++ b/docs/ai/mcp/connecting-clients.md @@ -0,0 +1,147 @@ +--- +sidebar_label: Connecting Clients +--- + +# Connecting Clients + +Our MCP servers are remote servers that work with any MCP client that supports the Streamable HTTP transport and the +standard MCP authorization flow. In most clients, all you need to provide is the server URL. The client will then +open a browser window where you sign in with your WPP Okta account and authorize the client to access data on your +behalf. + +:::warning Authorized Agent Environments +Please note that you may only connect to the BAV MCP servers from authorized agent environments that have been +vetted by WPP legal. If you are not sure whether your environment is authorized, please reach out. See +[access and authorization](./access-authorization.md) for more information. +::: + +## Server URLs + +| Server | URL | +|---------------------------------------|-----------------------------------------------| +| [BAV](./bav.md) | `https://mcp-beta.wppbav.com/v1/bav` | +| [Best Countries](./best-countries.md) | `https://mcp-beta.wppbav.com/v1/best-countries` | +| [Financial Data](./financial-data.md) | `https://mcp-beta.wppbav.com/v1/futures` | +| [Market Share](./market-share.md) | `https://mcp-beta.wppbav.com/v1/market-share` | + +:::note +The domain will change to `mcp.wppbav.com` in the future. We'll communicate this change in advance with a good notice +period so you can update your applications accordingly. +::: + +Each server is added to your client separately, so you can choose to only connect the servers you need. + +## WPP Open + +All of the BAV MCP servers are available in WPP Open via Creative Studio and its agent builder. + +This allows you to build agents that can access the BAV MCP servers directly from within WPP Open, +and leverage the capabilities of the agent builder to create custom workflows and integrations. + +To get started with using the BAV MCP servers in WPP Open, follow these steps: + +1. Log in to your WPP Open account and navigate to Creative Studio. +2. Open your playground or one of your existing projects. +3. Create a new agent or open an existing one in the Agent Builder. +4. In the Instructions tab, open Tools & Settings and find the server you want in the Tools list. + +And that's it! You can now use the MCP servers in your WPP Open agents to enhance their capabilities and create more +powerful workflows. + +The [Social Data](./social.md) connector by our partner Sightly is also available in WPP Open as a third-party +connector, and can be combined with the BAV MCP servers in the same agent. + +### Using pre-built agents + +Getting started with the BAV MCP server has a little learning curve in familiarizing yourself with BAV data, concepts +and methodology to make the most out of it. If you are building an internal tool, please do get in touch with us for +assistance. + +To help you get started quickly, we have created some pre-built agents that create summaries and reports using key BAV +data. These can be helpful to drop in as part of a multi-step agent workflow. They are managed by BAV and make it +super-simple for you to get started with BAV data with minimal setup. See [BAV Agents](../agents.md) for more +information. + +## Claude + +In the Claude apps, our servers can be added as custom connectors. Add a new custom connector, give it a name and +paste the server URL. Claude will then take you through the sign-in and authorization flow. Depending on your plan, an +organization administrator may need to add the connector for your organization first. + +In Claude Code, you can add a server from the command line: + +```bash +claude mcp add --transport http wpp-bav https://mcp-beta.wppbav.com/v1/bav +``` + +Then run `/mcp` inside Claude Code to sign in and authorize the server. + +## ChatGPT + +ChatGPT supports remote MCP servers as custom connectors, depending on your plan and workspace settings. Create a new +connector using the server URL and choose OAuth as the authentication method. ChatGPT will then take you through the +sign-in and authorization flow. Your workspace administrator may need to enable custom connectors first. + +## Microsoft 365 Copilot + +To use our servers in Microsoft 365 Copilot, add them as a tool to an agent in +[Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent), and +then publish the agent to Microsoft 365 Copilot and Teams. + +1. Open your agent in Copilot Studio and go to the **Tools** page. +2. Select **Add a tool**, then **New tool**, then **Model Context Protocol**. +3. Enter a **Server name**, a **Server description** and the **Server URL**, for example + `https://mcp-beta.wppbav.com/v1/bav`. Describe what the server does clearly, as the agent uses the description to + decide when to call it. For example: "WPP BAV brand equity data: brands, studies, pillars, imagery and other brand + metrics." +4. Choose **OAuth 2.0** as the authentication type and **Dynamic discovery** as the OAuth type. Our servers support + dynamic client registration, so no client ID or secret is needed. +5. Select **Create**, then **Next**. +6. Select **Create a new connection**, sign in with your WPP account and authorize access, then select + **Add to agent**. + +Repeat the steps for each server you want the agent to use. Each user of the agent signs in with their own account, +so they only see the tools they have access to. + +Your organization's data policies for Power Platform connectors also apply to MCP servers, so an administrator may +need to allow the connection first. + +## GitHub Copilot in VS Code + +In VS Code, you can add the servers to an `mcp.json` file, either in your workspace (`.vscode/mcp.json`) or in your +user configuration: + +```json +{ + "servers": { + "wpp-bav": { + "type": "http", + "url": "https://mcp-beta.wppbav.com/v1/bav" + }, + "wpp-best-countries": { + "type": "http", + "url": "https://mcp-beta.wppbav.com/v1/best-countries" + } + } +} +``` + +When the server starts, VS Code will prompt you to sign in and authorize it. The tools are then available to Copilot in +agent mode. + +## Other clients + +Any MCP client that supports remote servers over Streamable HTTP can connect to our servers. A few things to keep in +mind: + +- **Streamable HTTP only.** The servers only accept `POST` requests. The older SSE (Server-Sent Events) transport is not + supported, and `GET` and `DELETE` requests to the server URL return `405 Method Not Allowed`. +- **OAuth discovery.** Clients that support the MCP authorization flow will discover everything they need from the + `401` response and the `.well-known` metadata, including dynamic client registration. See + [access and authorization](./access-authorization.md) for details. +- **Personal access tokens.** If your client does not support OAuth but lets you set custom headers, you can pass a + personal access token as a Bearer token in the `Authorization` header instead. +- **Local-only clients.** If your client only supports local (stdio) servers, you can use a proxy such as + [mcp-remote](https://www.npmjs.com/package/mcp-remote) to connect it to a remote server. + +If you have trouble connecting a specific client, please [get in touch with us](mailto:bavsupport@wpp.com). diff --git a/docs/ai/mcp/financial-data.md b/docs/ai/mcp/financial-data.md index 8a52750..f49d842 100644 --- a/docs/ai/mcp/financial-data.md +++ b/docs/ai/mcp/financial-data.md @@ -5,11 +5,11 @@ sidebar_label: Financial Data Server # Financial Data MCP Server The Financial Data MCP Server provides access to the financial data via BAV Futures for listed companies around the -world through a set of tools that can be called by AI agents. +world through a set of tools that can be called by AI agents. It also provides daily share prices for listed companies. ## Connecting to the server -Our remote MCP server supports both SSE (Server-Sent Events) and Streamable HTTP. +Our remote MCP server uses the Streamable HTTP transport. To connect to the Financial Data MCP server, you need to use the following URL: ``` @@ -21,27 +21,46 @@ The domain will change to `mcp.wppbav.com` in the future. We'll communicate this period so you can update your applications accordingly. ::: -For authorization, please see the [access and authorization](./access-authorization.md) section. +For authorization, please see the [access and authorization](./access-authorization.md) section. For step-by-step +instructions for your client, see [connecting clients](./connecting-clients.md). ## Available Tools -The Financial Data MCP server provides a set of tools that you can use to access various types of data. +The Financial Data MCP server provides a set of tools that you can use to access various types of data. All tools are +available to every user who can connect to the server. **Tip:** You can always ask the agent to list the available tools interactively, or you can use -the [list tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#listing-tools) mechanism as +the [list tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#listing-tools) mechanism as defined in the MCP specification. This will return the full tool definitions including parameters and descriptions. -- `get-analyst-ratings` -- `get-balance-sheet` -- `get-cash-flow` -- `get-earnings` -- `get-financial-overview` -- `get-income-statement` +| Tool | Description | +|--------------------------|---------------------------------------------------------------------------------------------------------------| +| `get-analyst-ratings` | Analyst ratings and recommendations, including buy/sell/hold ratings and price targets. | +| `get-balance-sheet` | Balance sheet data, including assets, liabilities, and shareholders' equity. | +| `get-cash-flow` | Cash flow statement data, including operating, investing, and financing activities. | +| `get-earnings` | Earnings data and reports, including historical and estimated earnings. | +| `get-financial-overview` | A comprehensive financial overview, including general information, highlights, and valuation metrics. | +| `get-income-statement` | Income statement data, including revenue, expenses, and profitability. | +| `get-stock-prices` | Daily share prices (open, high, low, close, adjusted close and volume), optionally within a date range. | ### Tool Parameters -Each tool expects to receive the stock ticker symbol as a required parameter, including the exchange suffix where -applicable (e.g., `AAPL.US` for Apple Inc. on NASDAQ). +Each tool expects to receive the stock ticker symbol as a required `ticker` parameter, in the format +`TICKER.EXCHANGE` (e.g., `AAPL.US` for Apple Inc.). All US companies use the `.US` exchange code. + +In addition, `get-stock-prices` accepts two optional parameters to limit the date range: + +- `from` - The first trading day to return, as `YYYY-MM-DD`. Omit to start from the beginning of the published history. +- `to` - The last trading day to return, as `YYYY-MM-DD`. Omit to run to the most recent close. + +### Share Prices + +The share prices from `get-stock-prices` are returned oldest first, with one row per trading day. Weekends and market +holidays are therefore absent from the data. When comparing prices over time, use the adjusted close, which is +corrected for splits and dividends. + +A single call returns at most 500 trading days. If the requested range is longer, only the most recent 500 trading days +are returned and the response says so. Narrow the range with `from` and `to` to read an earlier period. :::note Unstable Responses We do not promise that MCP server responses will be stable over time, in contrast to traditional API responses. The diff --git a/docs/ai/mcp/intro.md b/docs/ai/mcp/intro.md index b7c8943..13b553c 100644 --- a/docs/ai/mcp/intro.md +++ b/docs/ai/mcp/intro.md @@ -1,9 +1,13 @@ +--- +sidebar_label: Introduction +--- + # Introduction By using an MCP server you can connect your AI models and agents directly to BAV data. This allows your agents to retrieve up-to-date information from BAV and use it to answer user queries, generate insights, and power your workflows. -MCP (Model Control Protocol) is a standard protocol that allows AI models and agents to interact with external data +MCP (Model Context Protocol) is an open standard that allows AI models and agents to interact with external data sources through a set of defined tools. Think of it as an API but specifically designed for AI models and agents to call tools to retrieve data. @@ -15,12 +19,28 @@ requests for new MCP tools, please let us know. We currently offer a few different MCP servers that you can connect to depending on which dataset you want to access. Please refer to each server's documentation for more details on the available tools. -- [BAV MCP Server](./bav.md) - Access to all WPP BAV data. -- [Best Countries MCP Server](./best-countries.md) - Access to WPP BAV Best Countries data. -- [Financial Data MCP Server](./financial-data.md) - Access to financial data for listed companies worldwide, powered by - BAV Futures. -- [Market Share MCP Server](./market-share.md) - Access to market share data via Euromonitor for brands and companies. -- [Social Data MCP Server](./social.md) - Access to social data via Sightly +| Server | URL | Data | +|-------------------------------------------------|-----------------------------------------------|-------------------------------------------------------------------| +| [BAV](./bav.md) | `https://mcp-beta.wppbav.com/v1/bav` | WPP BAV brand equity data and metadata. | +| [Best Countries](./best-countries.md) | `https://mcp-beta.wppbav.com/v1/best-countries` | WPP BAV Best Countries data on how countries and cities are seen. | +| [Financial Data](./financial-data.md) | `https://mcp-beta.wppbav.com/v1/futures` | Financial data and share prices for listed companies worldwide. | +| [Market Share](./market-share.md) | `https://mcp-beta.wppbav.com/v1/market-share` | Euromonitor market share for brands and companies. | + +:::note +The domain will change to `mcp.wppbav.com` in the future. We'll communicate this change in advance with a good notice +period so you can update your applications accordingly. +::: + +In addition to our own servers, the [Social Data](./social.md) connector by our partner Sightly is available as a +third-party connector in WPP Open. It gives your agents access to real-time social and news listening data that works +well alongside BAV brand perception data. + +## Getting started + +- **[Concepts](./concepts.md)** explains how the servers, tools and data fit together. +- **[Access & Authorization](./access-authorization.md)** covers who can connect and how authorization works. +- **[Connecting Clients](./connecting-clients.md)** shows how to add the servers to Claude, ChatGPT, Copilot, WPP Open + and other MCP clients. ## Building an internal tool? diff --git a/docs/ai/mcp/market-share.md b/docs/ai/mcp/market-share.md new file mode 100644 index 0000000..59d7269 --- /dev/null +++ b/docs/ai/mcp/market-share.md @@ -0,0 +1,116 @@ +--- +sidebar_label: Market Share Server +--- + +# Market Share MCP Server + +The Market Share MCP Server provides access to Euromonitor market share data for brands and companies through a set of +tools that can be called by AI agents. Market share can be sliced by category, geography, data type and year, and +read alongside BAV brand equity data for brands and companies that have been linked to BAV. + +## Connecting to the server + +Our remote MCP server uses the Streamable HTTP transport. +To connect to the Market Share MCP server, you need to use the following URL: + +``` +https://mcp-beta.wppbav.com/v1/market-share +``` + +:::note +The domain will change to `mcp.wppbav.com` in the future. We'll communicate this change in advance with a good notice +period so you can update your applications accordingly. +::: + +For authorization, please see the [access and authorization](./access-authorization.md) section. For step-by-step +instructions for your client, see [connecting clients](./connecting-clients.md). + +### Access + +The Market Share tools require access to Euromonitor data. Users without it will not see any tools when connecting +to the server. Please [get in touch with us](mailto:bavsupport@wpp.com) if you need access. + +## How the data works + +The server gives your agent a set of instructions on how to use the data. These are worth knowing if you are building +on top of the server, as they explain how to read the responses. + +- **Euromonitor has its own IDs.** Euromonitor keeps its own catalog of brands, companies, categories, geographies, + industries and data types, and none of them are BAV's. Look up IDs with the `get-euromonitor-*` tools first. A BAV ID + passed as a Euromonitor ID does not fail. It silently reads as a different entity. +- **Linked BAV brands and companies.** Where a Euromonitor brand or company has been linked to a BAV brand or company, + the lookup tools say so. Only linked entries can be read alongside BAV brand equity data. You can also pass BAV brand + and company IDs directly using the `bav_brands` and `bav_companies` parameters, which are matched through the link. +- **Every share query must be narrowed.** A share query has to name at least one entity, category, geography or + industry. A year on its own would return the whole of Euromonitor and is refused. +- **Null is not zero.** The measures arrive in separate extracts and are merged into one row. A `null` value is a + figure that was not supplied for that slice, never a zero. +- **Only licensed industries are available.** An industry that is not listed by `get-euromonitor-industries` is not + licensed, which means there is no data at all rather than a share of zero. + +## Available Tools + +The Market Share MCP server provides two sets of tools: + +- **Catalog Tools:** Look up the Euromonitor IDs that the share tools filter on. +- **Share Data Tools:** Fetch market share figures for brands and companies. + +**Tip:** You can always ask the agent to list the available tools interactively, or you can use +the [list tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#listing-tools) mechanism as +defined in the MCP specification. This will return the full tool definitions including parameters and descriptions. + +### Catalog Tools + +All catalog tools accept an optional `search` parameter to search by part of a name, and a `page` parameter for +pagination. Results are returned 50 at a time, and the response includes a `next_page` value until there are no more +pages. + +| Tool | Description | Additional parameters | +|-------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| +| `get-euromonitor-brands` | Search Euromonitor brands, including the owning Euromonitor company and the BAV brand each one is linked to. | `companies` (Euromonitor company IDs), `linked_to_bav` (true/false) | +| `get-euromonitor-companies` | Search Euromonitor companies, including the BAV company each one is linked to. | `linked_to_bav` (true/false) | +| `get-euromonitor-categories` | Search the tree of Euromonitor categories that a market share is a share of. | `industries` (Euromonitor industry IDs), `level` (depth in the tree), `parent` (category ID) | +| `get-euromonitor-geographies` | Search the tree of regions, countries and cities, including the BAV country each one lines up with. | `type` (`region`, `country` or `city`) | +| `get-euromonitor-industries` | Search the Euromonitor industries, the top of the category tree and the whole of what is licensed. | - | +| `get-euromonitor-data-types` | Search the data types, i.e. what a share row measures, such as retail value or retail volume. | `industries` (Euromonitor industry IDs), `categories` (Euromonitor category IDs) | + +A few things to keep in mind when working with the catalogs: + +- Euromonitor names brands and companies its own way, often using the legal name for companies (e.g. "Procter & Gamble + Co, The"). Searching for a distinctive part of the name works better than the full name. +- A parent category's figures cover the whole of it, so a parent should never be summed with its children. +- A region's figures are its own, never the sum of the countries in it. + +### Share Data Tools + +| Tool | Description | +|----------------------------|------------------------------------------------------------------------------------------------------------------| +| `get-brand-market-share` | How much of a category a brand holds in a market. | +| `get-company-market-share` | How much of a category a company holds in a market. This is the company's own share, not the sum of its brands. | + +Both tools accept the following parameters. Each parameter accepts an array of IDs or names (up to 50 values). + +- `brands` - Euromonitor brand IDs or names, from `get-euromonitor-brands`. Brand tool only. +- `bav_brands` - BAV brand IDs or names. Matched through the link on the brand. An unlinked brand returns nothing. + Brand tool only. +- `companies` - Euromonitor company IDs or names, from `get-euromonitor-companies`. +- `bav_companies` - BAV company IDs or names. Matched through the link on the company. An unlinked company returns + nothing. +- `categories` - Euromonitor category IDs or names. +- `geographies` - Euromonitor geography IDs or names. Not BAV country IDs. +- `industries` - Euromonitor industry IDs or names. +- `data_types` - Euromonitor data type IDs or names, e.g. "Retail Value RSP". Pass one, since rows that only differ by + data type measure different things. +- `years` - Year numbers, e.g. `2024`. Must be combined with another filter. +- `score_type` - Which measure each row carries: `actual_usd` (default), `actual_local`, `percentage` (the share of the + category in that market) or `rank` (the position in the category, where 1 is the largest). + +At least one of the brand, company, category, geography or industry parameters must be provided. If a name or ID cannot +be matched, the tool returns an error naming the parameter rather than an empty result, so that your agent can look up +the correct value and try again. + +:::note Unstable Responses +We do not promise that MCP server responses will be stable over time, in contrast to traditional API responses. The +data may be updated, and the models may also change how they respond to user requests. If you need stable responses for +your application we suggest prompting for a structured data response after the agent has called the tools. +::: diff --git a/docs/ai/mcp/mcp-apps.md b/docs/ai/mcp/mcp-apps.md new file mode 100644 index 0000000..82d7bb4 --- /dev/null +++ b/docs/ai/mcp/mcp-apps.md @@ -0,0 +1,79 @@ +--- +sidebar_label: MCP Apps (Charts) +--- + +# MCP Apps + +The [BAV MCP server](./bav.md) includes a set of display tools that render interactive BAV charts directly in the +conversation. They are built on [MCP Apps](https://github.com/modelcontextprotocol/ext-apps), an extension to the +Model Context Protocol that lets a tool come with its own user interface. + +## How it works + +Each display tool declares a UI resource (a `ui://` URI) in its tool metadata. When an agent calls the tool, a client +that supports MCP Apps loads that resource, an HTML page served with the `text/html;profile=mcp-app` MIME type, and +renders it in a sandboxed frame inside the conversation. The tool result carries the chart configuration and data as +structured content, which the page uses to draw the chart. + +You don't need to fetch the resources yourself. A client with MCP Apps support handles this automatically. + +## Client support + +MCP Apps is an extension, so not every MCP client supports it. Support is growing across AI assistants and agent +frameworks, but it varies between clients and versions, so please check the documentation of the client you use. + +In a client without MCP Apps support, the display tools can still be called, but no chart is shown. The agent only +receives a short text confirmation. If your client does not support MCP Apps, have your agent use the regular data tools +instead. + +## Display tools + +| Tool | UI resource | Chart | +|------------------------------------|----------------------------------|---------------------------------------------------------------------------------------------| +| `display-pillar-chart` | `ui://pillar-chart` | A column chart of the four pillars of brand equity: Differentiation, Relevance, Esteem and Knowledge. | +| `display-imagery-chart` | `ui://imagery-chart` | A chart of brand imagery (perception) attributes. | +| `display-powergrid-chart` | `ui://powergrid-chart` | A square scatter chart of Brand Strength against Brand Stature, with the Leadership, Momentum, Fatigued and Unfocused quadrants and the Mass Market line. | +| `display-brand-relationship-chart` | `ui://brand-relationship-chart` | Preferences, Recommendation and Usage in one chart, with a toggle between the three. | + +All display tools are available to users who can view BAV brand data. + +### Parameters + +The display tools take the same data selection parameters as the brand data tools: `studies` (required to get a +chart), `brands`, `audiences`, `countries` and `years`. Selecting a study works exactly as described in +[selecting data](./bav.md#selecting-data). If only `countries` and `years` are given, the tool asks the agent to choose +a study first. If the data is still being generated, the tool says so and the agent should call it again shortly. + +Some display tools take extra parameters: + +- `display-imagery-chart` + - `chart_type` - `line` (default), `bar` or `tree`. The treemap is only available when there is a single series. + - `score_type` - `rank` (default) or `percentage`. + - `sort_by` - A series ID to sort the attributes by, highest first. If left out, attributes are sorted alphabetically. +- `display-brand-relationship-chart` + - `data_type` - The data shown first: `preferences` (default), `recommendation` or `usage`. + +### Interacting with the charts + +All charts: + +- Follow the client's light or dark theme. +- Offer a fullscreen mode when the client supports it. +- Link to the same view in the WPP BAV platform, so the user can continue the analysis there. + +The imagery chart also lets the user switch between line and bar, between rank and percentage scores, and change the +sort order, without another tool call. The brand relationship chart lets the user switch between preferences, +recommendation and usage. + +## Charts and commentary + +The display tools return a chart, not the data. The text the agent receives only confirms that the chart is shown, and +points it to the matching data tool. If you want the agent to comment on what the chart shows, it should also call the +data tool: + +| Display tool | Data tool(s) | +|------------------------------------|----------------------------------------------------------------------| +| `display-pillar-chart` | `get-pillar-data` | +| `display-imagery-chart` | `get-imagery-data` | +| `display-powergrid-chart` | `get-powergrid-data` | +| `display-brand-relationship-chart` | `get-preferences-data`, `get-recommendation-data`, `get-usage-data` | diff --git a/docs/ai/mcp/social.md b/docs/ai/mcp/social.md index 1eaa848..7ffde2f 100644 --- a/docs/ai/mcp/social.md +++ b/docs/ai/mcp/social.md @@ -1,6 +1,21 @@ +--- +sidebar_label: Social Data +--- + # Social Data MCP Server -The social data MCP Server enables the intersection of real-time data listening and brand perception with data from our partner [Sightly](htps://sightly.com). The server provides Model Context Protocol (MCP) tools that allow clients to add these capabilities in conjunction with their existing data stack, enabling AI assistants and applications to access comprehensive brand profiles, discover cultural trends, and gather real-time insights from news articles and social media posts. +The Social Data MCP Server, provided by our partner [Sightly](https://sightly.com), enables the intersection of +real-time data listening and brand perception. The server provides Model Context Protocol (MCP) tools that allow +clients to add these capabilities in conjunction with their existing data stack, enabling AI assistants and +applications to access comprehensive brand profiles, discover cultural trends, and gather real-time insights from news +articles, social media posts, TikTok and YouTube. + +:::info Availability +The Social Data MCP Server is available as a connector in WPP Open. See +[Connecting clients: WPP Open](./connecting-clients.md#wpp-open) for how to add it to your agents. +::: + +This page is based on Sightly's MCP server documentation (version 1.36.0). ### Key Capabilities @@ -8,13 +23,15 @@ The social data MCP Server enables the intersection of real-time data listening - **Cultural Trend Analysis**: Discover macro cultural trends and patterns by aggregating news moments and social media narratives - **Real-Time News Insights**: Find clustered news moments (day-to-day events) and search individual news articles - **Social Media Intelligence**: Track social media narratives (day-to-day conversations) and analyze individual posts -- **TikTok Trend Discovery**: Get trending TikTok hashtags filtered by category, date range, and optional search terms +- **TikTok Trend Discovery**: Get trending TikTok hashtags filtered by category, date range, country, and optional search terms - **YouTube Intelligence**: Search YouTube videos and channels from a curated dataset with filtering by language, country, categories, and engagement metrics +- **YouTube Creator Discovery**: Find creators by topic or by who watches them, profile known channels including audience demographics and partnership eligibility, and track how interest in a topic is moving on YouTube - **Audience Targeting**: Generate platform-specific audience targeting segments for ad campaigns across multiple platforms ### Data Hierarchy The server organizes data in a hierarchical structure: + - **Individual Level**: Articles and social media posts provide detailed, granular content - **Cluster Level**: Moments (news clusters) and Narratives (social media clusters) group related content - **Trend Level**: Trends aggregate moments and narratives to reveal long-term cultural patterns @@ -32,24 +49,73 @@ The server organizes data in a hierarchical structure: ``` **Hierarchy**: + - **Social Posts** → Clustered into **Narratives** (day-to-day conversations) - **Articles** → Clustered into **Moments** (day-to-day news events) - **Narratives + Moments** → Aggregated into **Trends** (long-term cultural patterns) +## Array Parameters + +Every parameter documented as an array below also accepts a string, for clients that cannot send real JSON arrays: + +- A JSON-encoded array, such as `"[\"Nike\", \"Adidas\"]"`, is parsed into the equivalent array. +- Any other string, such as `"Nike"`, is treated as a single-element array. + +Sending a real array is still preferred. The documented maximum item counts apply either way, and values are never +split on commas, so `"Nike, Adidas"` is one value rather than two. + ## Tools +### get_brand_profile + +Get a brand's profile: industry, business and mentality summaries, mission, vision and value statements, key terms, +related entities, and the brand's answers to opinion and scenario questions. + +**Note**: Brand profiles must be created and submitted in Sightly before they can be retrieved via this tool. +Only profiles owned by your account or its child accounts are returned. `brand_name` is matched approximately, so close +variants of the profile name still find it. + +**Parameters**: +- `brand_name` (string, required): Brand name + +**Returns**: plain text, not JSON. It opens with a `BRAND NAME: ` line followed by bracketed sections, each +omitted when empty: + +- `[BRAND_INFORMATION]`: `Label: value` lines for industry, business summary, mentality summary, mission, vision and value statements, and key terms +- `[COMPANIES]`, `[INFLUENCERS]`, `[EVENTS]`, `[SOCIAL_CAUSES]`, `[PHILANTHROPIC_ORGANIZATIONS]`: one `name → relationship (type)` line per related entity +- `[OPINION_QUESTIONS]`, `[SCENARIO_QUESTIONS]`: one `question → answer` line per question + +When no matching profile is found, the response is the plain message `No profile found for `. + +**Example**: +```json +{ + "tool": "get_brand_profile", + "arguments": { + "brand_name": "Nike" + } +} +``` + ### get_trends -Discover macro cultural trends (long-term patterns). +Discover macro cultural trends (long-term patterns) from news and social media. Does not cover YouTube; for how +interest in a topic is moving on YouTube, use `get_youtube_creator_insights` with `insight_type="trends"`. **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Search terms. If not provided, returns top trends sorted by total article count (biggest trends first) -- `start_date` (string, optional): YYYY-MM-DD format, max 60 days old -- `end_date` (string, optional): YYYY-MM-DD format, max 60 days old -- `brand` (array, optional): Filter by brand names in top 10 brands (max 5) -- `person` (array, optional): Filter by person names in top 10 people (max 5) -- `sort_by` (string, optional): Sort order when no search terms provided. Options: "size" (total article count - biggest trends) or "recency" (earliest article date - most recent trends). Only valid without search terms +- `search_terms` (array, 0-3 terms, optional): Search terms. If not provided, returns top trends sorted by total article count (biggest trends first). Cannot be combined with `sort_by` +- `start_date` (string, optional): `YYYY-MM-DD` format, earliest `2026-01-01` +- `end_date` (string, optional): `YYYY-MM-DD` format, earliest `2026-01-01` +- `brand` (array, optional): Filter to trends that mention these brands (max 5, OR'd). Case-insensitive substring match against every brand on the trend, not only the 10 listed in `top_brands` +- `person` (array, optional): Filter to trends that mention these people (max 5, OR'd). Case-insensitive substring match against every person on the trend, not only the 10 listed in `top_people` +- `sort_by` (string, optional): Only valid without search terms. Options: `"size"` (default, total article count - biggest trends) or `"recency"` (most recent trends first) - `limit` (int, optional): Results per search term (default: 3, max: 5) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster + +Each trend in `sample_trends` includes `title`, `overview`, `bullet_points`, `start_date`, `end_date`, +`total_moment_count`, `total_narrative_count`, `total_article_count`, `total_post_count`, `article_count_timeline` and +`post_count_timeline` (see [Timelines](#timelines)), `top_brands` and `top_people` (up to 10 names each), and +`representative_moments` and `representative_narratives` (up to 3 each). **Example with search terms**: ```json @@ -68,8 +134,8 @@ Discover macro cultural trends (long-term patterns). { "tool": "get_trends", "arguments": { - "start_date": "2024-11-01", - "end_date": "2024-11-30", + "start_date": "2026-09-01", + "end_date": "2026-09-30", "limit": 5 } } @@ -80,13 +146,23 @@ Discover macro cultural trends (long-term patterns). Find clustered news articles about topics (day-to-day events). **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Search terms. If not provided, returns top moments sorted by article count (biggest story clusters first) -- `start_date` (string, optional): YYYY-MM-DD format, max 60 days old -- `end_date` (string, optional): YYYY-MM-DD format, max 60 days old +- `search_terms` (array, 0-3 terms, optional): Search terms. If not provided, returns top moments sorted by article count (biggest story clusters first). Cannot be combined with `sort_by` +- `start_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. Supports hour/minute precision; for a whole-day search use `T00:00:00` +- `end_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search use `T23:59:59` - `category` (array, optional): Filter by content categories (max 5) - `entity` (array, optional): Filter by entity names (max 5) -- `sort_by` (string, optional): Sort order when no search terms provided. Options: "size" (article count - biggest clusters) or "recency" (earliest article date - most recent moments). Only valid without search terms +- `sort_by` (string, optional): Only valid without search terms. Options: `"size"` (default, article count - biggest clusters) or `"recency"` (most recent moments first) - `limit` (int, optional): Results per search term (default: 8, max: 20) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster + +Each moment in `sample_news_moments` includes `title`, `summary`, `start_date`, `end_date`, `total_article_count`, +`article_count_timeline` (see [Timelines](#timelines)), and a `representative_article` with `title`, `url`, +`published_at`, `publisher_name`, `publisher_domain` and `publisher_location`. + +**Sensitive topics**: each moment may include `sensitive_topics`, the brand-safety topics the moment substantially +involves. Values come from: sex, drugs, crime, death, hacking, terrorism, tobacco, alcohol, military conflict, politics, +obscenity, conspiracy, guns, human rights, kids channel, racism. An empty list means the moment was evaluated and none +were flagged; the field is omitted for moments that have not been evaluated yet. **Example with search terms**: ```json @@ -94,21 +170,34 @@ Find clustered news articles about topics (day-to-day events). "tool": "get_news_moments", "arguments": { "search_terms": ["climate change"], - "start_date": "2024-01-01", - "end_date": "2024-01-31", + "start_date": "2026-09-01T00:00:00", + "end_date": "2026-09-30T23:59:59", "category": ["environment"], "limit": 10 } } ``` +**Example narrowing to a specific hour band**: +```json +{ + "tool": "get_news_moments", + "arguments": { + "search_terms": ["breaking news"], + "start_date": "2026-05-13T08:00:00", + "end_date": "2026-05-13T10:00:00", + "limit": 10 + } +} +``` + **Example without search terms** (browse top moments): ```json { "tool": "get_news_moments", "arguments": { - "start_date": "2024-01-01", - "end_date": "2024-01-31", + "start_date": "2026-09-01T00:00:00", + "end_date": "2026-09-30T23:59:59", "limit": 10 } } @@ -119,13 +208,31 @@ Find clustered news articles about topics (day-to-day events). Find clustered social media posts about topics (day-to-day conversations). **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Search terms. If not provided, returns top narratives sorted by post count (most discussed first) -- `start_date` (string, optional): YYYY-MM-DD format, max 60 days old -- `end_date` (string, optional): YYYY-MM-DD format, max 60 days old +- `search_terms` (array, 0-3 terms, optional): Search terms. If not provided, returns top narratives sorted by post count (most discussed first). Cannot be combined with `sort_by` +- `start_date` (string, optional): `YYYY-MM-DD` format, earliest `2026-01-01` +- `end_date` (string, optional): `YYYY-MM-DD` format, earliest `2026-01-01` - `sentiment` (string, optional): Filter by sentiment: `very_positive`, `positive`, `neutral`, `negative`, `very_negative` -- `platform` (array, optional): Filter by platforms (max 5): Twitter, Reddit, Truth Social, Pinterest, Instagram, Bluesky, TikTok, Threads -- `sort_by` (string, optional): Sort order when no search terms provided. Options: "size" (post count - most discussed) or "recency" (earliest post date - most recent narratives). Only valid without search terms +- `platform` (array, optional): Filter by platforms (max 5): X, Reddit, Truth Social, Pinterest, Instagram, Bluesky, TikTok, Threads +- `theme` (array, optional): Filter by themes (max 5). Same theme list as [`get_social_media_posts`](#get_social_media_posts) +- `entity` (array, optional): Filter to narratives about a specific named person, brand, organization, product, event, or place (max 5), e.g. `["Messi", "Nike"]`. Case-insensitive substring match; multiple values are OR'd. Covers the roughly two-thirds of narratives where an entity was detected. For broad topics or moods, use `search_terms` instead +- `min_likes` (int, optional): Only return narratives whose posts have at least this many likes in total (must be ≥ 0). Narratives with no like total are excluded +- `min_comments` (int, optional): Only return narratives whose posts have at least this many comments in total (must be ≥ 0). Narratives with no comment total are excluded +- `min_shares` (int, optional): Only return narratives whose posts have at least this many shares/reposts in total (must be ≥ 0). Coverage is partial (roughly a quarter of narratives), so prefer `min_likes`/`min_comments` for general engagement filtering +- `country` (array, optional): Only return narratives with at least one post from these countries, as ISO 3166-1 alpha-2 codes (max 5, OR'd, any case), e.g. `["gb", "au"]`. This is an inclusion filter, not a dominance filter: a global narrative with a single UK post matches `["gb"]`. To see what a market is talking about, compare that country's `country_counts` entry against `total_post_count` on each record. Roughly a third of posts have no known country +- `sort_by` (string, optional): Only valid without search terms. Options: `"size"` (default, post count - most discussed) or `"recency"` (most recent narratives first) - `limit` (int, optional): Results per search term (default: 8, max: 20) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster +- `include_original_text` (bool, optional, default `false`): Add `original_text` to each narrative's `representative_post`, i.e. the post's text in the language it was written in. Set `true` only when the source-language wording matters. Absent for posts that were already English + +Each narrative in `sample_social_media_narratives` includes `title`, `summary`, `start_date`, `end_date`, +`total_post_count`, a `representative_post` (with `text`, `platform`, `post_publish_date` and, when available, `url` and +`author_name`), and `source_counts`. The `representative_post` text is always English: non-English posts are +machine-translated, so quote it as a translation unless you request `include_original_text`. + +Each narrative also includes: +- `sentiment_score`: the cluster's overall sentiment on a -100 (most negative) to 100 (most positive) scale. The `sentiment` filter buckets this score: `very_negative` (below -75), `negative` (below -25), `neutral` (-25 to 25), `positive` (above 25), `very_positive` (above 75) +- `total_likes`, `total_comments`, `total_shares`: cluster-level engagement totals (omitted when unavailable) +- `country_counts` and `country_unclassified_count`: a per-country breakdown of where the posts come from (top 10 countries, with the remainder folded into an `other` entry) **Example with search terms**: ```json @@ -133,22 +240,22 @@ Find clustered social media posts about topics (day-to-day conversations). "tool": "get_social_media_narratives", "arguments": { "search_terms": ["AI"], - "start_date": "2024-01-01", - "end_date": "2024-01-31", + "start_date": "2026-09-01", + "end_date": "2026-09-30", "sentiment": "positive", - "platform": ["Twitter", "Reddit"] + "platform": ["X", "Reddit"] } } ``` -**Example without search terms** (browse top narratives): +**Example without search terms** (browse top narratives in a market): ```json { "tool": "get_social_media_narratives", "arguments": { - "start_date": "2024-01-01", - "end_date": "2024-01-31", - "platform": ["Twitter"], + "start_date": "2026-10-01", + "end_date": "2026-10-07", + "country": ["gb"], "limit": 10 } } @@ -159,14 +266,21 @@ Find clustered social media posts about topics (day-to-day conversations). Search individual news articles (detailed content). **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Keep complete concepts together (e.g., "renewable energy policy" not ["renewable", "energy"]). If not provided, returns most recent articles sorted by publish date -- `start_date` (string, optional): YYYY-MM-DD format, max 60 days old -- `end_date` (string, optional): YYYY-MM-DD format, max 60 days old +- `search_terms` (array, 0-3 terms, optional): Keep complete concepts together (e.g., `"renewable energy policy"` not `["renewable", "energy"]`). If not provided, returns most recent articles sorted by publish date. Non-English articles carry an English machine translation alongside the original text, and searches match both +- `start_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search use `T00:00:00` +- `end_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search use `T23:59:59` - `publisher` (string, optional): Filter by publisher name -- `category` (array, optional): Filter by content categories (max 5) +- `category` (array, optional): Filter by content categories (max 5). Do not prefix values with `news/` - `entity` (array, optional): Filter by entity names (max 5) -- `publisher_location` (string, optional): Filter by country: United States, United Kingdom, Canada +- `publisher_location` (string, optional): Filter by the publisher's country, as one full English country name: United States, United Kingdom, Canada, Germany, Spain, Turkey, South Africa, Nigeria, China, India, Philippines, Thailand, Mexico, Brazil, Argentina, France, Italy, Netherlands, Australia, Poland, United Arab Emirates, Japan. Articles with no recorded publisher location never match +- `language_code` (array, optional): Filter by the article's original language as lowercase ISO 639-3 codes (max 5, OR'd), e.g. `["spa", "deu"]`. Supported: eng, spa, deu, fra, ita, pol, nld, ara, jpn, por, zho, hin, tur, tha, rus, kor, fas, vie. Coverage is partial (only newer articles carry a language code), so use it to narrow by language rather than to find all English coverage - `limit` (int, optional): Results per search term (default: 10, max: 50) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster +- `include_full_body` (bool, optional, default `false`): Return each article's full body text. By default `body` is truncated to 2,000 characters. Non-English articles also carry `original_title`/`original_body` (pre-truncated to roughly 500 characters, unaffected by this flag) + +Each article in `sample_news_articles` includes `title`, `body`, `url`, `published_at`, `publisher_name`, +`publisher_domain`, `publisher_location`, `categories`, `entities`, `scenarios`, and `language_code`. Fields with no +value are omitted. **Example with search terms**: ```json @@ -180,6 +294,19 @@ Search individual news articles (detailed content). } ``` +**Example narrowing to a specific hour band**: +```json +{ + "tool": "get_news_articles", + "arguments": { + "search_terms": ["product launch"], + "start_date": "2026-05-13T08:00:00", + "end_date": "2026-05-13T10:00:00", + "limit": 20 + } +} +``` + **Example without search terms** (browse recent articles): ```json { @@ -197,12 +324,28 @@ Search individual news articles (detailed content). Search individual social media posts (detailed content). **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Keep complete concepts together. If not provided, returns most recent posts sorted by publish date -- `start_date` (string, optional): YYYY-MM-DD format, max 60 days old -- `end_date` (string, optional): YYYY-MM-DD format, max 60 days old -- `platform` (array, optional): Filter by platforms (max 5): Twitter, Reddit, Truth Social, Pinterest, Instagram, Bluesky, TikTok, Threads +- `search_terms` (array, 0-3 terms, optional): Keep complete concepts together. If not provided, returns most recent posts sorted by publish date. Use for topics, themes, concepts, or moods; use `entity` for specific named people, brands, products, events or places. Combine both to find a topic about a named entity +- `start_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search use `T00:00:00` +- `end_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search use `T23:59:59` +- `platform` (array, optional): Filter by platforms (max 5): X, Reddit, Truth Social, Pinterest, Instagram, Bluesky, TikTok, Threads - `theme` (array, optional): Filter by themes (max 5): discounts, purchase, appearance, churn, cost, ads, experience, craftmanship, transaction, criminal, loyalty, stock, taste, temperature, ambiance, delivery, fit, injury, knowledge, leadership, comfort, access, illness, location, restrooms, speed, satisfaction, wait times, cleanliness, durability, friendliness, selection +- `entity` (array, optional): Filter to posts about a specific named person, brand, organization, product, event, or place (max 5), e.g. `"Messi"`, `"Nike"`, `"FIFA World Cup"`. Case-insensitive substring match (`"messi"` matches `"Lionel Messi"`); multiple values are OR'd. Only covers the roughly half of posts where an entity was detected. Use short, distinctive fragments +- `min_likes` (int, optional): Only return posts with at least this many likes (must be ≥ 0). Posts with no like count are excluded +- `min_comments` (int, optional): Only return posts with at least this many comments (must be ≥ 0). Posts with no comment count are excluded +- `min_shares` (int, optional): Only return posts with at least this many shares/reposts (must be ≥ 0). Many platforms do not report shares, so this can sharply narrow results +- `min_author_followers` (int, optional): Only return posts whose author has at least this many followers (must be ≥ 0). Use for questions about influential or large accounts. Posts with no follower count are excluded, which drops platforms without a follower concept (Reddit, Facebook, Tumblr) entirely +- `country` (array, optional): Filter by the post's country of origin as ISO 3166-1 alpha-2 codes (max 5, OR'd, any case), e.g. `["us", "gb"]`. About half of all posts carry a country. Best-covered countries: us, th, gb, in, br, fr, tr, mx +- `language_code` (array, optional): Filter by the post's detected language as lowercase ISO 639-1 codes (max 5, OR'd), e.g. `["en", "ja"]`. Values must be lowercase (`"JA"` matches nothing). Pair with `country` to get a language within a market - `limit` (int, optional): Results per search term (default: 10, max: 50) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster +- `include_full_body` (bool, optional, default `false`): Return each post's full text. By default post text is truncated to 2,000 characters +- `include_original_text` (bool, optional, default `false`): Add `original_text` to each post, i.e. its text in the language it was written in. Absent for posts that were already English, so its presence signals a non-English original + +Each post in `sample_social_media_posts` includes `text`, `platform`, `url`, `post_publish_date`, `author_name`, +`themes`, `likes`, `comments`, `shares`, `author_followers`, `entities`, `country` and `language_code` (each omitted +when unavailable). Post text is always English: non-English posts are machine-translated on ingestion. Search is both +keyword and semantic, so a query in one language retrieves posts written in another; use `language_code` to restrict +results to an original language. **Example with search terms**: ```json @@ -210,7 +353,7 @@ Search individual social media posts (detailed content). "tool": "get_social_media_posts", "arguments": { "search_terms": ["climate action"], - "platform": ["Twitter"], + "platform": ["X"], "theme": ["experience"], "limit": 25 } @@ -229,15 +372,49 @@ Search individual social media posts (detailed content). } ``` +**Example filtering by entity and engagement**: +```json +{ + "tool": "get_social_media_posts", + "arguments": { + "entity": ["Nike"], + "search_terms": ["product recall"], + "min_likes": 100, + "min_comments": 10, + "limit": 25 + } +} +``` + +**Example filtering by market and language** (Japanese-language posts from Japan): +```json +{ + "tool": "get_social_media_posts", + "arguments": { + "search_terms": ["product launch"], + "country": ["jp"], + "language_code": ["ja"], + "limit": 25 + } +} +``` + ### get_tiktok_hashtags -Get trending TikTok hashtags. Can optionally filter by search terms or get top hashtags by category and date range. +Get trending TikTok hashtags. Can optionally filter by search terms or get top hashtags by category, date range and +country. **Parameters**: - `search_terms` (array, 0-3 terms, optional): Optional search terms to filter results. If not provided, returns top hashtags according to other parameters -- `category_name` (string, optional): Filter by TikTok category (default: "ALL"). Available categories: ALL, ACADEMIC_RESOURCES, ANIMATION_AND_COMICS, APPAREL_AND_ACCESSORIES, ART, AUTOMOTIVE, BABY_CARE, BABY_KIDS_AND_MATERNITY, BEAUTY, BEAUTY_AND_PERSONAL_CARE, BEAUTY_SERVICES, BUSINESS_AND_FINANCE, BUSINESS_SERVICES, CARD_AND_BOARD_GAMES, CAREER_AND_PROFESSIONAL_GROWTH, COLLEGE, COMEDY, COMMUNITY_UPDATES_AND_ISSUES, CONVENTIONAL_AND_MAINSTREAM_SPORTS, COOKING, CRAFTING_AND_CREATIONS, CULTURE, DANCE, DIARY_AND_VLOG, DRINKS, EATING_EXPERIENCES, EDUCATION, ENTERTAINMENT_AND_SPORTS_NEWS, ENVIRONMENT, EXERCISE_AND_FITNESS, EXTREME_AND_ADVENTURE_SPORTS, FAMILY, FINANCIAL_SERVICES, FOOD, FOOD_AND_BEVERAGE, FOOD_RECOMMENDATIONS, GADGETS_AND_INNOVATION, GAMES, GENERAL_TRAVEL, HAIR_CARE, HEALTH, HEALTH_AND_WELLNESS, HISTORY_AND_LITERATURE, HOME_AND_GARDEN, HOME_IMPROVEMENT, HOUSEHOLD_PRODUCTS, LEARNING_AND_DEVELOPMENT, LEISURE_AND_RECREATION_FACILITIES, LIFE_SERVICES, LIVESTOCK_AND_FARMING, MISCELLANEOUS_PERFORMANCES, MOVIES_AND_TV, MUSIC, NEWS_AND_ENTERTAINMENT, OTHER_BEAUTY, OTHER_FASHION, OTHER_TRANSPORTATION, OUTDOOR_RECREATION, OUTFITS, PERFORMING_ARTS, PERSONAL_PHOTOGRAPHY, PETS, PET_CARE_AND_ACCESSORIES, PHOTOGRAPHY, PRODUCTIVITY_AND_EFFICIENCY, ROMANCE, SCIENCE, SENSORY_EXPERIENCES, SHOWS_FESTIVALS_AND_EXHIBITIONS, SOFTWARE_AND_APPS, SPECIAL_EFFECTS, SPORTS, SPORTS_AND_OUTDOOR, SUPERNATURAL_AND_HORROR, TECHNOLOGY, TOYS_COLLECTIBLES_AND_MEMORABILIA, TRAVEL, VEHICLE_AND_TRANSPORTATION, VIDEO_GAMES, WILDLIFE_AND_EXOTIC_PETS -- `date_range` (string, optional): Filter by date range (default: "1DAY"). Available options: "1DAY", "7DAY", "30DAY", "120DAY" -- `limit` (int, optional): Number of results per search term or total results if no search term (default: 10, max: 50) +- `category_name` (string, optional): Filter by TikTok category. When omitted, a query with search terms spans all categories, while a query without search terms defaults to the cross-category `"ALL"` leaderboard. Available categories: ALL, ACADEMIC_RESOURCES, ANIMATION_AND_COMICS, APPAREL_AND_ACCESSORIES, ART, AUTOMOTIVE, BABY_CARE, BABY_KIDS_AND_MATERNITY, BEAUTY, BEAUTY_AND_PERSONAL_CARE, BEAUTY_SERVICES, BUSINESS_AND_FINANCE, BUSINESS_SERVICES, CARD_AND_BOARD_GAMES, CAREER_AND_PROFESSIONAL_GROWTH, COLLEGE, COMEDY, COMMUNITY_UPDATES_AND_ISSUES, CONVENTIONAL_AND_MAINSTREAM_SPORTS, COOKING, CRAFTING_AND_CREATIONS, CULTURE, DANCE, DIARY_AND_VLOG, DRINKS, EATING_EXPERIENCES, EDUCATION, ENTERTAINMENT_AND_SPORTS_NEWS, ENVIRONMENT, EXERCISE_AND_FITNESS, EXTREME_AND_ADVENTURE_SPORTS, FAMILY, FINANCIAL_SERVICES, FOOD, FOOD_AND_BEVERAGE, FOOD_RECOMMENDATIONS, GADGETS_AND_INNOVATION, GAMES, GENERAL_TRAVEL, HAIR_CARE, HEALTH, HEALTH_AND_WELLNESS, HISTORY_AND_LITERATURE, HOME_AND_GARDEN, HOME_IMPROVEMENT, HOUSEHOLD_PRODUCTS, LEARNING_AND_DEVELOPMENT, LEISURE_AND_RECREATION_FACILITIES, LIFE_SERVICES, LIVESTOCK_AND_FARMING, MISCELLANEOUS_PERFORMANCES, MOVIES_AND_TV, MUSIC, NEWS_AND_ENTERTAINMENT, OTHER_BEAUTY, OTHER_FASHION, OTHER_TRANSPORTATION, OUTDOOR_RECREATION, OUTFITS, PERFORMING_ARTS, PERSONAL_PHOTOGRAPHY, PETS, PET_CARE_AND_ACCESSORIES, PHOTOGRAPHY, PRODUCTIVITY_AND_EFFICIENCY, ROMANCE, SCIENCE, SENSORY_EXPERIENCES, SHOWS_FESTIVALS_AND_EXHIBITIONS, SOFTWARE_AND_APPS, SPECIAL_EFFECTS, SPORTS, SPORTS_AND_OUTDOOR, SUPERNATURAL_AND_HORROR, TECHNOLOGY, TOYS_COLLECTIBLES_AND_MEMORABILIA, TRAVEL, VEHICLE_AND_TRANSPORTATION, VIDEO_GAMES, WILDLIFE_AND_EXOTIC_PETS +- `date_range` (string, optional): Filter by date range (default: `"1DAY"`). Available options: `"1DAY"`, `"7DAY"`, `"30DAY"`, `"120DAY"` +- `country` (array, optional): Filter by country, as uppercase ISO 3166-1 alpha-2 codes (max 5). Supported: US, GB, CA, DE, ES, TR, ZA, NG, CN, IN, PH, TH, MX, BR, AR, FR, IT, NL, PL, AU, AE, JP, PT, KR, VN. Lowercase codes are accepted and upcased. When omitted, returns hashtags across all available countries +- `limit` (int, optional): Number of results per search term, or total results if no search term (default: 50, max: 200) +- `include_total_statistics` (bool, optional, default `true`): When `false`, omits `aggregate_stats`. Unlike the other tools, these statistics are computed over the returned rows (not the full dataset), so disabling them reduces response size but does not speed up the search + +Each row in `hashtags` includes `hashtag_name`, `rank_position`, `rank_change` (`"NEW"` or a signed position change), +`posts`, `posts_global_lifetime`, `views`, `views_global_lifetime`, `category_name`, `country_code`, `date_range`, +`created_at`, `top_country_list`, `audience_ages`, and `trending_history`. **Example**: ```json @@ -252,13 +429,14 @@ Get trending TikTok hashtags. Can optionally filter by search terms or get top h } ``` -**Example without search terms**: +**Example without search terms** (top beauty hashtags in the UK): ```json { "tool": "get_tiktok_hashtags", "arguments": { "category_name": "BEAUTY", "date_range": "1DAY", + "country": ["GB"], "limit": 15 } } @@ -271,7 +449,7 @@ Generate audience targeting segments for specific ad platforms based on an audie **Parameters**: - `audience_name` (string, required): The name of the audience to target (e.g., "Tech Enthusiasts", "Fitness Enthusiasts") - `audience_description` (string, required): A description of the audience to target (e.g., "Young professionals interested in technology and innovation") -- `platform` (string, required): Which platform to target. Available platforms: `Programmatic`, `YouTube`, `Pinterest`, `LinkedIn`, `TikTok`, `Snapchat`, `Meta`, `X`, `Reddit`, `Spotify` +- `platform` (string, required): Which platform to target. Available platforms: `Programmatic`, `YouTube`, `Pinterest`, `LinkedIn`, `TikTok`, `Snapchat`, `Meta`, `X`, `Reddit`, `Spotify`, `Search`. Matched case-insensitively; any other value returns an error. Always pass `X` for Twitter **Platform-Specific Targeting Types**: @@ -279,17 +457,20 @@ Generate audience targeting segments for specific ad platforms based on an audie - **Programmatic**: categories, genres, ctv_segments, olv_segments - **TikTok**: interests, video_interactions, creator_interactions, hashtags - **Meta**: detailed_demographics, interests, behaviors -- **Snapchat**: lifestyle, shoppers, visitors +- **Snapchat**: lifestyles, shoppers, visitors - **LinkedIn**: company_industries, member_interests, member_traits - **X**: interests, keywords, hashtags - **Pinterest**: interests, keywords - **Spotify**: interests, music_genres, playlist_themes, podcast_topics - **Reddit**: interest_groups, keywords +- **Search**: keywords + +Keywords and hashtags are written for the audience rather than chosen from the platform's published segment list. Every +other targeting type is chosen from that list. -**Returns**: Platform-specific targeting segments organized by demographics and targeting types. The response structure varies by platform but includes: -- Demographics (age, gender, income, parental status, etc.) - varies by platform -- Targeting segments (interests, behaviors, keywords, etc.) - varies by platform -- Audience name and platform identifier +**Returns**: a JSON object with two keys, both varying by platform: +- `demographics`: age, gender, income, parental status and similar options. YouTube and Search share the same demographic options +- `segments`: one list per targeting type above **Example**: ```json @@ -317,21 +498,28 @@ Generate audience targeting segments for specific ad platforms based on an audie ### get_youtube_videos -Search YouTube videos from the Brand Mentality curated YouTube dataset. +Search individual YouTube videos by keyword and publish date, from the Sightly curated YouTube dataset. Returns +videos, not creator analysis; for audience, engagement or partnership questions, use +[`get_youtube_creator_insights`](#get_youtube_creator_insights). **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Search terms for video title/description. If not provided, returns top videos sorted by view count (highest first) -- `start_date` (string, optional): Start date for video publish date filtering (YYYY-MM-DD format) -- `end_date` (string, optional): End date for video publish date filtering (YYYY-MM-DD format) -- `language` (array, optional): Filter by language codes (e.g., "en", "es") - max 5 -- `country` (array, optional): Filter by channel country codes (e.g., "US", "UK") - max 5 -- `iab_category` (array, optional): Filter by IAB taxonomy category names (e.g., "Sports", "Music") - max 5 -- `is_short` (boolean, optional): Filter by video type: true for Shorts, false for long-form, omit for all -- `exclude_kids_content` (boolean, optional): Exclude kids content when true +- `search_terms` (array, 0-3 terms, optional): Search terms for video title/description. If not provided, returns top videos sorted by view count (highest first). Cannot be combined with `sort_by` +- `start_date` (string, optional): Start of the video publish date range (`YYYY-MM-DD`, earliest `2005-02-14`). While `include_total_statistics` is `true` the range may not exceed 180 days; omit this to search the 180 days ending at `end_date` (or today) +- `end_date` (string, optional): End of the video publish date range (`YYYY-MM-DD`, earliest `2005-02-14`) +- `language` (array, optional): Filter by language codes (e.g., `"en"`, `"es"`) - max 5 +- `country` (array, optional): Filter by the channel's country as uppercase ISO 3166-1 alpha-2 codes (e.g., `"US"`, `"GB"`) - max 5. Case-sensitive: lowercase codes match nothing, and the UK's code is `GB`, not `UK` +- `iab_category` (array, optional): Filter by IAB taxonomy category names (e.g., `"Sports"`, `"Music"`) - max 5. Case-insensitive substring match, so `"Sports"` also matches more specific categories that contain it +- `is_short` (boolean, optional): Filter by video type: `true` for Shorts, `false` for long-form, omit for all +- `exclude_kids_content` (boolean, optional): Exclude kids content when `true` - `min_views` (int, optional): Minimum view count threshold - `min_channel_subscribers` (int, optional): Minimum channel subscriber count -- `sort_by` (string, optional): Sort order when no search terms provided. Options: "size" (view count - most viewed) or "recency" (publish date - newest videos). Only valid without search terms +- `sort_by` (string, optional): Only valid without search terms. Options: `"size"` (default, view count - most viewed) or `"recency"` (newest videos first) - `limit` (int, optional): Results per search term (default: 10, max: 50) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster and removes the 180-day cap + +Each video in `sample_youtube_videos` includes `title`, `description`, `video_id`, `url`, `published`, `views`, `likes`, +`duration` (seconds), `is_short`, `language`, `country`, `categories`, `channel_id`, `channel_title`, and +`channel_subscribers`. **Example with search terms**: ```json @@ -374,20 +562,26 @@ Search YouTube videos from the Brand Mentality curated YouTube dataset. ### get_youtube_channels -Search YouTube channels from the Brand Mentality curated YouTube dataset. +Search YouTube channels by keyword in their title or description, from the Sightly curated YouTube dataset. +Carries no audience or engagement data; pass `channel_id` values from here to +[`get_youtube_creator_insights`](#get_youtube_creator_insights) for a full profile. **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Search terms for channel title/description. If not provided, returns top channels sorted by subscriber count (highest first) -- `start_date` (string, optional): Start date for latest video publish date filtering (YYYY-MM-DD format) -- `end_date` (string, optional): End date for latest video publish date filtering (YYYY-MM-DD format) -- `language` (array, optional): Filter by language codes (e.g., "en", "es") - max 5 -- `country` (array, optional): Filter by country codes (e.g., "US", "UK") - max 5 -- `exclude_kids_content` (boolean, optional): Exclude kids content when true +- `search_terms` (array, 0-3 terms, optional): Search terms for channel title/description. If not provided, returns top channels sorted by subscriber count (highest first). Cannot be combined with `sort_by` +- `start_date` (string, optional): Start of the latest-video publish date range (`YYYY-MM-DD`, earliest `2005-02-14`). While `include_total_statistics` is `true` the range may not exceed 180 days; omit this to search the 180 days ending at `end_date` (or today) +- `end_date` (string, optional): End of the latest-video publish date range (`YYYY-MM-DD`, earliest `2005-02-14`) +- `language` (array, optional): Filter by language codes (e.g., `"en"`, `"es"`) - max 5 +- `country` (array, optional): Filter by the channel's country as uppercase ISO 3166-1 alpha-2 codes (e.g., `"US"`, `"GB"`) - max 5. Case-sensitive: lowercase codes match nothing, and the UK's code is `GB`, not `UK` +- `exclude_kids_content` (boolean, optional): Exclude kids content when `true` - `min_subscribers` (int, optional): Minimum subscriber count threshold - `min_views` (int, optional): Minimum total view count threshold - `min_video_count` (int, optional): Minimum video count on channel -- `sort_by` (string, optional): Sort order when no search terms provided. Options: "size" (subscriber count - most popular) or "recency" (latest video date - recently active channels). Only valid without search terms +- `sort_by` (string, optional): Only valid without search terms. Options: `"size"` (default, subscriber count - most popular) or `"recency"` (recently active channels first) - `limit` (int, optional): Results per search term (default: 10, max: 50) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster and removes the 180-day cap + +Each channel in `sample_youtube_channels` includes `title`, `description`, `channel_id`, `url`, `subscribers`, +`video_count`, `total_views`, `latest_video_published`, `language`, `country`, and `categories`. **Example with search terms**: ```json @@ -429,66 +623,233 @@ Search YouTube channels from the Brand Mentality curated YouTube dataset. } ``` +### get_youtube_creator_insights + +Discover and analyse YouTube creators, and track content trends, using Google's YouTube advertising data. This is +distinct from `get_youtube_videos` and `get_youtube_channels`, which search Sightly's own curated corpus by keyword and +date. Use those for historical content search; use this one for creator discovery, partnership suitability, audience +composition and trend trajectories. + +There are three creator modes, which are mutually exclusive. Provide exactly one of `topic`, `channel_ids`, or the +audience filters: + +| Mode | Use when | Returns | +|------|----------|---------| +| `topic` | Finding creators who cover a subject | Creators ranked by relevance to that topic | +| `channel_ids` | You already know the channels | Full profiles; the only mode with audience demographics and top videos | +| Audience filters | Finding creators by who watches them | Creators whose viewers match the profile | + +**Parameters**: +- `insight_type` (string, optional, default `"creators"`): `"creators"` finds or profiles creators; `"trends"` returns three years of monthly trend history for a topic, or what is trending for an audience +- `topic` (string, optional): A subject in plain words (e.g. `"electric vehicles"`, `"Nike"`). Matched internally to a Google Knowledge Graph entity; the match is returned as `resolved_topic` so an ambiguous term can be checked and retried +- `channel_ids` (array, optional, max 50): YouTube channel IDs such as `"UCX6OQ3DkcsbYNE6H8uQQuVA"`. Channel names cannot be looked up here; get IDs from `get_youtube_channels` first. Only the first `limit` IDs are profiled (10 by default) and the rest are silently dropped, so raise `limit` when passing more than 10. Not valid with `insight_type="trends"` +- `audience_age_ranges` (array, optional, max 5): Viewer age ranges: `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, `65+` +- `audience_genders` (array, optional, max 5): Viewer genders: `male`, `female` +- `audience_interests` (array, optional, max 5): Viewer interests in plain words (e.g. `"cooking"`). Describes the audience's interests, whereas `topic` describes what the creator makes content about. Each interest is matched to a Google Knowledge Graph entity; an interest that cannot be matched returns an error +- `country` (string, optional, default `"us"`): ISO 3166-1 alpha-2 code in any case (the UK is `gb`, Japan `jp`, India `in`). Creator results, audience data and trends are all specific to this country. Supports the 219 countries Google Ads can target, which excludes Taiwan (`tw`), Hong Kong (`hk`), and Puerto Rico (`pr`); any other code returns an error +- `limit` (int, optional): Defaults to 15 for creator searches and 10 for channel profiles (max 50 for profiles, 100 otherwise). Ignored for trends, which return at most 5 +- `include_brand_sentiment` (bool, optional, default `false`): Only applies with `insight_type="trends"` and a `topic` naming a brand. Returns up to 6 months of positive/neutral/negative view share plus AI-written summaries of what drove the positive and negative sentiment, derived from video content only (never comments). Fails for non-brand topics +- `include_top_videos` (bool, optional, default `true`): Only applies to channel profiles. Set `false` to roughly halve the response when you need only channel metrics and audience demographics + +**Data sharing consent**: Google gates non-public fields behind each creator's consent. When `data_sharing_consent` is +`false`, `engagement_rate`, the per-video averages, `languages` and `audience` are absent (not zero) for that creator. +Roughly a quarter of creators withhold consent, and large official channels often do. + +**No pagination**: Google returns roughly a thousand creators per search with no paging. `total_available` reports how +many matched; raise `limit` rather than expecting a second page. + +**Example - find creators covering a topic**: +```json +{ + "tool": "get_youtube_creator_insights", + "arguments": { + "topic": "electric vehicles", + "country": "us" + } +} +``` + +**Example - profile known channels** (the only way to get audience demographics): +```json +{ + "tool": "get_youtube_creator_insights", + "arguments": { + "channel_ids": ["UCX6OQ3DkcsbYNE6H8uQQuVA"], + "include_top_videos": true + } +} +``` + +**Example - find creators by their audience**: +```json +{ + "tool": "get_youtube_creator_insights", + "arguments": { + "audience_age_ranges": ["25-34", "35-44"], + "audience_interests": ["sustainable fashion"], + "country": "gb" + } +} +``` + +**Example - brand sentiment on YouTube**: +```json +{ + "tool": "get_youtube_creator_insights", + "arguments": { + "insight_type": "trends", + "topic": "Nike", + "include_brand_sentiment": true + } +} +``` + +**Response fields**: +- `country`: the country searched +- `resolved_topic`: the Knowledge Graph entity your topic text matched (`query`, `name`, `machine_id`, `description`), with `other_matches` listing alternatives +- `total_available` / `returned`: how many creators, channels or trends matched, versus how many were returned +- `channels_not_found`: requested channel IDs Google did not recognise +- `creators[]`: `name`, `channel_id`, `handle`, `channel_created`, `country`, `languages`, `relevance`, `data_sharing_consent`, `metrics` +- `profiles[]`: `name`, `channel_id`, `handle`, `channel_created`, `country`, `channel_type`, `languages`, `data_sharing_consent`, `metrics`, plus `audience` (viewer share by age range, gender, device and country), `content_topics`, and `top_videos` (up to 5). Profiles carry no relevance +- `trends[]`: `name`, trend direction, `views`, `views_indexed`, `audience_share`, `change_percent`, `history` (monthly), `brand_sentiment` +- `metrics`: subscribers, views, videos, likes, comments, Shorts views and videos, `engagement_rate`, per-video averages, whether the creator is an active Shorts or live stream creator, and `partnership_opportunities` (advertising products the creator is eligible for) + +**Reading trends**: +- Trend data lags by roughly two months; the newest month is the latest Google has published +- `change_percent` is a fraction (`0.19` = +19%). At the top level it compares the latest month with three months earlier; within `history`, each month compares with the month before +- `views_indexed` is 0-100 against the topic's own peak month, so it cannot be compared across topics +- `views` is the absolute view count for the latest month only +- `history` covers 36 months, newest first, for topic trends only. Audience trends return `audience_share` instead: the fraction of the requested audience that searched for or viewed the trend +- `brand_sentiment` shares are proportions of views and sum to 1 per month. Months Google lacks enough data for carry no shares + ## Response Structure -All search tools return results with clear distinction between total matches and sample results: +### Output Format + +Every tool returns its result as a single text block: + +- **Results found**: a short data context (guidance on how to interpret the payload), a blank line, then the payload. The payload is JSON for every tool except `get_brand_profile`, which returns plain text. +- **Nothing found**: a short plain-text message with no JSON, such as `No News Articles found for: . Try broader search terms or expand the date range.` This happens when no search term returns a result, when no brand profile matches, and when `get_youtube_creator_insights` finds no creators, profiles, or trends. When at least one search term returns results, the terms without any come back with an empty `sample_*` list instead. +- **Invalid input**: a tool error describing the problem, such as an unknown audience-targeting platform, `sort_by` sent with `search_terms`, or a YouTube date range wider than 180 days. + +### Search Tool Payloads + +`get_trends`, `get_news_moments`, `get_social_media_narratives`, `get_news_articles`, `get_social_media_posts`, +`get_youtube_videos`, and `get_youtube_channels` share one shape: -### Field Naming Convention -- `total_matches`: Total number of matching records in the database -- `sample_*`: The subset of example records returned (e.g., `sample_social_media_posts`, `sample_news_articles`) +- `search_start_date` / `search_end_date`: the range actually searched. `YYYY-MM-DD` for trends, narratives, and the YouTube tools; `YYYY-MM-DDTHH:MM:SS` for moments, articles, and posts. +- `search_results`: one entry per search term, or a single entry when browsing without search terms. Each entry holds: + - `search_term`: the term, omitted when browsing without search terms + - `aggregate_stats`: population statistics, omitted when `include_total_statistics=false` + - the sample list: `sample_trends`, `sample_news_moments`, `sample_social_media_narratives`, `sample_news_articles`, `sample_social_media_posts`, `sample_youtube_videos`, or `sample_youtube_channels` -This distinction helps clarify that `total_matches` represents the full scope of data matching your query, while the `sample_*` list contains representative examples limited by the `limit` parameter. +`aggregate_stats.total_matches` is the number of records matching the query in the whole database, while the +`sample_*` list holds representative examples capped by `limit`. Fields with no value are omitted from records rather +than returned as null. + +The other tools have their own shapes, described in their sections: `get_tiktok_hashtags` returns `hashtags` rows with +statistics over those rows, `get_youtube_creator_insights` returns creators, profiles, or trends with +`total_available` and `returned`, `get_audience_targeting` returns `demographics` and `segments`, and +`get_brand_profile` returns plain text. ### Aggregate Statistics -**Social Media Posts**, **News Articles**, **YouTube Videos**, and **YouTube Channels** return full aggregate statistics per search term: +Statistics cover every record matching the query, not just the returned sample. They are expensive to compute, so pass +`include_total_statistics=false` when you only need a few example records; the search is then significantly faster. +`get_youtube_creator_insights` has no `include_total_statistics` parameter. -- `get_social_media_posts`: `total_matches`, `platform_distribution`, `top_themes_distribution`, `date_distribution` -- `get_news_articles`: `total_matches`, `top_publishers_distribution`, `top_categories_distribution`, `publisher_location_distribution`, `date_distribution` +- `get_social_media_posts`: `total_matches`, `platform_distribution`, `top_themes_distribution`, `language_distribution`, `date_distribution`, `likes_stats`, `comments_stats`, `shares_stats` +- `get_news_articles`: `total_matches`, `top_publishers_distribution`, `top_categories_distribution`, `top_iab_categories_distribution`, `publisher_location_distribution`, `language_code_distribution`, `date_distribution` - `get_youtube_videos`: `total_matches`, `language_distribution`, `country_distribution`, `category_distribution`, `views_distribution`, `likes_distribution`, `date_distribution` - `get_youtube_channels`: `total_matches`, `language_distribution`, `country_distribution`, `subscriber_distribution`, `date_distribution` +- `get_social_media_narratives`: `total_matches`, `total_post_count`, `sentiment_distribution` (negative, neutral, positive), `platform_distribution`, `country_distribution`, `narrative_size_distribution`, `narratives_per_day_date_distribution`, `total_likes_stats`, `total_comments_stats`, `total_shares_stats` +- `get_news_moments`: `total_matches`, `total_article_count`, `moment_size_distribution`, `moments_per_day_date_distribution` +- `get_trends`: `total_matches`, `total_article_count`, `total_post_count`, `top_brands_distribution`, `top_people_distribution`, `trends_per_day_date_distribution` +- `get_tiktok_hashtags`: `views_distribution`, `posts_distribution`, `rank_change_distribution`, `top_country_distribution`, computed over the returned rows rather than the full dataset + +Notes on reading these: + +- **Date distributions** are `{"interval": ..., "buckets": [{"date": ..., "count": ...}]}` with up to 30 buckets. The interval (for example `1d`, `7d`, or `1M`) is chosen automatically to fit the searched range, so the `*_per_day_date_distribution` series are not always daily. +- **Cluster dates**: the `*_per_day_date_distribution` series count clusters (when stories broke, conversations started, or trends concluded), not their contents. For article or post volume over time, use `get_news_articles` or `get_social_media_posts`. +- **Multi-valued fields** (a narrative's platforms, an article's categories) count a record in every bucket it belongs to, so buckets can sum to more than `total_matches`. +- **Truncation**: distributions keyed by value (platforms, themes, languages, countries, publishers, categories, brands, people) list only the most frequent values, so a missing key means zero or a value outside the top ones. Range and date distributions list every bucket, including empty ones. +- **Engagement stats**: each `*_stats` object has `count`, `min`, `max`, `avg`, and `sum`. `count` reflects only records that have a value for that metric, so compare it to `total_matches` to gauge coverage. + +### Timelines -**News Moments**, **Social Media Narratives**, and **Trends** return `total_matches` count per search term. +`article_count_timeline` (trends and moments) and `post_count_timeline` (trends) show a record's own volume over its +lifetime. Records with 14 or fewer days of activity get one entry per active day; records with 15 to 90 days are +grouped into 7-day entries, and longer ones into calendar months. ### Example Response Structure +A `get_social_media_posts` response: + ```json { - "search_start_date": "2024-10-01", - "search_end_date": "2024-12-01", + "search_start_date": "2026-05-01T00:00:00", + "search_end_date": "2026-05-31T23:59:59", "search_results": [ { "search_term": "AI", "aggregate_stats": { "total_matches": 15420, - "platform_distribution": {"Twitter": 8500, "Reddit": 4200, "TikTok": 2720}, + "platform_distribution": {"X": 8500, "Reddit": 4200, "TikTok": 2720}, "top_themes_distribution": {"experience": 3200, "knowledge": 2800}, - "date_distribution": [{"date": "2024-11-01", "count": 520}, ...] + "language_distribution": {"en": 12100, "es": 1450, "ja": 980}, + "date_distribution": {"interval": "1d", "buckets": [{"date": "2026-05-01T00:00:00", "count": 520}, ...]}, + "likes_stats": {"count": 14200, "min": 0, "max": 84210, "avg": 312.5, "sum": 4437500}, + "comments_stats": {"count": 13980, "min": 0, "max": 9120, "avg": 27.4, "sum": 383052}, + "shares_stats": {"count": 1120, "min": 0, "max": 4300, "avg": 18.2, "sum": 20384} }, "sample_social_media_posts": [ - { "post_id": "...", "text": "...", ... } + { "text": "...", "platform": "X", "url": "...", "post_publish_date": "...", "likes": 1280, "comments": 64, "shares": 22, "entities": ["Lionel Messi", "FIFA World Cup"], ... } ] } ] } ``` -**Note**: Distribution fields prefixed with `top_` (e.g., `top_themes_distribution`) return the most frequent values, not exhaustive lists. - ## Common Rules ### Dates -- Format: `YYYY-MM-DD` (e.g., `"2024-01-15"`) -- Max age: 60 days from today -- Default: If not provided, uses 60-day lookback + +- **Date-only format** (`YYYY-MM-DD`): used by `get_trends` and `get_social_media_narratives`, earliest `2026-01-01` +- **UTC datetime format** (`YYYY-MM-DDTHH:MM:SS`): used by `get_news_articles`, `get_news_moments`, and `get_social_media_posts`, earliest `2026-01-01T00:00:00`. Naive UTC; do not include a timezone offset. For a whole-day search use `T00:00:00` to `T23:59:59` +- **YouTube tools** (`get_youtube_videos`, `get_youtube_channels`): `YYYY-MM-DD`, earliest `2005-02-14` +- **Default**: if not provided, the start date is the earliest available date +- **180-day YouTube cap**: while `include_total_statistics` is `true` (the default), the YouTube tools search at most 180 days. An omitted `start_date` defaults to the 180 days ending at `end_date` (or today), and an explicit range wider than 180 days returns an error. Send `include_total_statistics: false` to search the full history without population statistics +- **What the range filters on**: an article's or post's publish date, a moment's or narrative's earliest article or post, a trend's latest publish date, a video's publish date, and a channel's latest video publish date + +### Countries + +Each tool supports a different set of countries and expects its own code format: + +| Tool | Parameter | Format | Supported countries | +|------|-----------|--------|---------------------| +| `get_social_media_posts` | `country` | ISO 3166-1 alpha-2, any case | Any country (about half of posts carry one) | +| `get_social_media_narratives` | `country` | ISO 3166-1 alpha-2, any case | Any country | +| `get_news_articles` | `publisher_location` | Full English name, one value | The 22 countries listed under [`get_news_articles`](#get_news_articles) | +| `get_tiktok_hashtags` | `country` | ISO 3166-1 alpha-2, uppercase (lowercase is upcased) | US, GB, CA, DE, ES, TR, ZA, NG, CN, IN, PH, TH, MX, BR, AR, FR, IT, NL, PL, AU, AE, JP, PT, KR, VN | +| `get_youtube_videos` | `country` | ISO 3166-1 alpha-2, uppercase only | Any country | +| `get_youtube_channels` | `country` | ISO 3166-1 alpha-2, uppercase only | Any country | +| `get_youtube_creator_insights` | `country` (default `us`) | ISO 3166-1 alpha-2, any case | The 219 countries Google Ads can target (not Taiwan, Hong Kong or Puerto Rico) | +| `get_trends`, `get_news_moments`, `get_audience_targeting`, `get_brand_profile` | None | | No country filter | + +Two rules apply everywhere: + +- The UK's code is `gb` (or `GB`), never `uk`. A `uk` value matches nothing on the search tools and returns an error on `get_tiktok_hashtags` and `get_youtube_creator_insights`. +- A country outside a tool's fixed list (`get_news_articles`, `get_tiktok_hashtags`, `get_youtube_creator_insights`) returns an error. On the tools that accept any country, an unknown or wrongly cased code returns no results rather than an error. ### Search Terms -- 0-3 terms per request (optional for all tools) + +- 0-3 terms per request (optional for every tool that accepts them) - Terms run in parallel when provided - For articles/posts: Keep complete concepts together - ✅ `["renewable energy policy"]` - ❌ `["renewable", "energy", "policy"]` -- **Without search terms**: Tools return results sorted by a logical default, customizable with `sort_by` parameter: +- **`sort_by` cannot be combined with `search_terms`**: for the tools that accept `sort_by` (`get_trends`, `get_news_moments`, `get_social_media_narratives`, `get_youtube_videos`, `get_youtube_channels`), sending both returns an error. When search terms are provided, results are ranked by relevance automatically, so omit `sort_by`. Use `"recency"` only when chronological ordering is explicitly wanted +- **Without search terms**: Tools return results sorted by a logical default, customizable with the `sort_by` parameter: - Trends: default "size" (biggest trends), optional "recency" (most recent trends) - Moments: default "size" (biggest story clusters), optional "recency" (most recent moments) - Narratives: default "size" (most discussed), optional "recency" (most recent narratives) @@ -499,13 +860,25 @@ This distinction helps clarify that `total_matches` represents the full scope of - YouTube Channels: default "size" (highest subscriber count), optional "recency" (recently active channels) ### Tool Selection + - Brand info → `get_brand_profile` -- Long-term trends → `get_trends` +- Long-term trends in news and social media → `get_trends` - News clusters → `get_news_moments` - Social clusters → `get_social_media_narratives` - Individual articles → `get_news_articles` - Individual posts → `get_social_media_posts` - Trending TikTok hashtags → `get_tiktok_hashtags` -- YouTube videos → `get_youtube_videos` -- YouTube channels → `get_youtube_channels` +- YouTube videos matching a keyword → `get_youtube_videos` +- YouTube channels matching a keyword → `get_youtube_channels` - Audience targeting segments → `get_audience_targeting` +- YouTube creators to partner with, their audience, or YouTube topic trends → `get_youtube_creator_insights` + +The three YouTube tools cover different ground. `get_youtube_videos` and `get_youtube_channels` search Sightly's curated +historical corpus by keyword and date; use them to find content that was published. `get_youtube_creator_insights` uses +Google's advertising data; use it to discover creators, judge partnership suitability, see who watches a channel, or +track a topic's trajectory. Channel IDs flow one way: look a channel up with `get_youtube_channels`, then pass its ID to +`get_youtube_creator_insights` for the audience profile. + +Call more than one of these tools for the same question only when chaining channel IDs as above, or when the user asks +for both sources. `get_trends` covers news and social media, not YouTube. No tool ranks channels by growth or momentum, +so a request for "trending channels" is answered by the single best-fitting tool, with that limitation stated. diff --git a/docs/ai/mcp/wpp-open.md b/docs/ai/mcp/wpp-open.md deleted file mode 100644 index 40ed3a5..0000000 --- a/docs/ai/mcp/wpp-open.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -sidebar_label: WPP Open ---- - -# WPP Open - -All of the BAV MCP Servers are available in WPP Open via Creative Studio and its agent builder. - -This allows you to build agents that can access the BAV MCP servers directly from within WPP Open, -and leverage the capabilities of the agent builder to create custom workflows and integrations. - -To get started with using the BAV MCP servers in WPP Open, follow these steps: - -1. Log in to your WPP Open account and navigate to Creative Studio. -2. Open your playground or one of your existing projects. -3. Create a new agent or open an existing one in the Agent Builder. -4. In the Instructions tab, open Tools & Settings and find the server you want in the Tools list. - -And that's it! You can now use the MCP servers in your WPP Open agents to enhance their capabilities and create more -powerful workflows. - -## Using pre-built agents - -Getting started with the BAV MCP server has a little learning curve in familiarizing yourself with BAV data, concepts -and methodology to make the most out of it. If you are building an internal tool, please do get in touch with us for -assistance. - -To help you get started quickly, we have created some pre-built agents that create summaries and reports using key BAV -data. These can be helpful to drop in as part of a multi-step agent workflow. They are manged by BAV and makes it -super-simple for you to get started with BAV data with minimal setup. From e5012290be022e6946cb373e9521c40cb600f077 Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Fri, 23 Oct 2026 23:18:55 +0200 Subject: [PATCH 02/23] Fix outdated REST API docs Correct scopes, stock prices, brandscape data, the health check, webhooks and the fields, filters and includes on existing endpoint pages to match the API. Co-Authored-By: Claude Opus 5.5 --- docs/audiences/audience-groups.md | 13 +- docs/audiences/audiences.md | 122 ++++++++--- docs/audiences/export.md | 70 ++++++- docs/authentication.md | 49 ++++- docs/best-countries/country-data.md | 25 ++- docs/brand-data/archetypes.md | 24 ++- docs/brand-data/brand-personality-match.md | 20 +- docs/brand-data/brand-vulnerability-map.md | 5 + docs/brand-data/brand-worth-map.md | 14 +- docs/brand-data/brandscape-data.md | 221 ++++++++++++++------ docs/brand-data/category-worth-map.md | 5 +- docs/brand-data/cee-opinions.md | 39 ++-- docs/brand-data/commitment-funnel.md | 39 +++- docs/brand-data/cost-of-entry.md | 17 +- docs/brand-data/index.md | 18 +- docs/brand-data/love-plus.md | 12 +- docs/brand-data/partnership-exchange-map.md | 17 +- docs/brand-data/swot.md | 11 +- docs/brand-data/toplist-market.md | 17 +- docs/brands/brands.md | 121 +++++++---- docs/brands/collections.md | 29 ++- docs/company-data/companies.md | 36 +++- docs/company-data/stock-prices.md | 156 +++++++++----- docs/customizing/fields.md | 2 +- docs/customizing/searching.md | 11 + docs/errors.md | 37 +++- docs/health-check.md | 19 +- docs/metadata/cities.md | 36 ++-- docs/metadata/countries.md | 60 +++--- docs/metadata/operating-companies.md | 4 +- docs/metadata/sectors.md | 6 +- docs/metadata/stock-exchanges.md | 2 +- docs/metrics/metric-groups.md | 18 +- docs/metrics/metrics.md | 31 +-- docs/pagination.md | 4 +- docs/rate-limiting.md | 5 +- docs/studies/categories.md | 13 +- docs/studies/studies.md | 221 ++++++++++++++------ docs/versioning.md | 4 +- docs/webhooks.md | 68 +++--- 40 files changed, 1148 insertions(+), 473 deletions(-) diff --git a/docs/audiences/audience-groups.md b/docs/audiences/audience-groups.md index 3351c30..af547e1 100644 --- a/docs/audiences/audience-groups.md +++ b/docs/audiences/audience-groups.md @@ -2,7 +2,7 @@ ## What are audience groups? -[Audiences](audiences.md) are cuts of respondents that can be used ta analyze datasets. Audience Groups are a way to +[Audiences](audiences.md) are cuts of respondents that can be used to analyze datasets. Audience Groups are a way to organize audiences into groups. For example, there are several audiences for different age cuts which are all grouped under the Age group. @@ -14,9 +14,9 @@ To list all of the audience groups and browse them via the API, use the list end GET /api/v2/audience-groups ``` -## Get a audience group +## Get an audience group -You may also directly retrieve a audience group's details if you already have its system ID. +You may also directly retrieve an audience group's details if you already have its system ID. ```http request GET /api/v2/audience-groups/123 @@ -24,6 +24,8 @@ GET /api/v2/audience-groups/123 Where `123` is the system ID of the audience group. +The audience groups endpoints are read-only. + ## Schema ### Full response schema @@ -47,11 +49,12 @@ The slim relationship schema is used when the audience group is used as part of ## Relationships & includes -By default, relationships apart from the sector are not included. See +By default, relationships are not included. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: -- `audiences` - The [audiences](audiences.md) that belong to this audience group. +- `audiences` - The [audiences](audiences.md) that belong to this audience group, using the + [audience relationship schema](audiences.md#relationship-response-schema). ## Searching diff --git a/docs/audiences/audiences.md b/docs/audiences/audiences.md index 94d038c..93c8e13 100644 --- a/docs/audiences/audiences.md +++ b/docs/audiences/audiences.md @@ -4,24 +4,34 @@ You may use the Audiences endpoint to retrieve details about one or more audienc ## What are audiences? -Audiences are the core of all our datasets. Audiences are pre-filtered groups of respondents for a dataset. They are -shared between the BAV and Best Countries datasets. +Audiences are the core of all our datasets. An audience is a group of respondents, such as women aged 18-34. Brand +data is always read for a study and an audience. Examples of audiences include: All Adults (everyone), Female, Age 18-25, etc. For the BAV dataset they correspond to the available cuts of data that you can access on audiences. For the Best -Countries -dataset they correspond to a set of filters that you can then query the dataset with. +Countries dataset they correspond to a set of filters that you can then query the dataset with. Audiences can be active and inactive. Your application should not display inactive audiences to users even if they are available through the API. Audiences can also be public/private. Public audiences are available to all users across the group. Private audiences -are audiences only accessible by the current user. +are only accessible by the user who owns them and the users they have been shared with. The API only returns the +audiences you have access to: public audiences, your own audiences and audiences shared with you. + +Audiences are either standard audiences provided by The Fount (`is_standard`) or audiences built by users. A new +audience has no data until it is deployed. Audiences in turn belong to [audience groups](audience-groups.md). These groups can be used to create a better selection experience in an interface as the number of audiences can be plentiful. +:::tip Creating and managing audiences + +This page covers reading audiences. To create, update, delete and deploy audiences, and to manage their definitions, +segments and metrics, see [Managing audiences](managing-audiences.md). + +::: + ## List all audiences To list all of the audiences and browse them via the API, use the list endpoint: @@ -38,64 +48,122 @@ You may also directly retrieve an audience's details if you already have its sys GET /api/v2/audiences/1 ``` -Where `1` is the system ID of the audience. +Where `1` is the system ID of the audience. Include `definitions.segments.metrics` to get its full definition. :::note All adults is the base audiences The All Adults audience is our definition of "unfiltered" or "everyone". It always has the system ID of 1. ::: +## Get the studies for an audience + +To list the studies an audience has data in, along with the audience's size in each study, use: + +```http request +GET /api/v2/audiences/1/studies +``` + +Where `1` is the system ID of the audience. An audience that has not been deployed has no studies. This endpoint is +paginated and returns the following for each study: + +| Key | Type | Description | +|---------------|---------|---------------------------------------------------------------------------------------------------| +| `study` | object | The [study](../studies/studies.md#relationship-response-schema), with its `country` and `year`. | +| `respondents` | integer | The number of respondents in this study who are in the audience. | +| `population` | integer | The population projection: the number of people the audience represents in the study's market. Calculated when the audience is deployed. `null` for markets without a population figure to project to. | + ## Schema ### Full response schema -| Key | Type | Filterable | Sortable | Configurable | Description | -|---------------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|--------------------------------------------------------------------------------------------------------------------| -| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | -| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The display name of the audience. | -| `description` | string | :x: | :white_check_mark: | :white_check_mark: | A more detailed description (optional) of the audience. | -| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience is active (should be used) or not. Please don't show inactive audiences in a user interface. | -| `is_public` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience is publicly available to everyone (true) or just the current user (false). | -| `available_for_bav` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience can be used with the BAV dataset. | -| `available_for_bc` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience can be used with the Best Countries dataset. | -| `bc_filters` | array | :white_check_mark: | :x: | :white_check_mark: | The filters to apply to the raw Best Countries dataset to get this audience. | -| `available_for_diversity` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience is available in the Consumer Equality Equation study. | -| `is_ethnic_minority` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience is considered an ethnic minority. | -| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this audience was first created. | -| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this audience was last updated. | +| Key | Type | Filterable | Sortable | Configurable | Description | +|---------------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The display name of the audience. | +| `description` | string | :x: | :x: | :white_check_mark: | A more detailed description (optional) of the audience. | +| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience is active (should be used) or not. Please don't show inactive audiences in a user interface. | +| `is_public` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience is publicly available to everyone (true) or restricted (false). | +| `is_standard` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the audience is one of The Fount's standard audiences. | +| `available_for_diversity` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience can be used for diversity analysis (the Consumer Equality Equation study). | +| `is_ethnic_minority` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience represents an ethnic minority group. | +| `deployed_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when the audience was last deployed. `null` if it has never been deployed. | +| `definitions_updated_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when the audience's segments last changed. If this is later than `deployed_at`, the audience must be deployed again for the change to show in its data. | +| `deleted_at` | string | :x: | :x: | :white_check_mark: | Always `null`. Deleted audiences are not returned. | +| `url` | string | :x: | :x: | :x: | The URL to view the audience in The Fount. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this audience was first created. | +| `updated_at` | string | ([updated since](../customizing/filters.md)) | :white_check_mark: | :white_check_mark: | A datetime string when this audience was last updated. | + +The `group`, `user` and `definitions` keys are added when the matching relationship is [included](#relationships--includes). + +:::caution Removed fields + +`available_for_bav`, `available_for_bc` and `bc_filters` are no longer part of the full audience response. The first +two are still part of the relationship schema below. + +::: ### Relationship Response Schema -The slim relationship schema is used when the audience is used as part of an include in another resource. +The slim relationship schema is used when the audience is used as part of an include in another resource, for example +the `audiences` include on [audience groups](audience-groups.md). | Key | Type | Description | |---------------------|---------|--------------------------------------------------------------------------------------------------------------------| | `id` | integer | The system ID for the audience. | | `name` | string | The primary name of the audience. | | `is_active` | boolean | Whether this audience is active (should be used) or not. Please don't show inactive audiences in a user interface. | -| `is_public` | boolean | Whether this audience is publicly available to everyone (true) or just the current user (false). | +| `is_public` | boolean | Whether this audience is publicly available to everyone (true) or restricted (false). | | `available_for_bav` | boolean | Whether this audience can be used with the BAV dataset. | | `available_for_bc` | boolean | Whether this audience can be used with the Best Countries dataset. | +### Definition Schema + +The `definitions` include returns a list of definitions. An audience without definitions cannot be deployed. + +| Key | Type | Description | +|---------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | The definition ID. | +| `defined_for` | object | What the definition is limited to: `type` is `country` or `study`, with the `id` of that record. Both are `null` when the definition applies to all of the audience's data. | +| `dataset` | object | The dataset the definition reads, as a `key` and a `label`. | +| `segments` | array | The definition's segments, when `definitions.segments` is included. Each has `id`, `uuid`, `sort_order`, `name`, `within_segment_operator`, `between_segments_operator`, `created_at`, `updated_at` and, when `definitions.segments.metrics` is included, `metrics`. | +| `created_at` | string | A datetime string when the definition was created. | +| `updated_at` | string | A datetime string when the definition was last updated. | + +See [Managing audiences](managing-audiences.md) for the full segment and metric schemas. + ## Additional Filters -For convenience, we have a set of additional filters for brands that are not available in +For convenience, we have a set of additional filters for audiences that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: - `active` - Set to `1` to only return active audiences. - `inactive` - Set to `1` to only return inactive audiences. - `public` - Set to `1` to only return public audiences. - `private` - Set to `1` to only return private audiences. +- `system_provided` - Set to `1` to only return The Fount's standard audiences. +- `user_generated` - Set to `1` to only return audiences built by users. +- `has_definitions` - Set to `1` to only return audiences with at least one definition. - `groups` - A comma-separated list of audience group IDs. This will only return audiences that belong to the specified groups. +- `users` - A comma-separated list of user IDs. This will only return audiences owned by the specified users. +- `available_for_studies` - A comma-separated list of study IDs. This will only return audiences with data available in + the specified studies. + +For the `active`, `inactive`, `public`, `private`, `system_provided`, `user_generated` and `has_definitions` filters, +any value turns the filter on. ## Relationships & includes -By default, relationships apart from the sector are not included. See -the [includes section](../customizing/includes) for more information on how this works. The following relationships -are available: +By default, relationships are not included. See the [includes section](../customizing/includes.md) for more information +on how this works. The following relationships are available: - `group` - The [audience group](audience-groups.md) that this audience belongs to. +- `definitions` - The audience's [definitions](#definition-schema). +- `definitions.segments` - The definitions, with their segments. +- `definitions.segments.metrics` - The definitions, with their segments and each segment's metrics. This is the + audience's full definition. +- `user` - The user who owns the audience (`id`, `first_name`, `last_name`, `name` and `email`). +- `user.operating_company` - The owner, with their [operating company](../metadata/operating-companies.md). ## Searching -This endpoint supports searching. See the [searching section](../customizing/searching) for more details. \ No newline at end of file +This endpoint supports searching. See the [searching section](../customizing/searching.md) for more details. diff --git a/docs/audiences/export.md b/docs/audiences/export.md index 4642029..769d58e 100644 --- a/docs/audiences/export.md +++ b/docs/audiences/export.md @@ -10,9 +10,8 @@ your own systems. This is what the Audience Export Integration is designed for. ## How it works -All audiences are available through the [Audiences API](audiences.md) and you can listen to data -change -events for updated audiences through [Webhooks](../webhooks.md). However, doing so requires you to always maintain the +All audiences are available through the [Audiences API](audiences.md) and you can listen to data change events for +updated audiences through [Webhooks](../webhooks.md). However, doing so requires you to always maintain the full list of audiences in your system. This is where the Audience Export Integration comes in. With the Audience Export Integration your application is added as an export destination for an audience within The @@ -41,8 +40,11 @@ Which format you choose depends on your use case and the data you need, as well The first format is always available for all datasets. The second format is available for all BAV studies. Formats 3 and 4 are available for all Audience Origin studies. -In addition, formats 2, 3 and 4 are available for all Honeycomb studies. These are studies where BAV and Audience Origin -data have been fused together. +In addition, formats 2, 3 and 4 are available for all fused studies (the "AO+BAV Fused" study type). These are studies +where BAV and Audience Origin data have been fused together. + +Formats 3 and 4 can also be fetched directly from the API for a given audience and study. See +[Fetching respondents from the API](#fetching-respondents-from-the-api). ## Access control @@ -56,7 +58,8 @@ on their e-mail address. To get started with the Audience Export Integration you'll want to become familiar with: - The different type of supported formats for the audience export. -- The [Audiences API](audiences.md) and how to use it to create and manage audiences. +- The [Audiences API](audiences.md) and how to use it to read audiences, and + [Managing audiences](managing-audiences.md) for how to create and manage them. - The [Webhooks](../webhooks.md) and how to listen to audience export events. As you start thinking about how to use the Audience Export Integration, @@ -115,9 +118,7 @@ see the [Audience API schema](audiences.md). ### Audience Origin Respondent IDs -The Audience Origin Respondent ID (AO ID) is a unique identifier for each respondent in an audience. This ID is used to -link the -respondent to the data in the data warehouse. IDs take slightly different forms depending on the study but are most +The Audience Origin Respondent ID (AO ID) is a unique identifier for each respondent in an audience. This ID is used to link the respondent to the data in the data warehouse. IDs take slightly different forms depending on the study but are most recently v4 UUIDs. :::warning Specific approval required @@ -206,4 +207,53 @@ see the [Audience API schema](audiences.md). "810_2x_4" ] } -``` \ No newline at end of file +``` + +## Fetching respondents from the API + +In addition to the webhook-based export, the Audience Origin respondent IDs and progressive numbers for an audience can +be fetched directly from the API, one study at a time. + +### Audience Origin Respondent IDs + +```http request +GET /api/v2/audiences/{audienceId}/respondents/ao-ids/{studyId} +``` + +Returns the Audience Origin IDs of the respondents in the audience for the given study. Respondents without an Audience +Origin ID are left out. + +### Audience Origin Progressive Numbers + +```http request +GET /api/v2/audiences/{audienceId}/respondents/ao-progressive-numbers/{studyId} +``` + +Returns the Audience Origin progressive numbers of the respondents in the audience for the given study. Respondents +without a progressive number are left out. + +### Requirements + +Both endpoints require: + +- A token with the `bav:audience-origin-data` scope. +- Access to both the audience and the study. +- The user's permission to export Audience Origin IDs (`ao-ids`) or Audience Origin progressive numbers + (`ao-progressive-numbers`) respectively. This permission requires specific approval. + +A `404` is returned if the audience or study does not exist, and a `403` if you are not allowed to access them or to +export. + +### Response + +The response is not paginated. It contains a single `data` key with an array of identifiers: + +```json +{ + "data": [ + "808_2x_4", + "809_2x_4", + "810_2x_4" + ] +} +``` diff --git a/docs/authentication.md b/docs/authentication.md index e96538a..c92b73f 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -47,11 +47,50 @@ out integrations for each tool using the API. We allow you to create integrations and API keys that have different levels of access to your account. This is done through scopes. -Generally each endpoint has its own scope. For example to list all brands using the `/brands` endpoint, you will need -the `Brands: Read` scope. +Scopes are broad and each one covers a group of endpoints, typically a dataset. For example, to list brands using the +`/brands` endpoint, your API key needs the `bav:shared-resources` scope, and to get data from the `/brandscape-data` +endpoint, it needs the `bav:brand-data` scope. + +If your API key doesn't have the scope that an endpoint requires, a `401` error is returned with a message telling you +which scope is missing. Scopes for your API keys and applications are managed from -you [profile settings page in The Fount](https://fount.wppbav.com/profile?tab=api). +the [API section in The Fount](https://fount.wppbav.com/api). + +### Available scopes + +| Scope | Name | Covers | +|----------------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bav:shared-resources` | Shared Resources | Shared reference data: brands, brand tags, collections, audiences and audience groups (reading), studies and their categories (`/studies/{id}/categories`), years, countries, cities, regions, sectors, GICS sectors, companies, stock prices, stock exchanges, operating companies, tools and the stock performance slide deck (`/slide-decks/stock-performance`). | +| `bav:brand-data` | BAV Brand Data | BAV brand research data and analysis: brandscape data, the brandscape data models (`/brandscape/...`), the tool endpoints (`/tools/...`), categories, brand variations, brand metrics and brand metric groups, brand measures and brand measure groups, BAV questions and question groups, CEE opinions, and the study-level endpoints for brands, brand metrics, brand measures, BAV questions and audience questions. | +| `bav:best-countries-data` | Best Countries Data | Best Countries research data: the `/best-countries/...` and `/flourish/best-countries/...` endpoints, Best Countries metrics, metric groups and factors. | +| `bav:audience-origin-data` | Audience Origin Data | Audience Origin data: the `/audience-origin/...` endpoints (metrics, metric groups, touchpoints, frequencies and queries) and the audience respondent ID endpoints (`/audiences/{id}/respondents/...`). | +| `bav:market-share-data` | Market Share Data | Euromonitor market share data: the `/market-share/...` endpoints, including the brand and company shares and the catalogs of brands, companies, categories, geographies, industries and data types. | +| `bav:audiences:write` | Build Audiences | Creating, updating and deleting audiences, audience segments and segment metrics, and deploying audiences (`/audiences/{id}/deploy`). Reading audiences only requires `bav:shared-resources`. | +| `bav:collections:write` | Create Collections | Creating and managing brand collections. The collection endpoints in the REST API are currently read-only and only require `bav:shared-resources`. | +| `profile` | User Profile | The authenticated user's profile information from the `/oauth/userinfo` endpoint. | + +The [health check](health-check.md) endpoint doesn't require authentication or any scope. + +### Scopes and permissions + +Most of the dataset scopes are tied to a permission in The Fount. You can only give a scope to an API key when your +account has access to the dataset it covers. For example, the `bav:best-countries-data` scope is only available if +you have access to Best Countries. For an application, the scopes available depend on the access of the account that +owns the application. + +Scopes control which endpoints an API key can use. Within those endpoints, you can still only see the data that the +account you're acting as has access to. If the account doesn't have permission to perform an action or see a resource, +a `403` error is returned. + +### System scopes + +A few scopes are not for general use and can't be self-assigned: + +- `act-as-user` lets an approved application act on behalf of its users by sending the user's e-mail address in the + `X-Act-As-User` header. It is only offered on an application's own API keys once the application has been approved + to act on behalf of users. +- `bav:auto-login` is a legacy system scope for trusted integrations. It requires a special permission and can't be + given to applications. -A select few endpoints cannot be self-assigned through the settings page but requires approval. In this case you will -find more information on the respective endpoint docs pages. +[Contact us](mailto:support@bernskiold.com) if you think your integration needs one of these. diff --git a/docs/best-countries/country-data.md b/docs/best-countries/country-data.md index dc8fde7..b4a474b 100644 --- a/docs/best-countries/country-data.md +++ b/docs/best-countries/country-data.md @@ -12,20 +12,26 @@ Country data has two types of data: - **Attributes. (`attributes`)** The 74 imagery/perception attributes that respondents answer in the Best Countries survey. - **Factors. (`factors`)** The 10 factors that contribute to GDP growth and is made up by a selection of the attributes. Included in the factors is the overall score that is a weighted average of all factors. -Country data also has three types of scores: +Country data has two types of scores: -- **Scores. (`scores`)** A 100-point score where 100 is best and 0 is worst, calculated through a pipeline based on the responses. -- **Ranks. (`ranks`)** The 100-point score turned into a sorted simple rank where 1 is the best. -- **Percentages. (`percent`)** Available only for the subset of attributes that are our consideration attributes. For example "consider doing business". The percent of respondents who answered affirmatively to the satement. +- **Scores. (`scores`)** A normalized 100-point score where 100 is best and 0 is worst, scaled across the countries and calculated through a pipeline based on the responses. +- **Ranks. (`ranks`)** The 100-point score turned into a sorted simple rank against the other countries, where 1 is the best. + +Any other data type or score type returns a `400 Bad Request` response. ## Creating a query The endpoint HTTP query accepts dynamic parameters for the year, score type and data type as described above. In a generic case, the query looks like this: ```http -GET /api/v2/best-countries/countries/{yearNumber}/{dataType}/{scoreType} +GET /api/v2/best-countries/countries/{year}/{dataType}/{scoreType} ``` +Where `{year}` is either the system ID of the year or the calendar year (e.g. `2024`), `{dataType}` is `attributes` or +`factors` and `{scoreType}` is `scores` or `ranks`. A `404` is returned if the year has no Best Countries data. + +This endpoint requires a token with the `bav:best-countries-data` scope. + For example, getting the factor ranks for 2024 would look like this: ```http @@ -34,7 +40,7 @@ GET /api/v2/best-countries/countries/2024/factors/ranks ## Schema -The API response for the country data endpoint will give you an array of datapoint objects. Each object is a one-level object that contains a few metadata fields and a series of metrics. The meta fields are: +The API response for the country data endpoint will give you an array of datapoint objects in a `data` key. The response is not paginated. Each object is a one-level object that contains a few metadata fields and a series of metrics. The meta fields are: - `country`. The name of the country the datapoint relates to. - `country_id`. The system ID of the country. @@ -47,10 +53,11 @@ The metric fields are made up by the metric or factor key and its corresponding For convenience, a set of filters allow you to further refine the data: -- `country_codes`. A comma-separated list of country codes to include data from. +- `country_codes`. A comma-separated list of two-letter ISO country codes to include data from. - `countries`. A comma-separated list of country system IDs to include data from. -The filters are applied as a standard query parameter like this: +When neither filter is given, every country is returned. Unlike most other endpoints, the filters are applied as plain +query parameters (not inside `filter[...]`) like this: ```http GET /api/v2/best-countries/countries/2024/factors/ranks?country_codes=US @@ -58,4 +65,4 @@ GET /api/v2/best-countries/countries/2024/factors/ranks?country_codes=US ## Sorting -By default the data will be sorted by the country name. All fields returned by the endpoint are [sortable](../customizing/filters#sorting-results). +By default the data will be sorted by the country name. All fields returned by the endpoint are [sortable](../customizing/filters#sorting-results) using the `sort` query parameter, prefixed with `-` for descending order (e.g. `sort=-total`). Only one sort column is supported. diff --git a/docs/brand-data/archetypes.md b/docs/brand-data/archetypes.md index b1e3a45..1dec34b 100644 --- a/docs/brand-data/archetypes.md +++ b/docs/brand-data/archetypes.md @@ -1,5 +1,8 @@ # Archetypes +Archetypes show how strongly a brand is associated with each of the twelve BAV brand archetypes, such as Inventor, +Expert and Rebel, as a percentile rank and a construct score. + Archetypes data are split across two types: - Cultural archetypes @@ -20,10 +23,17 @@ GET /api/v2/tools/archetypes When you query the Archetypes endpoint the parameters are split between filtering parameters and comparison parameters. The filter parameters filter down the data, while the comparison parameters are used to create competitive archetypes. -| Key | Required? | Type | Description | -|---------------|:----------------------------:|---------------|-----------------------------------------------------------------| -| `brands` | :x: | numeric array | Filter parameter. A comma-separated list of Brand IDs. | -| `studies` | :white_check_mark: | numeric array | Filter parameter. A comma-separated list of Study IDs. | -| `audiences` | :x: (defaults to All Adults) | numeric array | Filter parameter. A comma-separated list of Audience IDs. | -| `collections` | :x: | numeric array | Comparison parameter. A comma-separated list of Collection IDs. | -| `categories` | :x: | numeric array | Comparison parameter. A comma-separated list of Category IDs. | \ No newline at end of file +| Key | Required? | Type | Description | +|---------------|:----------------------------:|---------|---------------------------------------------------------------------------------------------------| +| `brands` | :x: | integer | Filter parameter. A single Brand ID. | +| `studies` | :white_check_mark: | integer | Filter parameter. A single Study ID. | +| `audiences` | :x: (defaults to All Adults) | integer | Filter parameter. A single Audience ID. | +| `categories` | :x: | integer | Comparison parameter. A single Category ID to compare against. Can be combined with `collections`. | +| `collections` | :x: | integer | Comparison parameter. A single Collection ID to compare against. Can be combined with `categories`. | + +## Response + +The response contains a `data` array with one entry per brand. Each entry has `brand` (with `id`, `name` and +`local_name`), `brand_variation`, `sector`, `category`, `study`, `country`, `year` and `audience` objects, and a `data` +object keyed by archetype (`inventor`, `expert`, `leader`, `innocent`, `enticer`, `fashion_forward`, `adventurer`, +`rebel`, `entertainer`, `companion`, `nurturer` and `trusted_friend`), each with a `rank` and a `construct`. diff --git a/docs/brand-data/brand-personality-match.md b/docs/brand-data/brand-personality-match.md index 030be76..0cc8973 100644 --- a/docs/brand-data/brand-personality-match.md +++ b/docs/brand-data/brand-personality-match.md @@ -1,5 +1,9 @@ # Brand Personality Match +The Brand Personality Match returns the brands in the same study whose imagery profile most closely matches the brand +you name, ranked by similarity. Similarity is the correlation of the brands' imagery attribute ranks, so matches can +come from any category. Only brands with a knowledge percentile rank of 50 or above are considered. + ## Creating a query ```http request @@ -8,8 +12,14 @@ GET /api/v2/tools/brand-personality-match ## Parameters -| Key | Required? | Type | Description | -|-------------|:----------------------------:|---------------|-----------------------------------------| -| `brands` | :white_check_mark: | numeric array | A single Brand ID in array format. | -| `studies` | :white_check_mark: | numeric array | A single Study ID in array format. | -| `audiences` | :x: (defaults to All Adults) | numeric array | A single Audience ID in array format. | +| Key | Required? | Type | Description | +|-------------|:----------------------------:|---------|-----------------------| +| `brands` | :white_check_mark: | integer | A single Brand ID. | +| `studies` | :white_check_mark: | integer | A single Study ID. | +| `audiences` | :x: (defaults to All Adults) | integer | A single Audience ID. | + +## Response + +The response contains a `data` array of matching brands. Each entry has `brand`, `sector`, `category`, `study`, +`country`, `year` and `audience` objects (each with `id` and `name`), plus `correlation` and `varianceExplained`, each +with a `raw` value and a `formatted` percentage string. diff --git a/docs/brand-data/brand-vulnerability-map.md b/docs/brand-data/brand-vulnerability-map.md index 6798326..6973f22 100644 --- a/docs/brand-data/brand-vulnerability-map.md +++ b/docs/brand-data/brand-vulnerability-map.md @@ -1,5 +1,8 @@ # Brand Vulnerability Map +The Brand Vulnerability Map shows how vulnerable a brand is, based on its brand equity metrics. This is the +vulnerability assessment the Agency Change Predictor uses, returned on its own. + ## Creating a query ```http request @@ -11,3 +14,5 @@ GET /api/v2/tools/brand-vulnerability-map | Key | Required? | Type | Description | |---------|:------------------:|---------|--------------------| | `brand` | :white_check_mark: | integer | A single Brand ID. | + +Note that this endpoint uses the singular `brand` parameter. diff --git a/docs/brand-data/brand-worth-map.md b/docs/brand-data/brand-worth-map.md index c5fd944..e2c8536 100644 --- a/docs/brand-data/brand-worth-map.md +++ b/docs/brand-data/brand-worth-map.md @@ -1,5 +1,9 @@ # Brand Worth Map +The Brand Worth Map places brands on two axes, "Worth paying more for" and "Providing good value", and classifies them +into four quadrants split at a percentile rank of 50: Brand Worth (high on both), Desire (high worth, low value), Value +Champion (high value, low worth) and Emotional Choice (low on both). + ## Creating a query ```http request @@ -8,8 +12,8 @@ GET /api/v2/tools/brand-worth-map ## Parameters -| Key | Required? | Type | Description | -|-------------|:----------------------------:|---------------|-----------------------------------------| -| `brands` | :white_check_mark: | numeric array | A comma-separated list of Brand IDs. | -| `studies` | :white_check_mark: | numeric array | A comma-separated list of Study IDs. | -| `audiences` | :x: (defaults to All Adults) | numeric array | A comma-separated list of Audience IDs. | \ No newline at end of file +| Key | Required? | Type | Description | +|-------------|:----------------------------:|---------------|--------------------------------------| +| `brands` | :white_check_mark: | numeric array | A comma-separated list of Brand IDs. | +| `studies` | :white_check_mark: | numeric array | A comma-separated list of Study IDs. | +| `audiences` | :x: (defaults to All Adults) | integer | A single Audience ID. | diff --git a/docs/brand-data/brandscape-data.md b/docs/brand-data/brandscape-data.md index b28a1bf..eea7b2d 100644 --- a/docs/brand-data/brandscape-data.md +++ b/docs/brand-data/brandscape-data.md @@ -6,47 +6,114 @@ A fundamental core concept of BAV is the "Brandscape" which is the set of brands The brandscape data is the collection of metrics and their respective values for the brandscape. You can, in practical terms, see the brandscape data is the "BAV data". -The brandscape data endpoint gives you data by: +Brandscape data has one row per brand, category, study and audience, with every metric BAV calculates for that +combination. You can get the data by: -- [Study](studies.md) -- [Year](years.md) -- [Country](countries.md) -- [Audience](audiences.md) -- [Category](categories.md) +- [Study](../studies/studies.md) +- [Year](../metadata/years.md) +- [Country](../metadata/countries.md) +- [Audience](../audiences/audiences.md) +- [Brand](../brands/brands.md) +- [Category](../studies/categories.md) You can customize the response to include only the data you need, such as only specific metrics. -:::note Filtering is required -Please note that filtering is required on the brandscapa data endpoint to achieve quick response times. For best -performance, please use these combinations of filters: +## List brandscape data -- Study + Audience + Brand + Category -- Country + Year + Audience -- Brand + Audience + Country + Year +To list the brandscape data, use the list endpoint: -You should read these from left to right. A combination of "Study + Audience" works just as well as "Study + Audience + -Brand". However, "Category + Audience" will not. +```http request +GET /api/v2/brandscape-data +``` -You may filter on one or multiple of each type. -::: +The response is [paginated](../pagination.md). There is no endpoint for retrieving a single brandscape data row. -## List all brandscape data +### Scoping the request -To list all of the brandscape data and browse them via the API, use the list endpoint: +Each request is scoped to one or more studies. You can do this in one of two ways: -```http request -GET /api/v2/brandscape-data -``` +- **By study:** Use the `studies` filter with one or more study IDs. +- **By market and year:** Use a country filter (`countries` or `country_code`) together with a year filter (`years` + or `year_number`). -## Get a brandscape data +A `400` error is returned if you filter by a country without a year, or by a year without a country. -You may also directly retrieve a brandscape data's details if you already have its system ID. +If you don't give a study, country or year filter at all, the request falls back to the most recently released +syndicated BAV study from the last three years. We recommend that you always scope your requests explicitly. -```http request -GET /api/v2/brandscape-data/123 +When no `audiences` filter is given, the data is returned for the All Adults audience (ID `1`). + +### Study types + +When you filter by market and year, the request only resolves to syndicated BAV studies by default. To include other +types of studies, set the `study_types` filter to a comma-separated list of the study types you want. The available +study types are: + +- `syndicated` - The syndicated BAV study (default). +- `snap` - SnapBAV studies. +- `fused` - Fused studies. +- `custom` - Custom studies. + +Unknown values are ignored. The `study_types` filter has no effect when you use the `studies` filter. + +If studies of other types exist for the markets and years you requested but were left out by the study type filter, +they are listed in `meta.available_alternatives`. Each entry tells you about the study, and which `study_types` value +includes it: + +```json +{ + "data": [], + "meta": { + "available_alternatives": [ + { + "study_id": 1234, + "study_name": "SnapBAV Norway 2025", + "market": "Norway", + "year": 2025, + "study_type": "snap", + "caveat": "...", + "message": "A SnapBAV study is available for this market and year. Add filter[study_types]=snap to include it." + } + ] + // ... pagination meta + } +} +``` + +Data from BAV AURA studies is never returned by this endpoint. + +### Data generation + +Brandscape data is generated per study and audience the first time it is requested. If any of the requested study and +audience combinations are still being generated, the response has a `202 Accepted` status code. The rows that are +already available are still returned, and `meta.generation` lists the combinations that are pending. Retry the request +shortly to get the full data. + +```json +{ + "data": [ + // ... rows that are already available + ], + "meta": { + "generation": { + "status": "partial", + "message": "Some of the requested combinations are still being generated. Retry the request shortly.", + "combinations": [ + { + "study_id": 635, + "study_name": "BAV US 2025", + "audience_id": 42, + "audience_name": "Millennials", + "was_just_triggered": true + } + ] + } + // ... pagination meta + } +} ``` -Where `123` is the system ID of the brandscape data. +The `status` is `partial` when some of the requested data is already available, and `pending` when none of it is. ## Schema @@ -55,11 +122,11 @@ Where `123` is the system ID of the brandscape data. The brandscape data schema is large (≈ 350 fields). For that reason we omit the full schema here. It is divided into: - Metadata (for example: study, category, brand, audience information) -- Metric Data +- Metric data -The metric data field names are built up by the `import_name` of the [Brand Metrics](metrics.md) resource and a suffix -depending on the score type. Not all metrics have all score types. The metric resource will show the available score -types. Suffixes are: +The metric data field names are built up by the `key` of the [Brand Metrics](../metrics/metrics.md) resource and a +suffix depending on the score type. Not all metrics have all score types. The metric resource will show the available +score types, and its `brandscape_data_columns` field lists the exact field names. Suffixes are: - `_rank` for percentile rank scores. - `_pct` for percentage scores. @@ -68,57 +135,77 @@ types. Suffixes are: - `_category_index` for index scores against the brand's category. - No suffix for value scores, like base sizes. -In addition to this, there are two special fields: +Every metric you have access to is returned by default. Use the `metric_keys` or `metric_group_keys` parameters (see +below) to limit the metrics returned. -- `is_duplicate` will be true if the brand is studied in multiple categories. All scores but the usage, preference and - recommendation scores are category-agnostic which means that if you perform aggregate analysis (average, standard - deviation etc) on these scores you want to remove duplicates first. -- `brand_name` is the local brand name that was asked in the survey. This can be different from the global brand name - from the brands relationship. You should use this field in combination with the data when available as the brand name. +In addition to the metric data, each row has the following fields: -All fields are sortable, filterable and configurable. +| Key | Type | Description | +|----------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | The system ID of the brandscape data row. | +| `study_type` | string | The type of study the row came from: `syndicated`, `snap`, `fused` or `custom`, or `null` for other study types. Returned by default, and when the `study` relationship is included. | +| `is_duplicate` | boolean | `true` for a brand's second and later categories in the same study. All scores but the usage, preference and recommendation scores are category-agnostic, which means that if you perform aggregate analysis (average, standard deviation etc.) on these scores you want to remove duplicates first. | +| `brand_name` | string | The local brand name that was asked in the survey. This can be different from the global brand name from the brand relationship. You should use this field in combination with the data when available as the brand name. | +| `created_at` | string | A datetime string when this row was first created. | +| `updated_at` | string | A datetime string when this row was last updated. | + +All metric fields are sortable, filterable and configurable. In addition, you may sort by `id`, `brand_name`, +`study_id`, `category_id`, `year_id`, `country_id`, `base_id`, `brand_variation_id`, `is_duplicate`, `created_at` and +`updated_at`. + +For rollup studies (studies made up of several other studies), metrics with a per-study breakdown also return a +`{metric}_rollup` field. This is an object with the value for each underlying study, keyed by study ID, or `null` when +the row has no breakdown. ## Additional Filters -In addition to the standard filters and all the fields, we have a set of helper filters to make querying the data easier -by reducing the need for lookups in our database. These are: +In addition to the standard filters and the metric fields, we have a set of helper filters to make querying the data +easier by reducing the need for lookups in our database. These are: -- `countries` - A comma-separated list of country IDs (for example: 1,2,3). -- `country_code`. A comma-separated list of ISO two letter country codes (for example: GB) which can take the place of - a `country_id` filter. -- `years` - A comma-separated list of year IDs (for example: 1,2,3). -- `year_number`. A comma-separated of years by their numbers (for example: 2022) which can be used over a `year_id` - filter. +- `studies` - A comma-separated list of study IDs (for example: 1,2,3). +- `countries` - A comma-separated list of country IDs (for example: 1,2,3). Requires a year filter. +- `country_code` - A comma-separated list of ISO two letter country codes (for example: GB). Can be used instead of + the `countries` filter. Requires a year filter. +- `years` - A comma-separated list of year IDs (for example: 1,2,3). Requires a country filter. +- `year_number` - A comma-separated list of years by their numbers (for example: 2022). Can be used instead of the + `years` filter. Requires a country filter. +- `study_types` - A comma-separated list of study types that a country and year filter may resolve to (see + [study types](#study-types)). +- `audiences` - A comma-separated list of audience IDs (for example: 1,2,3). Defaults to All Adults (`1`). - `brands` - A comma-separated list of brand IDs (for example: 1,2,3). +- `brand_variations` - A comma-separated list of brand variation IDs (for example: 1,2,3). +- `brand_name` - A search on the brand name, using the search index. - `categories` - A comma-separated list of category IDs (for example: 1,2,3). -- `audiences` - A comma-separated list of audience IDs (for example: 1,2,3). -- `studies` - A comma-separated list of study IDs (for example: 1,2,3). +- `companies` - A comma-separated list of company IDs (for example: 1,2,3). - `sectors` - A comma-separated list of sector IDs (for example: 1,2,3). -- `companies` - A comma-separated list of company IDs (for example: 1,2,3) -- `brand_name`. A text search on the brand name. + +Filters must be given per key, for example `filter[country_code]=GB`. A `400` error is returned if `filter` is given as +a single value. ## Additional Column Customizations -In addition to the standard column customizations we have a helper parameter. This is used as a top-level query -parameter. +In addition to the standard column customizations we have two helper parameters. These are used as top-level query +parameters. -- `metric_keys` - A comma-separated list of metric keys (for example: `differentation,relevance`) which can be used to +- `metric_keys` - A comma-separated list of metric keys (for example: `differentiation,relevance`) which can be used to automatically get all the available score types for these metrics only without having to get each field specifically. -- `metric_group_keys` - A comma-separated list of metric group keys (for example: `imagery,pillars`) which can be used - to automatically get all the available score types for the metrics in these groups, without having to set each metric - specifically. +- `metric_group_keys` - A comma-separated list of [metric group](../metrics/metric-groups.md) keys (for + example: `pillars`) which can be used to automatically get all the available score types for the metrics in these + groups, without having to set each metric specifically. ## Relationships & includes -By default, relationships apart from the sector are not included. See -the [includes section](../customizing/includes) for more information on how this works. The following relationships -are available: - -- `study` - The [study](studies.md) for the brandscape data record. -- `year` - The [year](years.md) for the brandscape data record. -- `country` - The [country](countries.md) for the brandscape data record. -- `audiences` - The [audience](./audiences.md) for the brandscape data record. -- `brand` - The [brand](brands.md) for the brandscape data record. -- `category` - The [category](categories.md) for the brandscape data record. -- `sector` - The [sector](sectors.md) for the brandscape data record. -- `company` - The [company](companies.md) for the brandscape data record. +When you don't use the `include` parameter, each row includes the `study`, `audience` (returned as `base`), `category`, +`brand` and `brand_variation` relationships by default. When you use the `include` parameter, only the relationships +you ask for are returned. See the [includes section](../customizing/includes) for more information on how this works. +The following relationships are available: + +- `study` - The [study](../studies/studies.md) for the brandscape data row. +- `year` - The [year](../metadata/years.md) for the brandscape data row. +- `country` - The [country](../metadata/countries.md) for the brandscape data row. +- `audience` - The [audience](../audiences/audiences.md) for the brandscape data row. Returned in the `base` field. +- `brand` - The [brand](../brands/brands.md) for the brandscape data row. +- `brandVariation` - The brand variation the brand was measured under. Returned in the `brand_variation` field. +- `category` - The [category](../studies/categories.md) for the brandscape data row. +- `sector` - The [sector](../metadata/sectors.md) for the brandscape data row. +- `company` - The [company](../company-data/companies.md) for the brandscape data row. diff --git a/docs/brand-data/category-worth-map.md b/docs/brand-data/category-worth-map.md index dead18b..1e95231 100644 --- a/docs/brand-data/category-worth-map.md +++ b/docs/brand-data/category-worth-map.md @@ -1,5 +1,8 @@ # Category Worth Map +The Category Worth Map is the [Brand Worth Map](brand-worth-map.md) for categories rather than brands. Each category is +placed on the "Worth paying more for" and "Providing good value" axes using the average percentile rank of its brands. + ## Creating a query ```http request @@ -12,4 +15,4 @@ GET /api/v2/tools/category-worth-map |--------------|:----------------------------:|---------------|-----------------------------------------| | `categories` | :white_check_mark: | numeric array | A comma-separated list of Category IDs. | | `studies` | :white_check_mark: | numeric array | A comma-separated list of Study IDs. | -| `audiences` | :x: (defaults to All Adults) | numeric array | A comma-separated list of Audience IDs. | \ No newline at end of file +| `audiences` | :x: (defaults to All Adults) | integer | A single Audience ID. | diff --git a/docs/brand-data/cee-opinions.md b/docs/brand-data/cee-opinions.md index a6eec49..57adb60 100644 --- a/docs/brand-data/cee-opinions.md +++ b/docs/brand-data/cee-opinions.md @@ -23,36 +23,49 @@ GET /api/v2/cee-opinions/123 Where `123` is the system ID of the cee opinion. +The opinion records are only returned for studies you have access to. The endpoints are read-only and require a token +with the `bav:brand-data` scope. + ## Schema ### Full response schema -Because the schema is large we omit it here. It consists of both metadata columns (study details) and the opinion and -value columns. The values are in percent. +Because the schema is large we omit it here. Each record is one study, market, year and audience. It consists of the +`id`, `created_at` and `updated_at` columns plus one column per opinion. The values are in percent. + +Every opinion column can be filtered on, sorted by and selected with [fields](../customizing/fields.md), as can `id` +(exact filter), `created_at` and `updated_at`. ## Additional Filters -For convenience, we have a set of additional filters for brands that are not available in +For convenience, we have a set of additional filters for opinions that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: - `years` - A comma-separated list of year IDs. This will filter the opinions to only those for the given years. -- `year_numbers` - A comma-separated list of year numbers. This will filter the opinions to only those - for the given years. +- `year_number` - A comma-separated list of year numbers. This will filter the opinions to only those for the given + years. - `studies` - A comma-separated list of study IDs. This will filter the opinions to only those for the given studies. - `audiences` - A comma-separated list of audience IDs. This will filter the opinions to only those in the given audiences. - `countries` - A comma-separated list of country IDs. This will filter the opinions to only those for the given countries. -- `country_codes` - A comma-separated list of two-letter ISO country codes. This will filter the opinions to only those +- `country_code` - A comma-separated list of two-letter ISO country codes. This will filter the opinions to only those for the given countries. +- `updated_since` - A date. Only include records updated on or after this date. + +:::note + +Unlike most other endpoints, the year number and country code filters on this endpoint are singular: `year_number` and +`country_code`. + +::: ## Relationships & includes -By default, relationships apart from the sector are not included. See -the [includes section](../customizing/includes) for more information on how this works. The following relationships -are available: +By default, relationships are not included. See the [includes section](../customizing/includes) for more information +on how this works. The following relationships are available: -- `study` - The [study](companies.md) . -- `country` - The [country](countries.md) . -- `year` - The [year](years.md) . -- `audience` - The [audience](./audiences.md) . \ No newline at end of file +- `study` - The [study](../studies/studies.md) the opinions were measured in. +- `country` - The [country](../metadata/countries.md) the opinions were measured in. +- `year` - The [year](../metadata/years.md) the opinions were measured in. +- `audience` - The [audience](../audiences/audiences.md) the opinions are for. diff --git a/docs/brand-data/commitment-funnel.md b/docs/brand-data/commitment-funnel.md index 6a39fd2..f59686c 100644 --- a/docs/brand-data/commitment-funnel.md +++ b/docs/brand-data/commitment-funnel.md @@ -1,15 +1,44 @@ # Commitment Funnel +The Commitment Funnel shows the strength of a brand's behavioral and emotional relationship with consumers, across +seven stages: Loyalty, Adoption and Consideration (behavioral), Awareness, and Respect, Love and Advocate (emotional). + ## Creating a query ```http request GET /api/v2/tools/commitment-funnel ``` +This endpoint takes the same filters as the [brandscape data models](brandscape-data.md). Array parameters are passed +using array syntax, for example: + +```http request +GET /api/v2/tools/commitment-funnel?brands[]=148&brands[]=149&studies[]=635 +``` + ## Parameters -| Key | Required? | Type | Description | -|-------------|:----------------------------:|---------------|-----------------------------------------| -| `brands` | :white_check_mark: | numeric array | A comma-separated list of Brand IDs. | -| `studies` | :white_check_mark: | numeric array | A comma-separated list of Study IDs. | -| `audiences` | :x: (defaults to All Adults) | numeric array | A comma-separated list of Audience IDs. | \ No newline at end of file +At least one of `brands`, `studies`, `countries` or `years` must be provided. `studies` is not required: you can +instead use `countries` and `years` to select studies by market and year. + +| Key | Required? | Type | Description | +|-----------------|:----------------------------:|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `brands` | One of the four filters | array | Up to 50 brands, as brand IDs or brand names. Names are matched to the closest brand. | +| `studies` | One of the four filters | array | Up to 50 studies, as study IDs or study names. Names are matched to the closest study you have access to. | +| `countries` | One of the four filters | array | Up to 50 countries, as country IDs, ISO 3166-1 alpha-2 or alpha-3 codes, or country names. | +| `years` | One of the four filters | array | Up to 50 years, as year IDs or calendar years. | +| `audiences` | :x: (defaults to All Adults) | array | Up to 50 audiences, as audience IDs or audience names. | +| `study_types[]` | :x: (defaults to `syndicated`) | string array | The kinds of study that `countries` and `years` may resolve to: `syndicated` (the standard BAV study), `snap`, `fused` or `custom`. Ignored when `studies` is set. | + +:::note + +The `benchmarks` and `format` parameters accepted by the [brandscape data models](brandscape-data.md) pass validation +on this endpoint but are not applied: the Commitment Funnel always responds with JSON and does not add benchmark rows. + +::: + +## Response + +The response contains a `data` array with one entry per brand data point. Each entry has `study`, `audience`, +`category`, `year`, `country`, `sector` and `brand` objects (each with `id` and `name`), a `brand_display_name`, a +`data_point_label` and a `metrics` array, where each metric has a `key`, `value` and `label`. diff --git a/docs/brand-data/cost-of-entry.md b/docs/brand-data/cost-of-entry.md index fa0c852..d75281f 100644 --- a/docs/brand-data/cost-of-entry.md +++ b/docs/brand-data/cost-of-entry.md @@ -1,5 +1,7 @@ # Cost of Entry +Cost of Entry compares a brand's imagery attributes against the average of a competitive set. + ## Creating a query ```http request @@ -8,11 +10,20 @@ GET /api/v2/tools/cost-of-entry ## Parameters +This endpoint uses the singular `brand`, `study` and `audience` parameters. + | Key | Required? | Type | Description | |------------------|:----------------------------:|---------------|--------------------------------------------------------------------------------------------| | `brand` | :white_check_mark: | integer | A single Brand ID. | | `study` | :white_check_mark: | integer | A single Study ID. | | `audience` | :x: (defaults to All Adults) | integer | A single Audience ID. | -| `categories` | If no collections. | numeric array | A comma-separated list of Category IDs. | -| `collections` | If no categories. | numeric array | A comma-separated list of Collection IDs. | -| `comparisonName` | :x: | string | Give the comparison a custom name. Otherwise the category or collection name will be used. | +| `categories` | If no collections. | numeric array | A comma-separated list of Category IDs that form the competitive set. | +| `collections` | If no categories. | numeric array | A comma-separated list of Collection IDs that form the competitive set. | +| `comparisonName` | :x: | string | A label for the competitive set (max 255 characters). | + +:::caution + +`comparisonName` is accepted but is currently not applied to the Cost of Entry output; the category or collection name +is used. + +::: diff --git a/docs/brand-data/index.md b/docs/brand-data/index.md index ce80d58..a25e1df 100644 --- a/docs/brand-data/index.md +++ b/docs/brand-data/index.md @@ -11,4 +11,20 @@ and all relevant wording. Each endpoint documentation will show you which parameters each endpoint takes and what the response will look like. However, we suggest that you also try each tool in the graphical interface on The Fount to get a better understanding of -the results. \ No newline at end of file +the results. + +## Access + +All tool endpoints require a token with the `bav:brand-data` scope. In addition, each tool requires that the user has +access to that tool in The Fount; otherwise a `403` response is returned. + +## Parameter formats + +Most tool endpoints take comma-separated lists of IDs, for example `brands=148,149`. Where a page lists a parameter as +taking a single ID, only one value is accepted. The [Commitment Funnel](commitment-funnel.md) instead follows the +[brandscape data models](brandscape-data.md) and takes array parameters (`brands[]=148&brands[]=149`), which also accept +names, and can select studies by `countries` and `years`. + +Unless stated otherwise, the `audiences` parameter defaults to All Adults (audience ID `1`), and responses are returned +as JSON in a `data` key. + diff --git a/docs/brand-data/love-plus.md b/docs/brand-data/love-plus.md index 34fb8aa..4175992 100644 --- a/docs/brand-data/love-plus.md +++ b/docs/brand-data/love-plus.md @@ -1,5 +1,7 @@ # Love+ +Love+ shows the four kinds of love a brand inspires: dependable, aspirational, playful and intellectual. + ## Creating a query ```http request @@ -8,8 +10,8 @@ GET /api/v2/tools/love-plus ## Parameters -| Key | Required? | Type | Description | -|-------------|:----------------------------:|---------------|-----------------------------------------| -| `brands` | :white_check_mark: | numeric array | A comma-separated list of Brand IDs. | -| `studies` | :white_check_mark: | numeric array | A comma-separated list of Study IDs. | -| `audiences` | :x: (defaults to All Adults) | numeric array | A comma-separated list of Audience IDs. | \ No newline at end of file +| Key | Required? | Type | Description | +|-------------|:----------------------------:|---------------|--------------------------------------| +| `brands` | :white_check_mark: | numeric array | A comma-separated list of Brand IDs. | +| `studies` | :white_check_mark: | integer | A single Study ID. | +| `audiences` | :x: (defaults to All Adults) | integer | A single Audience ID. | diff --git a/docs/brand-data/partnership-exchange-map.md b/docs/brand-data/partnership-exchange-map.md index 9a6000f..244a6cb 100644 --- a/docs/brand-data/partnership-exchange-map.md +++ b/docs/brand-data/partnership-exchange-map.md @@ -1,5 +1,8 @@ # Partnership Exchange Map +The Partnership Exchange Map compares the imagery attributes of two brands to show what each could bring to a +partnership. + ## Creating a query ```http request @@ -8,8 +11,12 @@ GET /api/v2/tools/partnership-exchange-map ## Parameters -| Key | Required? | Type | Description | -|---------------------|:------------------:|---------------|--------------------------------------| -| `brands` | :white_check_mark: | numeric array | A comma-separated list of Brand IDs. | -| `comparison_brands` | :white_check_mark: | numeric array | A comma-separated list of Brand IDs. | -| `studies` | :white_check_mark: | numeric array | A comma-separated list of Study IDs. | +Give one brand in `brands` and its partner in `comparison_brands`. The exchange is directional, so swapping the two +gives a different result. + +| Key | Required? | Type | Description | +|---------------------|:----------------------------:|---------|--------------------------------------| +| `brands` | :white_check_mark: | integer | A single Brand ID. | +| `comparison_brands` | :white_check_mark: | integer | A single Brand ID for the partner. | +| `studies` | :white_check_mark: | integer | A single Study ID. | +| `audiences` | :x: (defaults to All Adults) | integer | A single Audience ID. | diff --git a/docs/brand-data/swot.md b/docs/brand-data/swot.md index 1f9f2bb..d2fc22c 100644 --- a/docs/brand-data/swot.md +++ b/docs/brand-data/swot.md @@ -1,5 +1,8 @@ # SWOT +SWOT classifies a brand's imagery attributes as strengths, weaknesses, opportunities and threats, by comparing each +attribute against the brand's own average and against the average of a competitive set. + ## Creating a query ```http request @@ -12,7 +15,7 @@ GET /api/v2/tools/swot |------------------|:----------------------------:|---------------|--------------------------------------------------------------------------------------------| | `brands` | :white_check_mark: | numeric array | A comma-separated list of Brand IDs. | | `studies` | :white_check_mark: | numeric array | A comma-separated list of Study IDs. | -| `audiences` | :x: (defaults to All Adults) | numeric array | A comma-separated list of Audience IDs. || `categories` | If no collections. | numeric array | A comma-separated list of Category IDs. | -| `categories` | If no collections. | numeric array | A comma-separated list of Category IDs. | -| `collections` | If no categories. | numeric array | A comma-separated list of Collection IDs. | -| `comparisonName` | :x: | string | Give the comparison a custom name. Otherwise the category or collection name will be used. | +| `audiences` | :x: (defaults to All Adults) | numeric array | A comma-separated list of Audience IDs. | +| `categories` | If no collections. | numeric array | A comma-separated list of Category IDs that form the competitive set. | +| `collections` | If no categories. | numeric array | A comma-separated list of Collection IDs that form the competitive set. | +| `comparisonName` | :x: | string | Give the comparison a custom name (max 255 characters). Otherwise the category or collection name will be used. | diff --git a/docs/brand-data/toplist-market.md b/docs/brand-data/toplist-market.md index b3de891..e7ebca7 100644 --- a/docs/brand-data/toplist-market.md +++ b/docs/brand-data/toplist-market.md @@ -1,5 +1,7 @@ # Market Toplist +The Market Toplist returns the top-ranked brands in a study for each metric you name, ordered by percentile rank. + ## Creating a query ```http request @@ -8,10 +10,11 @@ GET /api/v2/tools/toplist-market ## Parameters -| Key | Required? | Type | Description | -|---------------|:----------------------------:|---------------|-----------------------------------------| -| `brands` | :white_check_mark: | numeric array | A comma-separated list of Brand IDs. | -| `studies` | :white_check_mark: | numeric array | A comma-separated list of Study IDs. | -| `audiences` | :x: (defaults to All Adults) | numeric array | A comma-separated list of Audience IDs. | -| `metrics` | If no metric keys. | numeric array | A comma-separated list of Metric IDs. | -| `metric_keys` | If no metrics. | string array | A comma-separated list of metric keys. | +Choose the metrics with either `metric_keys` or `metrics`. + +| Key | Required? | Type | Description | +|---------------|:----------------------------:|---------------|-----------------------------------------------------------------------------| +| `studies` | :white_check_mark: | integer | A single Study ID. | +| `audiences` | :x: (defaults to All Adults) | integer | A single Audience ID. | +| `metrics` | If no metric keys. | numeric array | A comma-separated list of [brand metric](../metrics/metrics.md) IDs. | +| `metric_keys` | If no metrics. | string array | A comma-separated list of brand metric keys, e.g. `differentiation,relevance`. | diff --git a/docs/brands/brands.md b/docs/brands/brands.md index 2c5791d..3986120 100644 --- a/docs/brands/brands.md +++ b/docs/brands/brands.md @@ -7,9 +7,14 @@ You may use the Brands endpoint to retrieve details about one or more brands. Brands are the core of BAV. They are the entities that are researched by BAV surveys and is connected to many other resources. Brands differ from companies in that they are not necessarily a legal entity. Brands are owned by companies. -Brands in BAV do not belong specifically to a [category resource](categories.md). Each brand is studied in a specific -category in a specific [study](studies.md). However, for classification purposes each brand belongs to -a [sector](sectors.md) based on the studies it is in. +Brands in BAV do not belong specifically to a [category resource](../studies/categories.md). Each brand is studied in a +specific category in a specific [study](../studies/studies.md). However, for classification purposes each brand belongs +to a [sector](../metadata/sectors.md) based on the studies it is in. + +A brand has no scores of its own. Brand data always belongs to a brand in a study, so use these endpoints to find a +brand, then read its data from the [brandscape data](../brand-data/brandscape-data.md) endpoints. + +The brands endpoints are read-only. ## List all brands @@ -33,29 +38,49 @@ Where `123` is the system ID of the brand. ### Full response schema -| Key | Type | Filterable | Sortable | Configurable | Description | -|-----------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | -| `bav_brand_id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The brand key in the BAV database. Note that this may be both a positive and negative integer. Please use the `id` column over this unless you specifically need the brand key for legacy integrations. | -| `bav_id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The brand ID in the BAV database. Please use the `id` column over this unless you specifically need the brand key for legacy integrations. | -| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The global name of the brand. | -| `share_of_company` | float | :white_check_mark: | :white_check_mark: | :white_check_mark: | The percentage share that this brand makes up of the parent company's financial results. | -| `is_core` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this brand is considered a core brand for research purposes. | -| `is_studied_globally` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this brand is designated as a brand that we aim to currently study globally. Please note that this does not necessarily mean that is included in all studies in the current year. | -| `url` | string | :x: | :x: | :white_check_mark: | The URL of the brand's page on The Fount. | -| `logo_url` | string | :x: | :x: | :white_check_mark: | A URL to the latest approved version of the primary brand logo in SVG format. | -| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this brand was first created. | -| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this brand was last updated. | +| Key | Type | Filterable | Sortable | Configurable | Description | +|-----------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `bav_brand_id` | null | :x: | :x: | :x: | **Deprecated.** Always `null`. | +| `bav_id` | null | :x: | :x: | :x: | **Deprecated.** Always `null`. | +| `name` | string | :white_check_mark: (search) | :white_check_mark: | :white_check_mark: | The global name of the brand. Filtering by name uses the search index, the same as [searching](../customizing/searching.md). | +| `qualifier` | string | :x: | :white_check_mark: | :white_check_mark: | Text that tells apart brands with the same or a similar name. | +| `share_of_company` | float | :white_check_mark: | :white_check_mark: | :white_check_mark: | The percentage share that this brand makes up of the parent company's revenue. | +| `is_core` | null | :x: | :x: | :x: | **Deprecated.** Always `null`. | +| `is_studied_globally` | null | :x: | :x: | :x: | **Deprecated.** Always `null`. | +| `is_deprecated` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the brand is deprecated. A deprecated brand keeps its historical data and may point to a `replacement` brand. | +| `signalai_id` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The brand's identifier in Signal AI. | +| `parent_brand_id` | integer | :x: | :x: | :white_check_mark: | The ID of the parent brand in the brand hierarchy, or `null` if the brand has no parent. | +| `website_url` | string | :white_check_mark: | :white_check_mark: | :x: | The brand's website address. | +| `website_domain` | string | :x: | :x: | :x: | The domain of the brand's website address, without `www.` (for example `coca-cola.com`). | +| `social_linkedin` | string | :white_check_mark: | :white_check_mark: | :x: | The brand's LinkedIn profile URL. | +| `social_facebook` | string | :white_check_mark: | :white_check_mark: | :x: | The brand's Facebook profile URL. | +| `social_instagram` | string | :white_check_mark: | :white_check_mark: | :x: | The brand's Instagram profile URL. | +| `social_x` | string | :white_check_mark: | :white_check_mark: | :x: | The brand's X (formerly Twitter) profile URL. | +| `social_youtube` | string | :white_check_mark: | :white_check_mark: | :x: | The brand's YouTube channel URL. | +| `url` | string | :x: | :x: | :x: | The URL of the brand's page on The Fount. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this brand was first created. | +| `updated_at` | string | ([updated since](../customizing/filters.md)) | :white_check_mark: | :white_check_mark: | A datetime string when this brand was last updated. | + +:::caution Deprecated fields + +`bav_brand_id`, `bav_id`, `is_core` and `is_studied_globally` are still returned for backwards compatibility, but are +always `null`. They can no longer be filtered or sorted on. Use `id` to identify brands. The `logo_url` field has been +removed. + +::: ### Relationship Response Schema -The slim relationship schema is used when the brand is used as part of an include in another resource. +The slim relationship schema is used when the brand is used as part of an include in another resource, and for the +`replacement`, `parent` and `children` includes. -| Key | Type | Description | -|----------|---------|--------------------------------------------------------------| -| `id` | integer | The system ID for the brand. | -| `name` | string | The primary name of the brand. | -| `sector` | object | An object with the brand's [sector relationship](sectors.md) | +| Key | Type | Description | +|---------------|---------|----------------------------------------------------------------------------| +| `id` | integer | The system ID for the brand. | +| `name` | string | The primary name of the brand. | +| `sector` | object | An object with the brand's [sector relationship](../metadata/sectors.md). | +| `signalai_id` | string | The brand's identifier in Signal AI. | ## Additional Filters @@ -64,32 +89,54 @@ the [default filters](../customizing/filters.md) or are part of the columns. The - `years` - A comma-separated list of year IDs. This will filter the brands to only those that are studied in the specified years. +- `year_numbers` - A comma-separated list of year numbers (e.g. `2024,2025`). This will filter the brands to only those + that are studied in the specified years. - `categories` - A comma-separated list of category IDs. This will filter the brands to only those that are studied in - the specified categories. + the specified categories. A brand can be in different categories in different studies. - `sectors` - A comma-separated list of sector IDs. This will filter the brands to only those in the given sectors. - `countries` - A comma-separated list of country IDs. This will filter the brands to only those that are studied in the specified countries. +- `country_codes` - A comma-separated list of two-letter ISO country codes. This will filter the brands to only those + that are studied in the specified countries. - `regions` - A comma-separated list of region IDs. This will filter the brands to only those that are studied in the specified regions. +- `region_blocs` - A comma-separated list of region bloc IDs. This will filter the brands to only those that are + studied in countries belonging to the specified region blocs. - `studies` - A comma-separated list of study IDs. This will filter the brands to only those that are included in the specified studies. -- `country_codes` - A comma-separated list of two-letter ISO country codes. This will filter the brands to only those - that are studied in the specified countries. -- `year_numbers` - A comma-separated list of year numbers. This will filter the brands to only those that are studied - in the specified years. -- `has_studies` - Only include brands that have been included in any study at any point in time. +- `companies` - A comma-separated list of [company](../company-data/companies.md) IDs. This will filter the brands to + only those owned by the specified companies. +- `tags` - A comma-separated list of brand tag IDs or keys (e.g. `luxury`). See `/api/v2/brand-tags` for the available + tags. +- `variations` - A comma-separated list of brand variation IDs. This will filter the brands to only those with the + specified variations. +- `has_studies` - Set to `1` to only include brands that have been included in any study at any point in time, or `0` + for brands that have never been studied. ## Relationships & includes -By default, relationships apart from the sector are not included. See -the [includes section](../customizing/includes) for more information on how this works. The following relationships -are available: - -- `company` - The [company](companies.md) that owns the brand. -- `sector` - The [sector](sectors.md) that the brand belongs to. -- `studies` - A list of [BAV studies](studies.md) where this brand was included. -- `countries` - The [countries](countries.md) where this brand may have a local name, custom logo or where it is from. +By default, only the `replacement` relationship is included. See the [includes section](../customizing/includes.md) for +more information on how this works. The following relationships are available: + +- `company` - The [company](../company-data/companies.md) that owns the brand. +- `sector` - The [sector](../metadata/sectors.md) that the brand belongs to. +- `studies` - A list of [BAV studies](../studies/studies.md) where this brand was included. Each study contains its + `id`, `name`, `year`, `country`, `period` and `data_available_at`, plus the `brand_name` and `category_id` the brand + was measured under in that study. +- `studies.category` - Accepted for compatibility. The study entries still only expose the `category_id`; look the + category up via the [categories endpoint](../studies/categories.md). +- `countries` - The [countries](../metadata/countries.md) where the brand is present, with its local name and whether + the country is its country of origin. +- `variations` - The other names this brand is known by. +- `replacement` - The brand that replaced this one, if it is deprecated. Always included. +- `parent` - The parent brand in the brand hierarchy. +- `children` - The child brands in the brand hierarchy. +- `tags` - The brand's tags. `is_ai_generated` shows whether a tag was assigned by AI rather than by hand. ## Searching -This endpoint supports searching. See the [searching section](../customizing/searching) for more details. +This endpoint supports searching. See the [searching section](../customizing/searching.md) for more details. + +When searching (using `search` or `filter[name]`), only the `years`, `year_numbers`, `countries`, `country_codes`, +`regions`, `region_blocs`, `studies`, `categories`, `sectors`, `companies`, `variations`, `tags`, `is_deprecated` +and `has_studies` filters apply, and sorting is limited to a single column. diff --git a/docs/brands/collections.md b/docs/brands/collections.md index eb04b99..13e8cc4 100644 --- a/docs/brands/collections.md +++ b/docs/brands/collections.md @@ -13,7 +13,19 @@ Examples of useful collections are: A collection may be public or private. A public collection is available to all users. A private collection is only available to the user who created it. -A collection can also be shared with any number of users. +A collection can also be shared with any number of users. Through the API you only see your own collections, public +collections and collections shared with you. + +Collection IDs can be used wherever an endpoint takes a `collections` filter or benchmark, for example in the +[brand data tools](../brand-data/index.md). + +:::info Read-only + +The collections endpoints are read-only. Although a `bav:collections:write` token scope exists, the REST API has no +endpoints for creating, updating or deleting collections, and `POST`, `PUT`/`PATCH` and `DELETE` requests to +`/api/v2/collections` return a `400 Bad Request` response. + +::: ## List all collections @@ -41,8 +53,9 @@ Where `123` is the system ID of the collection. |-------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | | `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The primary name of the collection. | -| `collection_type` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the collection is private or public. | -| `uuid` | - | :white_check_mark: | :white_check_mark: | :white_check_mark: | The public unique identifier for the collection. Whenever a collection is shared outside of the system, or a direct link is required we use the UUID over the ID. | +| `collection_type` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The collection type: `1` public, `2` private or `3` report (deprecated). | +| `uuid` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The public unique identifier for the collection. Whenever a collection is shared outside of the system, or a direct link is required we use the UUID over the ID. | +| `url` | string | :x: | :x: | :x: | The URL to view the collection in The Fount. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this collection was first created. | | `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this collection was last updated. | @@ -55,6 +68,16 @@ the [default filters](../customizing/filters.md) or are part of the columns. The - `shared_with_me` - Set to `1` to only return collections shared with the user. - `mine` - Set to `1` to only return collections created by the user. +Any value turns these filters on. + +## Relationships & includes + +By default, relationships are not included. See the [includes section](../customizing/includes) for more information +on how this works. The following relationships are available: + +- `brands` - The [brands](brands.md) in the collection, using the brand relationship schema (`id`, `name`, `sector` + and `signalai_id`). + ## Searching This endpoint supports searching. See the [searching section](../customizing/searching) for more details. \ No newline at end of file diff --git a/docs/company-data/companies.md b/docs/company-data/companies.md index 20aa9a1..fd37349 100644 --- a/docs/company-data/companies.md +++ b/docs/company-data/companies.md @@ -23,6 +23,25 @@ GET /api/v2/companies/123 Where `123` is the system ID of the company. +## Get a company's stock prices + +To get the historical share prices for a company's primary stock exchange listing, use the company stock prices +endpoint: + +```http request +GET /api/v2/companies/123/stock-prices +``` + +Where `123` is the system ID of the company. + +This returns the same response as the [stock prices endpoint](stock-prices.md#response) and is not paginated. It +accepts the `from`, `to` and `interval` parameters described in +the [stock prices documentation](stock-prices.md#parameters). Omitting `from` and `to` returns the full price history, +so use a date window or a `weekly` or `monthly` `interval` to keep the response small. + +A company without a primary listing returns no rows, and its ID is listed in `meta.companies_without_listing`. A `503` +error is returned if the market data provider cannot be reached. + ## Schema ### Full response schema @@ -44,6 +63,7 @@ Where `123` is the system ID of the company. | `officers` | array | :white_check_mark: | :x: | :white_check_mark: | An array of names and roles of the registered company officers. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this company was first created. | | `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this company was last updated. | +| `url` | string | :x: | :x: | :x: | The URL to view the company in The Fount. | ### Relationship Response Schema @@ -61,17 +81,19 @@ the [default filters](../customizing/filters.md) or are part of the columns. The - `public` - Set to `1` to only return public (listed) companies. - `private` - Set to `1` to only return private (unlisted) companies. -- `brands` - Set to a comma-separated list of brand IDs to only return companies that own those brands. +- `brands` - Set to a comma-separated list of brand IDs to only return companies whose linked `brand` (the brand that + represents the company itself) is one of those brands. This does not match every brand the company owns. ## Relationships & includes -By default, relationships apart from the sector are not included. See +By default, relationships are not included. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: -- `brand` - The [brand](brands.md) relation if the company name is also a tracked brand name. -- `brands` - The [brands](brands.md) that belong to the company. -- `gics_sector` - The [GICS Sector](gics-sectors.md) that categorizes the company. -- `stock_exchanges` - The [stock exchanges](stock-exchanges.md) that the company is listed on. -- `country` - The [country](countries.md) that the company is headquartered in. +- `brand` - The [brand](../brands/brands.md) that represents the company itself, where one is linked. +- `brands` - The [brands](../brands/brands.md) that belong to the company. +- `gics_sector` - The [GICS Sector](../metadata/gics-sectors.md) that categorizes the company. +- `stock_exchanges` - The [stock exchanges](../metadata/stock-exchanges.md) that the company is listed on. Each + exchange also includes the company's `stock_ticker` on that exchange. +- `country` - The [country](../metadata/countries.md) that the company is registered in. - `latest_financials` - The latest financials for the company (available for public companies). diff --git a/docs/company-data/stock-prices.md b/docs/company-data/stock-prices.md index bee260f..72b1e62 100644 --- a/docs/company-data/stock-prices.md +++ b/docs/company-data/stock-prices.md @@ -2,59 +2,119 @@ ## What are stock prices? -Stock prices are the prices of a company's stock on a particular stock exchange. They are used to calculate the value of -a company. We collect stock prices for all companies on all stock exchanges that belong to brands that are covered in -BAV. +Stock prices are the historical share prices of a company's stock exchange listings. They are read from our market data +provider when you request them, one listing at a time, so a request has to name the companies or tickers it wants. -## List all stock prices +Prices are available for any company with a primary stock exchange listing, as well as for any ticker you name +directly, even when it isn't linked to a company in The Fount. -To list all of the stock prices and browse them via the API, use the list endpoint: +## List stock prices -```http request -GET /api/v2/stock-prices -``` - -## Get a stock price - -You may also directly retrieve a stock price's details if you already have its system ID. +To get the stock prices for one or more listings, use the list endpoint: ```http request -GET /api/v2/stock-prices/123 +GET /api/v2/stock-prices?companies[]=91&from=2024-01-01&to=2024-12-31 ``` -Where `123` is the system ID of the stock price. - -## Schema - -### Full response schema - -| Key | Type | Filterable | Sortable | Configurable | Description | -|------------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|------------------------------------------------------------| -| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | -| `date` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The date for the stock price value. | -| `open_price` | float | :white_check_mark: | :white_check_mark: | :white_check_mark: | The opening price for the day. | -| `close_price` | float | :white_check_mark: | :white_check_mark: | :white_check_mark: | The closing price for the day. | -| `adjusted_close_price` | float | :white_check_mark: | :white_check_mark: | :white_check_mark: | The adjusted closing price for the day. | -| `high_price` | float | :white_check_mark: | :white_check_mark: | :white_check_mark: | The highest price for the day. | -| `low_price` | float | :white_check_mark: | :white_check_mark: | :white_check_mark: | The lowest price for the day. | -| `trading_volume` | integer | :white_check_marl: | :white_check_mark: | :white_check_mark: | The amount of trades for the day. | -| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this stock price was first created. | -| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this stock price was last updated. | - -## Additional Filters - -For convenience, we have a set of additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: - -- `companies` - A comma-separated list of company IDs to only return stock prices for those companies. -- `stock_exchanges` - A comma-separated list of stock exchange IDs to only return stock prices for those stock - exchanges. - -## Relationships & includes - -By default, relationships apart from the sector are not included. See -the [includes section](../customizing/includes) for more information on how this works. The following relationships -are available: +There is no endpoint for retrieving a single stock price. To get the prices for a single company, you can also use the +[company stock prices endpoint](companies.md#get-a-companys-stock-prices). + +:::note This endpoint works differently +Unlike most other list endpoints, the stock prices endpoint is not paginated and does not support +[filters](../customizing/filters.md), [sorting](../customizing/filters.md#sorting-results), +[configurable fields](../customizing/fields.md), [includes](../customizing/includes.md) or `updated_since`. Omitting +`from` and `to` returns the full price history for each listing, so set a date window or a `weekly` or `monthly` +`interval` to keep the response small. +::: + +## Parameters + +You must name at least one company or ticker. You may name up to 25 companies and tickers in total per request. + +| Key | Required? | Type | Description | +|-------------|:---------:|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `companies` | :x: | array | The [companies](companies.md) to get stock prices for, by ID or name. Each company uses its primary stock exchange listing. Send as an array, for example: `companies[]=91&companies[]=148`. | +| `tickers` | :x: | string array | Tickers to get stock prices for, in `TICKER.EXCHANGE` form (for example `AAPL.US`). All US listings use the `.US` exchange code. Use this for listings that are not linked to a company. For example: `tickers[]=AAPL.US`. | +| `from` | :x: | date | The first trading day to return, inclusive, as `YYYY-MM-DD`. Omit to start at the beginning of the history. | +| `to` | :x: | date | The last trading day to return, inclusive, as `YYYY-MM-DD`. Must be on or after `from`. Omit to return up to the most recent close. | +| `interval` | :x: | string | One of `daily` (default), `weekly` or `monthly`. See [intervals](#intervals). | + +A ticker that duplicates the primary listing of a requested company is only returned once. + +### Intervals + +By default, one row is returned per trading day. Daily rows only exist for trading days, so there are no rows for +weekends and market holidays. + +With a `weekly` or `monthly` interval, each row covers a full week or month. The row holds the period's first open, +its highest high and lowest low, its total volume and its last close. The row is dated on the period's last trading day. + +## Response + +The response contains a `data` array with the price rows and a `meta` object describing the response. Rows are grouped +by ticker and sorted oldest first within each ticker. + +```json +{ + "meta": { + "tickers": ["AAPL.US"], + "count": 251, + "from": "2024-01-01", + "to": "2024-12-31", + "interval": "daily", + "tickers_without_prices": [], + "companies_without_listing": [] + }, + "data": [ + { + "ticker": "AAPL.US", + "date": "2024-01-02", + "company_id": 1, + "currency": "USD", + "open": 187.15, + "high": 188.44, + "low": 183.89, + "close": 185.64, + "adjusted_close": 184.29, + "volume": 82488700 + } + // ... more rows + ] +} +``` -- `company` - The [company](companies.md). -- `stock_exchange` - The [stock exchange](stock-exchanges.md). +### Row schema + +| Key | Type | Description | +|------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------| +| `ticker` | string | The ticker the price belongs to, in `TICKER.EXCHANGE` form. | +| `date` | string | The trading day as `YYYY-MM-DD`. For weekly and monthly intervals, this is the last trading day of the period. | +| `company_id` | integer | The ID of the [company](companies.md) with this listing, or `null` when no company is linked to the ticker. | +| `currency` | string | The currency of the prices, taken from the exchange the ticker trades on. `null` when the exchange is not known. | +| `open` | float | The first price traded at in the row's day, week or month. | +| `high` | float | The highest price traded at during the row's day, week or month. | +| `low` | float | The lowest price traded at during the row's day, week or month. | +| `close` | float | The last price traded at. This is not adjusted for splits and dividends. | +| `adjusted_close` | float | The close adjusted for splits and dividends. Use this when comparing prices over time, as `close` is not comparable across a split. | +| `volume` | integer | The number of shares traded during the row's day, week or month. | + +All price and volume fields may be `null` when the provider has no value for them. + +### Meta schema + +| Key | Type | Description | +|-----------------------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| `tickers` | string array | The tickers the response covers, including the primary listings of the requested companies. | +| `count` | integer | The number of rows returned. | +| `from` | string | The requested start date, or `null` when the series starts at the beginning of the history. | +| `to` | string | The requested end date, or `null` when the series runs to the most recent close. | +| `interval` | string | The interval used: `daily`, `weekly` or `monthly`. | +| `tickers_without_prices` | string array | Tickers with no prices at all, usually because they are mistyped or delisted. A ticker that simply didn't trade in the requested window isn't listed here. | +| `companies_without_listing` | integer array | The IDs of requested companies that have no primary stock exchange listing, and so returned no rows. | + +## Errors + +- A `422` error is returned if neither `companies` nor `tickers` is given, if more than 25 companies and tickers are + named in total, if a ticker contains characters other than letters, numbers, dots, dashes and underscores, or if `to` + is before `from`. +- A `503` error is returned if the market data provider cannot be reached. Retry the request later. diff --git a/docs/customizing/fields.md b/docs/customizing/fields.md index 658114d..31668ed 100644 --- a/docs/customizing/fields.md +++ b/docs/customizing/fields.md @@ -28,7 +28,7 @@ GET /api/v2/brands?fields[brands]=id,name Let's say you want to retrieve a list of brands to show in a dropdown for users to select. You'll want the brand ID for the value and the name for the display label. Instead of forcing you to download the -full [Brands response](../brand-data/brands.md), you may configure to only retrieve the columns you need. +full [Brands response](../brands/brands.md), you may configure to only retrieve the columns you need. ```http request GET /api/v2/brands?fields[brands]=id,name diff --git a/docs/customizing/searching.md b/docs/customizing/searching.md index 8b893c2..bbd09c1 100644 --- a/docs/customizing/searching.md +++ b/docs/customizing/searching.md @@ -13,3 +13,14 @@ To search, add the `search` parameter to the request. For example: ```http request GET https://fount.wppbav.com/api/v2/brands?search=Apple ``` + +## Search results + +Search results are ordered by relevance, with the best matches first. If you also set the `sort` parameter, the +results are ordered by your sort instead. + +:::note Search is limited to 1000 results +A search returns at most the 1000 best matches, regardless of how many records actually match. Pagination works +within those results, so you can't page past the first 1000 matches. If you need more results, make your search more +specific or combine it with [filters](filters.md) instead. +::: diff --git a/docs/errors.md b/docs/errors.md index 6fab316..1ac7e13 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -14,21 +14,38 @@ If you receive an HTML response when an error occurs check your accept header. T ## Response Codes -| Code | Description | -|--------------------------------------------|------------------------------------------------------------------------------------------------------| -| `200` - OK | Everything works as expected. | -| `400` - Bad Request | The request could not be handled, often due to a missing required parameter or badly formatted data. | -| `401` - Unauthorized | No valid API token provided or the API token used does not have the required scopes. | -| `403` - Forbidden | The user does not have permission to perform the requested action. | -| `404` - Not Found | The requested resource doesn't exist. | -| `500`, `502`, `503`, `504` - Server Errors | These are rare errors when something's wrong on The Fount's end. | +| Code | Description | +|--------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `200` - OK | Everything works as expected. | +| `201` - Created | The resource was created. | +| `202` - Accepted | The request was accepted, but some of the data is still being generated. Retry the request shortly. See for example [brandscape data](brand-data/brandscape-data.md#data-generation). | +| `204` - No Content | The request succeeded and there is no content to return, for example after deleting a resource. | +| `400` - Bad Request | The request could not be handled, often due to a missing required parameter, an invalid filter, sort or include, or badly formatted data. | +| `401` - Unauthorized | No valid API token provided or the API token used does not have the required [scopes](authentication.md#scopes). | +| `403` - Forbidden | The user does not have permission to perform the requested action. | +| `404` - Not Found | The requested resource doesn't exist. | +| `422` - Unprocessable Content | The request failed validation. The response includes an `errors` object with the validation errors for each parameter. | +| `429` - Too Many Requests | You have exceeded the [rate limit](rate-limiting.md). | +| `500`, `502`, `504` - Server Errors | These are rare errors when something's wrong on The Fount's end. | +| `503` - Service Unavailable | The Fount, or an upstream provider that the endpoint relies on (such as the market data provider for [stock prices](company-data/stock-prices.md)), is temporarily unavailable. Retry the request later. | ## Response ```json { - "data": { - "message": "Human readable error message." + "message": "Human readable error message." +} +``` + +Validation errors (`422`) also include the errors for each parameter: + +```json +{ + "message": "The to field must be a date after or equal to from.", + "errors": { + "to": [ + "The to field must be a date after or equal to from." + ] } } ``` diff --git a/docs/health-check.md b/docs/health-check.md index c181c22..b1f118f 100644 --- a/docs/health-check.md +++ b/docs/health-check.md @@ -1,27 +1,30 @@ # Health Check For some integrations and applications it can be helpful to check if the BAV API is up and running. This can be done by -sending a GET request to the `/health` endpoint. This endpoint is designed to return a simple response indicating the +sending a GET request to the health endpoint. This endpoint is designed to return a simple response indicating the health status of the API. ## Endpoint +```http request +GET /api/v2/health ``` -GET /health -``` + +This endpoint does not require authentication, so you don't need to send an API token. It is still subject to +the [rate limit](rate-limiting.md). ## Response The endpoint will return a 200 OK HTTP status code if the API is healthy. The response will be in JSON format and will -include a status message and a timestamp of the check. +include a status message and a timestamp of the check. The timestamp is in UTC, in the `YYYY-MM-DD HH:MM:SS` format. -Any status code that isn't 200 OK or a permissions issue (401 and 403) should be considered a failure. Because this -endpoint is very lightweight its response time should be very low. When connecting to the endpoint you may set a -short timeout (e.g. 1 second) to avoid long waits in case of an issue. +Any status code that isn't 200 OK should be considered a failure. Because this endpoint is very lightweight its response +time should be very low. When connecting to the endpoint you may set a short timeout (e.g. 1 second) to avoid long waits +in case of an issue. ```json { "status": "ok", - "timestamp": "2023-10-01T12:00:00Z" + "timestamp": "2026-10-01 12:00:00" } ``` diff --git a/docs/metadata/cities.md b/docs/metadata/cities.md index e6655fe..de20353 100644 --- a/docs/metadata/cities.md +++ b/docs/metadata/cities.md @@ -27,33 +27,37 @@ Where `123` is the system ID of the city. ### Full response schema -| Key | Type | Filterable | Sortable | Configurable | Description | -|---------------------------|----------|:-----------------------------------------:|:------------------:|:------------------:|----------------------------------------------------------------------------------------------------------------------| -| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID for the country. | -| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the country in English. | -| `latitude` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | - | -| `longitude` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | - | -| `timezone` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The timezone for the city, e.g. "Europe/London" | -| `population` | ineteger | :white_check_mark: | :white_check_mark: | :white_check_mark: | The population of the city. | -| `elevation` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The city's elevation. Also see digital_elevation_model which is available for more cities. | -| `digital_elevation_model` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | Another measure of the city's elevation. | -| `geonames_feature_code` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The [feature code](http://www.geonames.org/export/codes.html) from Geonames, allowing you to filter on type of city. | -| `created_at` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A datetime string when this city was first created in the system. | -| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this city was last updated in the system. | +| Key | Type | Filterable | Sortable | Configurable | Description | +|---------------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-----------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID for the city. Always returned. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the city. | +| `geonames_id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The city's ID in [GeoNames](https://www.geonames.org). | +| `latitude` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The city's latitude. | +| `longitude` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The city's longitude. | +| `timezone` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The IANA timezone for the city, e.g. "Europe/London". | +| `population` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The population of the city. | +| `elevation` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The city's elevation in meters, where GeoNames has a surveyed value. Also see `digital_elevation_model` which is available for more cities. | +| `digital_elevation_model` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The city's elevation in meters from the GeoNames digital elevation model. | +| `geonames_feature_code` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The [feature code](http://www.geonames.org/export/codes.html) from GeoNames, allowing you to filter on type of city. `PPLC` is a capital city. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this city was first created in the system. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this city was last updated in the system. | + +You can also sort the cities by `country_id`. To get the country for each city, use the `country` include. ## Additional Filters For convenience, we have a set of additional filters that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: -- `capitals` - Set to `true` to only return capital cities. +- `capitals` - Set to `1` to only return capital cities. - `regions` - Set to a comma-separated list of region IDs to only return cities in those regions. - `countries` - Set to a comma-separated list of country IDs to only return cities in those countries. -- `in_best_countries` - Set to a year number (e.g. 2023) to only return cities that are included in the Best Countries ranking for that year. +- `in_best_countries` - Set to a comma-separated list of year numbers (e.g. `2023,2024`) to only return cities that are + included in the Best Countries ranking for those years. ## Relationships & includes -By default, relationships apart from the sector are not included. See +By default, relationships are not included. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: diff --git a/docs/metadata/countries.md b/docs/metadata/countries.md index 388467e..9914ce5 100644 --- a/docs/metadata/countries.md +++ b/docs/metadata/countries.md @@ -29,22 +29,22 @@ Where `123` is the system ID of the country. ### Full response schema -| Key | Type | Filterable | Sortable | Configurable | Description | -|----------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-------------------------------------------------------------| -| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID for the country. | -| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the market should be used/shown or not. | -| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the country in English. | -| `native_name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the country in its native language. | -| `code` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The two-letter code (ISO 3166-1 alpha-2) for the country. | -| `code_alpha3` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The three-letter code (ISO 3166-1 alpha-3) for the country. | -| `code_numeric` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The numeric code (ISO 3166-1 numeric) for the country. | -| `capital` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the country's capital. | -| `area` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The size of the country. | -| `latitude` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | - | -| `longitude` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | - | -| `flag` | string | :x: | :x: | :white_check_mark: | The URL to the country's flag as an image. | -| `created_at` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A datetime string when this country was first created. | -| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this country was last updated. | +| Key | Type | Filterable | Sortable | Configurable | Description | +|----------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID for the country. Always returned. | +| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the market should be used/shown or not. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the country in English. | +| `native_name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the country in its native language. | +| `code` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The two-letter code (ISO 3166-1 alpha-2) for the country. | +| `code_alpha3` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The three-letter code (ISO 3166-1 alpha-3) for the country. | +| `code_numeric` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The numeric code (ISO 3166-1 numeric) for the country. | +| `region` | object | ([regions](#additional-filters)) | :x: | :x: | The [region](regions.md) that the country belongs to. Always returned. | +| `capital` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the country's capital. | +| `area` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The size of the country in square kilometers. | +| `latitude` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The latitude of the country's center. | +| `longitude` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The longitude of the country's center. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this country was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this country was last updated. | ### Relationship Response Schema @@ -54,10 +54,10 @@ The slim relationship schema is used when the country is used as part of an incl |----------------|---------|------------------------------------------------------------------------------------------| | `id` | integer | The system ID for the country. | | `name` | string | The name of the country in English. | -| `region` | object | An object with the region that this country belongs to [sector relationship](sectors.md) | -| `code` | object | The two-letter code (ISO 3166-1 alpha-2) for the country. | -| `code_alpha3` | object | The three-letter code (ISO 3166-1 alpha-3) for the country. | -| `code_numeric` | object | The numeric code (ISO 3166-1 numeric) for the country. | +| `region` | string | The name of the [region](regions.md) that this country belongs to. | +| `code` | string | The two-letter code (ISO 3166-1 alpha-2) for the country. | +| `code_alpha3` | string | The three-letter code (ISO 3166-1 alpha-3) for the country. | +| `code_numeric` | string | The numeric code (ISO 3166-1 numeric) for the country. | ## Additional Filters @@ -66,19 +66,21 @@ the [default filters](../customizing/filters.md) or are part of the columns. The - `active` - Set to `1` to only return active countries. - `regions` - Set to a comma-separated list of region IDs to only return countries in those regions. -- `with_studies` - Include this parameter to only return countries that have studies (note that these can be both released and unreleased studies). -- `with_recent_studies` - Set to a number (X) to only return countries that have released syndicated BAV studies in the last X calendar years. - For example: When set to 0 it will return countries that have studies in the current. When set to 1 it will return - countries that have studies in the current or past calendar year. -- `in_best_countries` - Set to a year number (e.g. 2023) to only return countries that are included in the Best Countries ranking for that year. +- `with_studies` - Include this parameter to only return countries that have studies (note that these can be both + released and unreleased studies). +- `with_recent_studies` - Set to a number (X) to only return countries that have an available syndicated BAV study in + the last X calendar years. For example: When set to 0 it will return countries that have studies in the current year. + When set to 1 it will return countries that have studies in the current or past calendar year. +- `with_recent_studies_incl_snap` - Works like `with_recent_studies`, but also counts custom and SnapBAV studies. +- `in_best_countries` - Set to a comma-separated list of year numbers (e.g. `2023,2024`) to only return countries that + are included in the Best Countries ranking for those years. ## Relationships & includes -By default, relationships apart from the sector are not included. See -the [includes section](../customizing/includes) for more information on how this works. The following relationships -are available: +The `region` relationship is always included. See the [includes section](../customizing/includes) for more +information on how includes work. The following relationships are available: -- `region` - The [region](regions.md) that -. +- `region` - The [region](regions.md) that the country belongs to. ## Searching diff --git a/docs/metadata/operating-companies.md b/docs/metadata/operating-companies.md index 1994189..86a868d 100644 --- a/docs/metadata/operating-companies.md +++ b/docs/metadata/operating-companies.md @@ -54,5 +54,5 @@ By default, relationships apart from the sector are not included. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: -- `parent` - The [company](companies.md) that owns another company. -- `brand` - The [brand](brands.md) that the operating company has. +- `parent` - The [company](../company-data/companies.md) that owns another company. +- `brand` - The [brand](../brands/brands.md) that the operating company has. diff --git a/docs/metadata/sectors.md b/docs/metadata/sectors.md index 57e7df9..e057a41 100644 --- a/docs/metadata/sectors.md +++ b/docs/metadata/sectors.md @@ -2,8 +2,8 @@ ## What are sectors? -When doing a BAV study, some questions are asked that relate sectors to one or more [categories](categories.md). You -can read more about the categories and what they represent on the [categories endpoint](categories.md). +When doing a BAV study, some questions are asked that relate sectors to one or more [categories](../studies/categories.md). You +can read more about the categories and what they represent on the [categories endpoint](../studies/categories.md). Each category belongs to a sector, which is a broader classification of categories. The benefit of a sector is that it is easier to compare across countries and years. @@ -62,7 +62,7 @@ By default, relationships apart from the sector are not included. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: -- `categories` - The [categories](categories.md) that belong to this sector. +- `categories` - The [categories](../studies/categories.md) that belong to this sector. ## Searching diff --git a/docs/metadata/stock-exchanges.md b/docs/metadata/stock-exchanges.md index 7c49446..fdb104d 100644 --- a/docs/metadata/stock-exchanges.md +++ b/docs/metadata/stock-exchanges.md @@ -2,7 +2,7 @@ ## What are stock exchanges? -Stock Exchanges are the entities where public [companies](companies.md) are listed. +Stock Exchanges are the entities where public [companies](../company-data/companies.md) are listed. ## List all stock exchanges diff --git a/docs/metrics/metric-groups.md b/docs/metrics/metric-groups.md index a7d6633..b1cbe83 100644 --- a/docs/metrics/metric-groups.md +++ b/docs/metrics/metric-groups.md @@ -31,11 +31,11 @@ Where `123` is the system ID of the brand metric group. |---------------|---------|:-----------------------------------------:|:------------------:|:------------------:|--------------------------------------------------------| | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | | `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The primary name of the group. | -| `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A machine-readable name for the group. | +| `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A machine-readable name for the group. Used by the `metric_group_keys` parameter on [brandscape data](../brand-data/brandscape-data.md). | | `description` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A short description on what this group is about. | -| `is_public` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the group is publicly available for all users. | | -| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this brand was first created. | -| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this brand was last updated. | +| `is_public` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the group is publicly available for all users. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this group was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this group was last updated. | ### Relationship Response Schema @@ -48,16 +48,16 @@ The slim relationship schema is used when the brand metric group is used as part ## Additional Filters -For convenience, we have a set of additional filters for brands that are not available in +For convenience, we have a set of additional filters for brand metric groups that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: -- `public` - Set to `1` to only return public metrics. -- `private` - Set to `1` to only return private metrics. +- `public` - Set to `1` to only return public groups. +- `private` - Set to `1` to only return private groups. ## Relationships & includes -By default, relationships apart from the sector are not included. See +By default, relationships are not included. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: -- `metric` - The [metrics](metrics.md) that are part of this group. +- `metrics` - The [metrics](metrics.md) that are part of this group. diff --git a/docs/metrics/metrics.md b/docs/metrics/metrics.md index 86a43be..eea9de4 100644 --- a/docs/metrics/metrics.md +++ b/docs/metrics/metrics.md @@ -13,9 +13,9 @@ To list all of the brand metrics and browse them via the API, use the list endpo GET /api/v2/brand-metrics ``` -## Get a brand +## Get a brand metric -You may also directly retrieve a brand's details if you already have its system ID. +You may also directly retrieve a brand metric's details if you already have its system ID. ```http request GET /api/v2/brand-metrics/123 @@ -30,24 +30,25 @@ Where `123` is the system ID of the brand metric. | Key | Type | Filterable | Sortable | Configurable | Description | |-----------------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|----------------------------------------------------------------------------------| | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A machine-readable key for the metric. Brandscape data fields are named after it. | | `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The primary name of the metric. | | `description` | string | :x: | :x: | :white_check_mark: | A short description on what this metric is about. | | `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | If the metric is active or deprecated. | | `is_public` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric is publicly available for all users. | | `is_core` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric is part of the core set of BAV metrics. | | `is_legacy` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric has been discontinued and will not available in new studies. | -| `has_construct_score` | - | :white_check_mark: | :x: | :white_check_mark: | Whether the metric has a construct score available. | -| `has_percentile_rank_score` | - | :white_check_mark: | :x: | :white_check_mark: | Whether the metric has a percentile rank score available. | -| `has_percentage_score` | - | :white_check_mark: | :x: | :white_check_mark: | Whether the metric has a percentage score available. | -| `has_value_score` | - | :white_check_mark: | :x: | :white_check_mark: | Whether the metric has a value score available. | -| `has_index_score` | - | :white_check_mark: | :x: | :white_check_mark: | Whether the metric has the two index scores available (brandscape and category). | -| `brandscape_data_columns` | array | :x: | :x: | :x: | An array of column names in the `brandscape_data` endpoint for this metric. | +| `has_construct_score` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric has a construct score available. | +| `has_percentile_rank_score` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric has a percentile rank score available. | +| `has_percentage_score` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric has a percentage score available. | +| `has_value_score` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric has a value score available. | +| `has_index_score` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric has the two index scores available (brandscape and category). | +| `brandscape_data_columns` | array | :x: | :x: | :x: | An array of the field names for this metric in the [brandscape data](../brand-data/brandscape-data.md) endpoint. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this brand metric was first created. | -| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this brand metric was last updated. | +| `updated_at` | string | ([updated since](../customizing/filters.md)) | :white_check_mark: | :white_check_mark: | A datetime string when this brand metric was last updated. | ### Relationship Response Schema -The slim relationship schema is used when the brand is used as part of an include in another resource. +The slim relationship schema is used when the brand metric is used as part of an include in another resource. | Key | Type | Description | |-------------|---------|----------------------------------------| @@ -57,15 +58,15 @@ The slim relationship schema is used when the brand is used as part of an includ ## Additional Filters -For convenience, we have a set of additional filters for brands that are not available in +For convenience, we have a set of additional filters for brand metrics that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: - `active` - Set to `1` to only return active metrics. - `inactive` - Set to `1` to only return inactive metrics. - `public` - Set to `1` to only return public metrics. - `private` - Set to `1` to only return private metrics. -- `groups` - A comma-separated list of audience group IDs. This will only return metrics that belong to the - specified groups. +- `group` - A comma-separated list of [brand metric group](metric-groups.md) IDs. This will only return metrics that + belong to the specified groups. - `current` - Set to `1` to only return metrics that are in use in studies today. - `legacy` - Set to `1` to only return legacy metrics. - `core` - Set to `1` to only return core metrics. @@ -73,8 +74,8 @@ the [default filters](../customizing/filters.md) or are part of the columns. The ## Relationships & includes -By default, relationships apart from the sector are not included. See -the [includes section](../customizing/includes) for more information on how this works. The following relationships +By default, relationships are not included. See +the [includes section](../customizing/includes.md) for more information on how this works. The following relationships are available: - `group` - The [group](metric-groups.md) that the metric belongs to. diff --git a/docs/pagination.md b/docs/pagination.md index f653540..5f6bbb1 100644 --- a/docs/pagination.md +++ b/docs/pagination.md @@ -9,7 +9,8 @@ and collections. You may use the following query parameters on list resources: - `page` will let you set the currently active page. -- `per_page` will let you set how many records you want to retrieve per page. Maximum of 1000. Default is 25. +- `per_page` will let you set how many records you want to retrieve per page. Maximum of 1000. Default is 25. A `400` + error is returned if you ask for more than 1000 records per page. URL Example: @@ -121,4 +122,5 @@ The structure of the API list response is as follows: "to": 15, "total": 2434 } +} ``` diff --git a/docs/rate-limiting.md b/docs/rate-limiting.md index 3e2a453..f1f9b60 100644 --- a/docs/rate-limiting.md +++ b/docs/rate-limiting.md @@ -1,10 +1,11 @@ # Rate Limiting The API has a rate limit of 500 requests per minute based on the user. This means that the rate limit applies to all of -your personal access tokens collectively. +your personal access tokens collectively. Requests without authentication, such as to the +[health check](health-check.md), are rate limited by IP address. :::note -When you run several requests per second you may find that the security suite in front of the API blocks you sooner than the rate limit, especially when run on public clouds. If you face this issue, please reduce the amount of requests you are making. If the resulting amount of requsts per second is too low to be viable for your use-case, please get in touch with us. +When you run several requests per second you may find that the security suite in front of the API blocks you sooner than the rate limit, especially when run on public clouds. If you face this issue, please reduce the amount of requests you are making. If the resulting amount of requests per second is too low to be viable for your use-case, please get in touch with us. ::: Each API response will return headers informing you of the rate limit and how many requests you have left. diff --git a/docs/studies/categories.md b/docs/studies/categories.md index 7dafb8c..4e04729 100644 --- a/docs/studies/categories.md +++ b/docs/studies/categories.md @@ -37,6 +37,10 @@ You may also directly retrieve a category's details if you already have its syst GET /api/v2/categories/123 ``` +Where `123` is the system ID of the category. + +The categories endpoints are read-only and require a token with the `bav:brand-data` scope. + ## Schema ### Full response schema @@ -57,19 +61,22 @@ The slim relationship schema is used when the category is used as part of an inc | `id` | integer | The system ID for the category. | | `name` | string | The primary name of the category. | +When the category is included with a nested `sector` include (for example `category.sector`), the relationship object +also contains a `sector` object. + ## Additional Filters -For convenience, we have a set of additional filters for brands that are not available in +For convenience, we have a set of additional filters for categories that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: - `sectors` - A comma-separated list of sector IDs. This will filter the categories to only those in the given sectors. ## Relationships & includes -By default, relationships not included. See the [includes section](../customizing/includes) for more information on how +By default, relationships are not included. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: -- `sector` - The [sector](sectors.md) that the category belongs to. +- `sector` - The [sector](../metadata/sectors.md) that the category belongs to. ## Searching diff --git a/docs/studies/studies.md b/docs/studies/studies.md index 222a3b2..6c1e77d 100644 --- a/docs/studies/studies.md +++ b/docs/studies/studies.md @@ -2,12 +2,14 @@ ## What are studies? -A fundamental element of our datasets are studies. A study is a collection of data from respondents at a specific point -in time. Most markets in BAV are for example covered at most once a year with the exception of the US which is done -quarterly. +A fundamental element of our datasets are studies. A study is a collection of data from respondents in one market at a +specific point in time. Most markets in BAV are for example covered at most once a year with the exception of the US +which is done quarterly. -Studies are a primary way of filtering our [brandscape data](./brandscape-data.md) and also contains information about the -study iself, such as when it was conducted and how many respondents it had. +Studies are a primary way of filtering our [brandscape data](../brand-data/brandscape-data.md) and also contains +information about the study itself, such as when it was conducted and how many respondents it had. + +You only see the studies you have access to. The studies endpoints are read-only. ## List all studies @@ -35,41 +37,114 @@ You may get a list of all brands in a study by using the following endpoint: GET /api/v2/studies/123/brands ``` -Where `123` is the system ID of the study. +Where `123` is the system ID of the study. A brand measured in several categories appears once per category. Returns +`404` if the study does not exist or you do not have access to it. This endpoint requires a token with the `bav:brand-data` +scope. + +## Get categories in a study + +You may get a list of the categories in a study by using the following endpoint: + +```http request +GET /api/v2/studies/123/categories +``` + +Where `123` is the system ID of the study. Each record is one brand in one category, so a category appears once for +every brand measured in it. + +## Study types + +The `type` field is a number. The `type_details` object (and the `study_type`/`study_type_label` fields on the +relationship schema) describe it. + +| `type` | Label | `study_types` slug | Description | +|--------|---------------|--------------------|----------------------------------------------------------------------------------------------------------| +| `1` | BAV (Standard) | `syndicated` | The full standard BAV study with a nationally representative sample. | +| `2` | Kaleidoscope | `custom` | A bespoke BAV study tailored for a specific need such as different sample, brands or custom questions. | +| `3` | Audience Origin | - | Audience Origin covers thousands of audience insight metrics. | +| `4` | Best Countries | - | Best Countries studies the perception of countries and societal opinions across the world. | +| `5` | Momentum | - | Momentum is a Wavemaker study. | +| `6` | SnapBAV | `snap` | A smaller BAV study with a limited number of brands. | +| `7` | Consumer Eye | `custom` | An Asia-based study that provides insights into consumer behavior and preferences combined with brand perceptions. | +| `8` | AO+BAV Fused | `fused` | Links Audience Origin and BAV data to provide a comprehensive view of audience insights and brand perceptions. | + +:::note + +The standard BAV study was previously labelled "Syndicated". Its label is now "BAV (Standard)", but its slug is still +`syndicated`, so existing `study_types` filters keep working. + +::: + +## Methodologies + +Each study is run on a methodology, the version of the BAV model that decides how its metrics are calculated. Use the +`methodology` include to get it. Metrics are calculated differently between methodologies, so take care when comparing +studies that were run on different ones. + +Methodologies have a stable `key` and a display `name`. The names were changed in October 2026; the keys did not +change, so use the `key` rather than the name to tell methodologies apart. + +| `key` | Name | Previous name | +|-------------------|----------------------|---------------| +| `classic` | BAV 1 | Classic | +| `classic-v2` | BAV 1 (Known Brands) | Classic V2 | +| `concepts-2023-1` | Triads V1 | V2023.1 | +| `concepts-2023-2` | Triads V2 | V2023.2 | +| `v2025` | BAV 3 (6× Unique) | V2025.1 | +| `v2025-2` | BAV 3 (Default) | V2025.2 | +| `v2025-3` | BAV 3 (Hungary) | V2025.3 | +| `v2025-4` | BAV 3 (Known Brands) | V2025.4 | ## Schema ### Full response schema -| Key | Type | Filterable | Sortable | Configurable | Description | -|---------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|------------------------------------------------------------------| -| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | -| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the study. | -| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this study should be used. | -| `type` | object | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this is a full BAV study or a smaller study. | -| `period` | object | :white_check_mark: | :white_check_mark: | :white_check_mark: | The period for the study (Full Year, Quarter). | -| `start_date` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A datetime string when the fieldwork for this study was started. | -| `end_date` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A datetime string when the fieldwork for this study ended. | -| `data_available_at` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A datetime string when the final data was made available. | -| `respondents` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | How many individual respondents the study had. | -| `categories` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | How many categories the study had. | -| `data_updated_at` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | When the data for the study was last updated. | -| `amount_of_cells` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The total amount of cells in the study. | -| `amount_of_brands` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | How many brands the study had. | -| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this study was first created. | -| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this study was last updated. | +| Key | Type | Filterable | Sortable | Configurable | Description | +|---------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the study. | +| `bav_key` | string | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The study's BAV key. | +| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this study is active. | +| `type` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The [study type](#study-types). | +| `type_details` | object | :x: | :x: | (with `type`) | Details of the study type: `id`, `slug` (the `study_types` slug, or `null`), `label`, `description` and a `dataset` object with `key`, `label`, `acronym` and `description`. | +| `period` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The study period: `1` full year, `2` first half, `3` second half, `4` to `7` Q1 to Q4, `8` rolling full year or `9` custom. | +| `start_date` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The date when the fieldwork for this study was started. | +| `end_date` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The date when the fieldwork for this study ended. | +| `data_available_at` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The date when the final data was made available. `null` until the data is available. | +| `respondents` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | How many individual respondents the study had. | +| `categories` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | How many categories the study had. | +| `data_updated_at` | string | (`data_updated_since`) | :white_check_mark: | :white_check_mark: | When the data for the study was last updated. Unlike `updated_at`, this ignores changes to the study's details. | +| `amount_of_cells` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The total amount of brand-by-category cells in the study. | +| `amount_of_brands` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | How many brands the study had. | +| `url` | string | :x: | :x: | :x: | The URL to view the study in The Fount. Left out when `fields` omits `id`. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this study was first created. | +| `updated_at` | string | ([updated since](../customizing/filters.md)) | :white_check_mark: | :white_check_mark: | A datetime string when this study was last updated. | ### Relationship Response Schema The slim relationship schema is used when the study is used as part of an include in another resource. -| Key | Type | Description | -|-----------|---------|------------------------------------------------| -| `id` | integer | The system ID for the study. | -| `name` | string | The primary name of the study. | -| `period` | object | The period for the study (Full Year, Quarter). | -| `country` | object | The country where the study was done. | -| `year` | object | The year when the study was done. | +| Key | Type | Description | +|--------------------|---------|------------------------------------------------------------------------------------------| +| `id` | integer | The system ID for the study. | +| `name` | string | The primary name of the study. | +| `period` | integer | The study period (see above). | +| `type` | integer | The [study type](#study-types) as a number. | +| `study_type` | string | The `study_types` slug for the type, e.g. `syndicated`. `null` for types without a slug. | +| `study_type_label` | string | The study type label, e.g. `BAV (Standard)`. | +| `country` | object | The country where the study was done (when loaded). | +| `year` | object | The year when the study was done (when loaded). | + +### Methodology Schema + +The schema used for the `methodology` include. + +| Key | Type | Description | +|---------------|---------|----------------------------------------------------------------------------------------------| +| `id` | integer | The system ID for the methodology. | +| `key` | string | The stable methodology key, e.g. `v2025-2`. Use this rather than the name to tell them apart. | +| `name` | string | The methodology name, e.g. `BAV 3 (Default)`. | +| `description` | string | What the methodology is and how it differs from the other versions. | ### Brands in Study Schema @@ -80,73 +155,79 @@ When getting the brands included in a study, the following schema is used: | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | | `brand_name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The local brand name used in the study. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this relation was first created. | -| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this relation was last updated. | +| `updated_at` | string | ([updated since](../customizing/filters.md)) | :white_check_mark: | :white_check_mark: | A datetime string when this relation was last updated. | ### Categories in Study Schema When getting the categories included in a study, the following schema is used: -| Key | Type | Filterable | Sortable | Configurable | Description | -|--------------|---------|:-----------------------------------------:|:------------------:|:------------------:|---------------------------------------------------------| -| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | -| `category` | object | :x: | :x: | :x: | A category relationship object. | -| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this relation was first created. | -| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this relation was last updated. | +| Key | Type | Filterable | Sortable | Configurable | Description | +|--------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `category` | object | :x: | (`category_name`) | :x: | A [category relationship object](categories.md#relationship-response-schema). Always included. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this relation was first created. | +| `updated_at` | string | ([updated since](../customizing/filters.md)) | :white_check_mark: | :white_check_mark: | A datetime string when this relation was last updated. | ## Relationships & includes -By default, relationships apart from the sector are not included. See -the [includes section](../customizing/includes) for more information on how this works. The following relationships -are available: +By default, relationships are not included. See the [includes section](../customizing/includes.md) for more information +on how this works. The following relationships are available: -- `country` - The [country](countries.md) country where the study was done. -- `year` - The [year](years.md) year when the study was done. +- `country` - The [country](../metadata/countries.md) where the study was done. +- `year` - The [year](../metadata/years.md) when the study was done. +- `methodology` - The [methodology](#methodologies) the study was run on. ### For brands in a study The following relationships are available for brands in a study: -- `country` - The [country](countries.md) country where the study was done. -- `year` - The [year](years.md) year when the study was done. +- `country` - The [country](../metadata/countries.md) where the study was done. +- `year` - The [year](../metadata/years.md) when the study was done. - `study` - The [study](studies.md) that the brand was included in. -- `brand` - The [brand](brands.md) object for each brand. +- `brand` - The [brand](../brands/brands.md) object for each brand. +- `brandVariation` - The brand variation (the name) the brand was measured under in this study. - `category` - The [category](categories.md) the brand was studied in. -- `category.sector` - Includes the [sector](sectors.md) the category belongs to, nested on the categories relationship object. +- `category.sector` - Includes the [sector](../metadata/sectors.md) the category belongs to, nested on the category + relationship object. ### For categories in a study -The following relationships are available for categories in a study: +The category is always included. The following additional relationships are available for categories in a study: -- `country` - The [country](countries.md) country where the study was done. -- `year` - The [year](years.md) year when the study was done. -- `study` - The [study](studies.md) that the brand was included in. -- `brand` - The [brand](brands.md) object for each brand. -- `category` - The [category](categories.md) the brand was studied in. +- `country` - The [country](../metadata/countries.md) where the study was done. +- `year` - The [year](../metadata/years.md) when the study was done. +- `study` - The [study](studies.md) that the category was included in. ## Additional filters -For convenience, we have a set of additional filters for brands that are not available in +For convenience, we have a set of additional filters for studies that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: -- `data_updated_since` - A datetime string. This will filter the studies to only those that have had their data updated - since the given date. -- `active` - Set to `1` to only return active audiences. -- `inactive` - Set to `1` to only return inactive audiences. -- `bav_study` - Set to `1` to only return studies that are full BAV studies. +- `study_types` - A comma-separated list of study type slugs: `syndicated` (BAV Standard), `custom` (Kaleidoscope and + Consumer Eye), `snap` (SnapBAV) or `fused` (AO+BAV Fused). Unknown slugs are ignored. Use the `type` filter to filter + by type number instead. +- `data_updated_since` - A date string. This will filter the studies to only those that have had their data updated + since the given date. Unlike `updated_since`, this ignores changes to the study's details. +- `active` - Set to `1` to only return active studies. +- `inactive` - Set to `1` to only return inactive studies. +- `bav_study` - Set to `1` to only return BAV studies (type `1`). - `released` - Set to `1` to only return studies that have been released. -- `unreleased` - Set to `1` to only return studies that have not been released. -- `full_year` - Set to `1` to only return studies that are full year studies (excludes US quarterly waves). -- `open_survey` - Set to `1` to only return studies that are open to brand list feedback. +- `unreleased` - Set to `1` to only return active studies that have not been released yet. +- `full_year` - Set to `1` to only return full year studies (period `1`, excludes US quarterly waves). +- `open_survey` - Set to `1` to only return studies with an open brand selection survey. - `regions` - A comma-separated list of region IDs. This will filter the studies to only those that are in the given regions. - `countries` - A comma-separated list of country IDs. This will filter the studies to only those that are in the given countries. -- `country_codes` - A comma-separated list of country codes. This will filter the studies to only those that are in the - given countries. +- `country_codes` - A comma-separated list of two-letter ISO country codes. This will filter the studies to only those + that are in the given countries. - `years` - A comma-separated list of year IDs. This will filter the studies to only those that are in the given years. - `year_numbers` - A comma-separated list of year numbers. This will filter the studies to only those that are in the given years. +For the scope filters (`active`, `inactive`, `bav_study`, `released`, `unreleased`, `full_year` and `open_survey`), any +value turns the filter on. + ### For brands in a study The following additional filters are available when fetching brands for a given study: @@ -154,6 +235,8 @@ The following additional filters are available when fetching brands for a given - `categories` - A comma-separated list of category IDs. This will filter the brands to only those that are studied in the specified categories. - `brands` - A comma-separated list of brand IDs. This will filter the brands to only the ones provided. +- `brandVariations` - A comma-separated list of brand variation IDs. This will filter the brands to only those measured + under the given variations. ### For categories in a study @@ -162,7 +245,17 @@ The following additional filters are available when fetching categories for a gi - `categories` - A comma-separated list of category IDs. This will filter the categories to only those given. - `brands` - A comma-separated list of brand IDs. This will filter the categories to only those that have the given brands in the study. +- `brand_variations` - A comma-separated list of brand variation IDs. This will filter the categories to only those + that have the given brand variations in the study. + +:::caution Filter naming + +The brand variation filter is named differently on the two endpoints: it is `filter[brandVariations]` (camelCase) on +`/studies/{id}/brands` and `filter[brand_variations]` (snake_case) on `/studies/{id}/categories`. Likewise, the include +for the brand variation on `/studies/{id}/brands` is `brandVariation`. + +::: ## Searching -This endpoint supports searching. See the [searching section](../customizing/searching) for more details. \ No newline at end of file +The studies list endpoint supports searching. See the [searching section](../customizing/searching.md) for more details. diff --git a/docs/versioning.md b/docs/versioning.md index 2517a21..3433f85 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -8,7 +8,7 @@ The current API version is: `2`. The version is part of the API URL: `/api/v2/RESOURCE`. :::caution Actively supported versions -Please not that we only actively support the current major version of the API. While we don't actively break an older +Please note that we only actively support the current major version of the API. While we don't actively break an older version, we suggest that you update to the latest version if you are using an older version. We try and make upgrades as easy as possible. ::: @@ -23,5 +23,5 @@ At a high-level, these are the changes that will affect you: - There are no removed resources but several new ones. - Some fields have been given new names, a select few have been removed. - Filtering now has a new, consistent format (see [filtering](customizing/filters.md)). -- Sorting now has a new, simplified format (see [sorting](customizing/filters.md)). +- Sorting now has a new, simplified format (see [sorting](customizing/filters.md#sorting-results)). - Expansions are now includes (see [includes](customizing/includes.md)). diff --git a/docs/webhooks.md b/docs/webhooks.md index 8a3245b..75b71b4 100644 --- a/docs/webhooks.md +++ b/docs/webhooks.md @@ -7,40 +7,52 @@ Webhooks allow you to receive HTTP push notifications for data changes in BAV. T integrations on top of BAV. You could, for example, use it to react in realtime to new data being available or make audiences seamlessly available in your own systems. -Our webhooks belong to the global platform. You can configure webhooks provide events based on all users and operating -companies or specific users and/or operating companies. For example, you may only want to listen to new audiences -created by users within GroupM. +Our webhooks belong to the global platform. You can configure webhooks to provide events based on all users and +operating companies or specific users and/or operating companies. For example, you may only want to listen to new +audiences created by users within GroupM. Filtering on users and operating companies applies to the audience and +collection events. Other events are always sent for all changes. -The webhooks come in two categories "data change webhooks" and other events. The data change webhooks are triggered -when data changes in BAV. The other events are triggered when other events occur in BAV. +## Events -The data change webhooks are currently supported for the following objects: +When a webhook is set up, it is subscribed to one or more events. The data change events are triggered when data is +created, updated or deleted in BAV: -- `Audiences` -- `Brands` -- `Brand Metrics` -- `Collections` -- `Studies` +| Event | `type` in the payload | Description | +|------------------------------|-----------------------|---------------------------------------------------------------------------------------| +| `audiences_data_change` | `Audience` | An [audience](audiences/audiences.md) was created, updated or deleted. | +| `brands_data_change` | `Brand` | A [brand](brands/brands.md) was created, updated or deleted. | +| `brand_metrics_data_change` | `BrandMetric` | A [brand metric](metrics/metrics.md) was created, updated or deleted. | +| `collections_data_change` | `Collection` | A [collection](brands/collections.md) was created, updated or deleted. | +| `studies_data_change` | `Study` | A [study](studies/studies.md) was created, updated or deleted. | -The other events are currently supported for the following events: +The following events can also be added to a webhook, but are not currently being sent: -- `Audience Export` - [Documentation](#) +| Event | Description | +|---------------------------------------|------------------------------------------------| +| `audience_origin_metrics_data_change` | An Audience Origin metric was changed. | +| `tools_data_change` | A tool was changed. | +| `tool_queries_data_change` | A tool query was changed. | +| `audience_export_italy_creator` | An audience was exported to Italy Creator. | ## How does a webhook work? -A webhook is simple a HTTP POST request to a URL you specify. The request is automatically triggered by BAV when data +A webhook is simply a HTTP POST request to a URL you specify. The request is automatically triggered by BAV when data updates or the event occurs. The request contains a [JSON payload](#the-webhook-payload) with the data that has changed or the event that has occurred. To receive data from the webhook all you need is a simple HTTP endpoint that: -- Is available on a publicly accessible HTTPS, non-localhost URL. -- Responds with a `HTTP 200` status code to the Webhook POST request. +- Is available on a publicly accessible HTTPS, non-localhost URL with a valid SSL certificate. +- Responds with a `2xx` status code (for example `HTTP 200`) to the webhook POST request within 5 seconds. -If your endpoint does not respond with a `HTTP 200` status code the request will be retried a few times. We use an -exponential backoff delay between retried. This means that for each retry the delay between retries will be longer. If -your endpoint continues to fail to respond it will be automatically disabled. You'll receive a notification when this -occurs. It must then be manually re-enabled when the issue has been fixed. +If your endpoint does not respond with a `2xx` status code within 5 seconds, the request will be retried. Each webhook +call is attempted up to 10 times in total. We use an exponential backoff delay between retries, which means that the +delay gets longer for each retry: 10 seconds after the first attempt, then 100 seconds, 1,000 seconds (about 17 +minutes), 10,000 seconds (about 2.8 hours) and then 100,000 seconds (about 28 hours) between each of the remaining +attempts. + +If all attempts fail, the webhook will be automatically disabled and the webhook's contacts will receive an email +notification. It must then be manually re-enabled when the issue has been fixed. ## Getting started @@ -49,7 +61,7 @@ Implementing webhooks is simpler than you might think. In summary, you'll need t - Create a receiving endpoint for the webhook. - Verify the authenticity of the webhook request by validating the signature in the request. - Parse the JSON payload in the request to get the data that has changed or the event that has occurred and process it. -- Respond to the request with a `HTTP 200` status code. +- Respond to the request with a `2xx` status code (for example `HTTP 200`). As some events are triggered by BAV it can be useful to use the sample payloads provided in the documentation to use as test data. This will allow you to test your endpoint without having to wait for the event to occur in BAV. @@ -97,17 +109,17 @@ The custom headers sent by BAV are: | Name | Description | |-----------------|----------------------------------------------------| | `BAV-Delivery` | A UUID (v4) that uniquely identifies this payload. | -| `BAV-Event` | The resource type that triggered this event. | +| `BAV-Event` | The resource type that triggered this event. This is the same as the `type` field in the body. | | `BAV-Signature` | The HMAC signature of the webhook payload. | The payload is sent with the following body: | Field | Description | |--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| `action` | The type of action that took place. This is only available for data change events and is otherwise not present. One of: `create`, `update`, `delete` | +| `action` | The type of action that took place. For data change events, one of: `created`, `updated`, `deleted`. | | `data` | The data for the object in the same format as the object's full response schema. You can find this in the documentation for each endpoint. | -| `type` | The type of resource that was targeted. | -| `url` | The URL to the object's page on The Fount. | +| `type` | The type of resource that was targeted, for example `Brand`. See [events](#events). | +| `url` | The URL to the object's page on The Fount, when it has one. Otherwise `null`. | | `webhookDate` | The date of the event in ISO 8601 format. | | `webhookTimestamp` | The date of the event in Unix timestamp format. | | `webhookId` | A UUID (v4) that uniquely identifies this payload. | @@ -116,7 +128,7 @@ For example: ```json { - "action": "create", + "action": "created", "data": { "id": 1, "name": "BAV@WPP" @@ -124,8 +136,8 @@ For example: }, "type": "Brand", "url": "https://fount.wppbav.com/brands/1", - "webhookDate": "2024-01-01T00:00:00Z", - "webhookTimestamp": 1672531200, + "webhookDate": "2024-01-01T00:00:00+00:00", + "webhookTimestamp": 1704067200, "webhookId": "7efba5b3-f551-4862-ad1e-2667d09a40bb" } ``` From 83b29519591a0ad218c6933f54dac09018a4fd29 Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Fri, 23 Oct 2026 23:18:55 +0200 Subject: [PATCH 03/23] Document new REST API endpoints Add pages for Market Share, brandscape models, Audience Origin, managing audiences, measures and questions, brand tags and variations, country indicators and the remaining Best Countries endpoints. Co-Authored-By: Claude Opus 5.5 --- docs/audience-origin/frequencies.md | 62 +++ docs/audience-origin/index.md | 33 ++ docs/audience-origin/metric-groups.md | 70 +++ docs/audience-origin/metrics.md | 101 +++++ docs/audience-origin/query.md | 137 ++++++ docs/audience-origin/touchpoints.md | 62 +++ docs/audiences/managing-audiences.md | 400 ++++++++++++++++++ docs/best-countries/factors.md | 66 ++- docs/best-countries/metric-groups.md | 70 ++- docs/best-countries/models.md | 190 +++++++++ docs/best-countries/raw-data.md | 65 +++ docs/brands/brand-tags.md | 83 ++++ docs/brands/brand-variations.md | 93 ++++ .../agency-change-predictor.md | 127 ++++++ docs/brandscape-models/brand-worth.md | 37 ++ docs/brandscape-models/imagery.md | 39 ++ docs/brandscape-models/index.md | 249 +++++++++++ docs/brandscape-models/influence.md | 32 ++ docs/brandscape-models/personality.md | 36 ++ docs/brandscape-models/pillars.md | 48 +++ docs/brandscape-models/powergrid.md | 62 +++ docs/brandscape-models/preferences.md | 43 ++ docs/brandscape-models/recommendation.md | 36 ++ docs/brandscape-models/super-cx.md | 93 ++++ docs/brandscape-models/usage.md | 43 ++ docs/market-share/brand-shares.md | 149 +++++++ docs/market-share/catalog.md | 209 +++++++++ docs/market-share/company-shares.md | 92 ++++ docs/market-share/index.md | 88 ++++ docs/measures/bav-question-groups.md | 67 +++ docs/measures/bav-questions.md | 93 ++++ docs/measures/brand-measure-groups.md | 65 +++ docs/measures/brand-measures.md | 98 +++++ docs/measures/index.md | 29 ++ docs/measures/study-catalog.md | 161 +++++++ docs/metadata/country-indicators.md | 110 +++++ sidebars.js | 64 ++- 37 files changed, 3499 insertions(+), 3 deletions(-) create mode 100644 docs/audience-origin/frequencies.md create mode 100644 docs/audience-origin/index.md create mode 100644 docs/audience-origin/metric-groups.md create mode 100644 docs/audience-origin/metrics.md create mode 100644 docs/audience-origin/query.md create mode 100644 docs/audience-origin/touchpoints.md create mode 100644 docs/audiences/managing-audiences.md create mode 100644 docs/best-countries/models.md create mode 100644 docs/best-countries/raw-data.md create mode 100644 docs/brands/brand-tags.md create mode 100644 docs/brands/brand-variations.md create mode 100644 docs/brandscape-models/agency-change-predictor.md create mode 100644 docs/brandscape-models/brand-worth.md create mode 100644 docs/brandscape-models/imagery.md create mode 100644 docs/brandscape-models/index.md create mode 100644 docs/brandscape-models/influence.md create mode 100644 docs/brandscape-models/personality.md create mode 100644 docs/brandscape-models/pillars.md create mode 100644 docs/brandscape-models/powergrid.md create mode 100644 docs/brandscape-models/preferences.md create mode 100644 docs/brandscape-models/recommendation.md create mode 100644 docs/brandscape-models/super-cx.md create mode 100644 docs/brandscape-models/usage.md create mode 100644 docs/market-share/brand-shares.md create mode 100644 docs/market-share/catalog.md create mode 100644 docs/market-share/company-shares.md create mode 100644 docs/market-share/index.md create mode 100644 docs/measures/bav-question-groups.md create mode 100644 docs/measures/bav-questions.md create mode 100644 docs/measures/brand-measure-groups.md create mode 100644 docs/measures/brand-measures.md create mode 100644 docs/measures/index.md create mode 100644 docs/measures/study-catalog.md create mode 100644 docs/metadata/country-indicators.md diff --git a/docs/audience-origin/frequencies.md b/docs/audience-origin/frequencies.md new file mode 100644 index 0000000..ae8a3d1 --- /dev/null +++ b/docs/audience-origin/frequencies.md @@ -0,0 +1,62 @@ +# Audience Origin Frequencies + +## What are frequencies? + +Some [Audience Origin metrics](metrics.md) measure a frequency, that is how often something happens. A metric that +measures a frequency is linked to it, which lets you find all the metrics for a given frequency, either with the +`metrics` include here or with the `frequency_id` filter on the metrics endpoint. + +## List all frequencies + +To list all of the frequencies and browse them via the API, use the list endpoint: + +```http request +GET /api/v2/audience-origin/frequencies +``` + +## Get a frequency + +You may also directly retrieve a frequency's details if you already have its system ID. + +```http request +GET /api/v2/audience-origin/frequencies/123 +``` + +Where `123` is the system ID of the frequency. + +## Schema + +### Full response schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|--------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-----------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the frequency. | +| `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The key of the frequency. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this frequency was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this frequency was last updated. | + +### Relationship Response Schema + +The slim relationship schema is used when the frequency is used as part of an include in another resource. + +| Key | Type | Description | +|--------|---------|-----------------------------------| +| `id` | integer | The system ID for the frequency. | +| `name` | string | The name of the frequency. | +| `key` | string | The key of the frequency. | + +## Additional Filters + +For convenience, we have a set of additional filters that are not available in +the [default filters](../customizing/filters.md) or are part of the columns. These are: + +- `has_metrics` - Set to `1` to only return frequencies that are used by at least one metric. + +## Relationships & includes + +By default, relationships are not included. See +the [includes section](../customizing/includes) for more information on how this works. The following relationships +are available: + +- `metrics` - The [metrics](metrics.md) that measure this frequency. diff --git a/docs/audience-origin/index.md b/docs/audience-origin/index.md new file mode 100644 index 0000000..b17eb2e --- /dev/null +++ b/docs/audience-origin/index.md @@ -0,0 +1,33 @@ +--- +sidebar_label: Overview +--- + +# Audience Origin + +Audience Origin is WPP's global study of people's media consumption, attitudes and behaviors. It contains demographic, +psychographic and behavioral data on people from around the world. + +The Audience Origin API is made up of two parts: + +- **The catalog.** The [metrics](metrics.md) that are measured, the [metric groups](metric-groups.md) they are + organized in, and the [touchpoints](touchpoints.md) and [frequencies](frequencies.md) that media metrics measure. Use + these to find out what you can ask for. +- **The data.** The [query endpoint](query.md) returns the Audience Origin data for a set of metrics in one or more + studies, for an [audience](../audiences/audiences.md). + +Audience Origin studies are [studies](../studies/studies.md) like any other, with their own study type. Use the studies +endpoint to find the Audience Origin studies you have access to. + +## Access + +All Audience Origin endpoints require the `bav:audience-origin-data` scope (shown as **Audience Origin Data** when you +create your API key). Your user also needs access to Audience Origin data in The Fount. + +:::note Access is granted separately +The Audience Origin Data scope can only be added to an API key if your user has access to Audience Origin data. +::: + +## Building audiences from Audience Origin + +Audience Origin metrics can be used as conditions when [building your own audiences](../audiences/managing-audiences.md). +Use the `audience-origins-metric` metric type together with the ID of the metric. diff --git a/docs/audience-origin/metric-groups.md b/docs/audience-origin/metric-groups.md new file mode 100644 index 0000000..10bce75 --- /dev/null +++ b/docs/audience-origin/metric-groups.md @@ -0,0 +1,70 @@ +# Audience Origin Metric Groups + +## What are Audience Origin metric groups? + +[Audience Origin metrics](metrics.md) are organized in metric groups, such as a group for media usage or for +attitudes. Groups nest one level deep: a top-level group can have child groups, and metrics belong to a group. + +The `key` of a group can be used in the [query endpoint](query.md) to get the data for every metric in the group. + +## List all Audience Origin metric groups + +To list all of the metric groups and browse them via the API, use the list endpoint: + +```http request +GET /api/v2/audience-origin/metric-groups +``` + +## Get an Audience Origin metric group + +You may also directly retrieve a metric group's details if you already have its system ID. + +```http request +GET /api/v2/audience-origin/metric-groups/123 +``` + +Where `123` is the system ID of the metric group. + +## Schema + +### Full response schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|---------------|---------|:-----------------------------------------:|:------------------:|:------------------:|--------------------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the metric group. | +| `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The key of the metric group. This is the key the [query endpoint](query.md) accepts in `metric_group_keys`. | +| `description` | string | :x: | :x: | :white_check_mark: | A description of the metric group. | +| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric group is active. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this metric group was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this metric group was last updated. | + +### Relationship Response Schema + +The slim relationship schema is used when the metric group is used as part of an include in another resource. + +| Key | Type | Description | +|-------------|---------|-----------------------------------------------------------------------------| +| `id` | integer | The system ID for the metric group. | +| `name` | string | The name of the metric group. | +| `key` | string | The key of the metric group. | +| `is_parent` | boolean | Whether this is a top-level metric group. | +| `parent` | object | The parent metric group, when it has been included. | + +## Additional Filters + +For convenience, we have a set of additional filters that are not available in +the [default filters](../customizing/filters.md) or are part of the columns. These are: + +- `only_parents` - Set to `1` to only return top-level groups. +- `only_children` - Set to `1` to only return groups nested under a parent. + +## Relationships & includes + +By default, relationships are not included. See +the [includes section](../customizing/includes) for more information on how this works. The following relationships +are available on the list endpoint: + +- `metrics` - The [metrics](metrics.md) in the metric group. +- `parent` - The parent metric group, if this group is nested. +- `children` - The metric groups nested under this one. diff --git a/docs/audience-origin/metrics.md b/docs/audience-origin/metrics.md new file mode 100644 index 0000000..bdc4bc2 --- /dev/null +++ b/docs/audience-origin/metrics.md @@ -0,0 +1,101 @@ +# Audience Origin Metrics + +## What are Audience Origin metrics? + +Audience Origin metrics are the questions and variables in the [Audience Origin](index.md) dataset. Each metric +belongs to a [metric group](metric-groups.md). Media metrics can also measure a [touchpoint](touchpoints.md) and +a [frequency](frequencies.md). + +The `key` of a metric is what you use to ask for its data in the [query endpoint](query.md). + +Not every metric is available in every study. Use the `for_studies` filter or the `studies` include to see where a +metric is available. + +## List all Audience Origin metrics + +To list all of the Audience Origin metrics and browse them via the API, use the list endpoint: + +```http request +GET /api/v2/audience-origin/metrics +``` + +## Get an Audience Origin metric + +You may also directly retrieve a metric's details if you already have its system ID. + +```http request +GET /api/v2/audience-origin/metrics/123 +``` + +Where `123` is the system ID of the metric. + +## Schema + +### Full response schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|---------------|---------|:-----------------------------------------:|:------------------:|:------------------:|---------------------------------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the metric. | +| `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The key of the metric. This is the key the [query endpoint](query.md) accepts in `metric_keys`. | +| `variable` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The Audience Origin questionnaire variable. | +| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric is active. | +| `is_public` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric is available to all users rather than restricted. | +| `type` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The type of the metric, such as `dictionary`, `boolean`, `integer` or `decimal`. | +| `is_ascribed` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric is ascribed: created with data science after fieldwork rather than asked in the questionnaire. | +| `is_core` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric is part of the core Audience Origin questionnaire. | +| `is_plus` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric is in the Audience Origin Plus set. | +| `is_tools` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric is in the Audience Origin tools set. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this metric was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this metric was last updated. | + +### Relationship Response Schema + +The slim relationship schema is used when the metric is used as part of an include in another resource. + +| Key | Type | Description | +|-------------|---------|-------------------------------------------------------------------------------------| +| `id` | integer | The system ID for the metric. | +| `name` | string | The name of the metric. | +| `key` | string | The key of the metric. | +| `variable` | string | The Audience Origin questionnaire variable. | +| `is_active` | boolean | Whether the metric is active. | +| `is_public` | boolean | Whether the metric is available to all users rather than restricted. | +| `type` | string | The type of the metric, such as `dictionary`, `boolean` or `integer`. | + +### Answer options + +The `options` include returns the answer options for the metric. Option sets can differ between studies, so the same +value can mean different things in two studies. + +| Key | Type | Description | +|------------|---------|--------------------------------------------------------------------------------------| +| `id` | integer | The system ID for the option. | +| `value` | mixed | The stored value. This is what appears in the data. | +| `label` | string | What the value means, for example "Strongly agree". | +| `study_id` | integer | The ID of the study this option applies to. Null if it applies to all studies. | + +## Additional Filters + +For convenience, we have a set of additional filters that are not available in +the [default filters](../customizing/filters.md) or are part of the columns. These are: + +- `touchpoint_id` - The ID of a [touchpoint](touchpoints.md) to filter by. +- `frequency_id` - The ID of a [frequency](frequencies.md) to filter by. +- `for_studies` - A comma-separated list of study IDs. Only metrics available in these studies are returned. +- `has_touchpoint` - Set to `1` to only return metrics with a touchpoint. +- `has_frequency` - Set to `1` to only return metrics with a frequency. +- `has_studies` - Set to `1` to only return metrics that are available in at least one study. + +## Relationships & includes + +By default, relationships are not included. See +the [includes section](../customizing/includes) for more information on how this works. The following relationships +are available: + +- `group` - The [metric group](metric-groups.md) that the metric belongs to. +- `group.parent` - The parent of the metric group. +- `touchpoint` - The [touchpoint](touchpoints.md) the metric measures, if any. +- `frequency` - The [frequency](frequencies.md) the metric measures, if any. +- `studies` - The [studies](../studies/studies.md) the metric is available in. +- `options` - The answer options for the metric. diff --git a/docs/audience-origin/query.md b/docs/audience-origin/query.md new file mode 100644 index 0000000..ac35163 --- /dev/null +++ b/docs/audience-origin/query.md @@ -0,0 +1,137 @@ +--- +sidebar_label: Query Data +--- + +# Querying Audience Origin Data + +The query endpoint returns Audience Origin data for a set of [metrics](metrics.md) in one or more Audience Origin +studies. The data is returned for an [audience](../audiences/audiences.md), which defaults to All Adults. + +## Creating a query + +The query is sent as a `POST` request with a JSON body: + +```http request +POST /api/v2/audience-origin/query +``` + +```json +{ + "filter": { + "studies": [701], + "metric_keys": ["gender"], + "audience": 1 + } +} +``` + +You choose which metrics to get data for with `metrics`, `metric_keys`, `metric_group_keys` or `metric_group_ids`. You +can combine these, and a group returns every metric in it. + +### Parameters + +All parameters are passed inside the `filter` object. + +| Key | Type | Required | Description | +|---------------------|---------|:------------------:|--------------------------------------------------------------------------------------------------------------------------------------| +| `studies` | array | :white_check_mark: | The IDs of the Audience Origin [studies](../studies/studies.md) to read from. Only active Audience Origin studies you have access to are accepted. | +| `metrics` | array | :x: | The IDs of the [metrics](metrics.md) to return. | +| `metric_keys` | array | :x: | The keys of the [metrics](metrics.md) to return. | +| `metric_group_keys` | array | :x: | The keys of [metric groups](metric-groups.md) to return every metric from. | +| `metric_group_ids` | array | :x: | The IDs of [metric groups](metric-groups.md) to return every metric from. | +| `quarters` | array | :x: | The quarters of the year to include, as numbers from `1` to `4`. All quarters are included by default. | +| `audience` | integer | :x: | The ID of the [audience](../audiences/audiences.md) to get the data for. Defaults to All Adults (`1`). | + +If any of the parameters are invalid, for example a study that is not an Audience Origin study or a metric key that +does not exist, the endpoint returns the status code `422` with the validation errors. + +## Schema + +The response contains a `data` array with one data point per study. Each data point contains a few metadata fields and +a `metrics` object with the data for each metric. + +```json +{ + "data": [ + { + "study": "United Kingdom 2025", + "study_id": 701, + "year": "2025", + "year_id": 45, + "country": "United Kingdom", + "country_id": 77, + "quarter": null, + "audience_id": 1, + "audience": "All Adults", + "metrics": { + "gender": { + "id": 1520, + "key": "gender", + "name": "Gender", + "label": "Gender", + "type": "dictionary", + "values": { + "1": { + "value": 1, + "label": "Male", + "score": 48.7, + "full_label": "Gender: Male" + }, + "2": { + "value": 2, + "label": "Female", + "score": 51.3, + "full_label": "Gender: Female" + } + }, + "dictionary": { + "1": "Male", + "2": "Female" + }, + "primaryGroup": "Demographics", + "secondaryGroup": "Gender" + } + } + } + ] +} +``` + +### Data point + +| Key | Type | Description | +|---------------|---------|------------------------------------------------------------------------| +| `study` | string | The name of the study. | +| `study_id` | integer | The system ID of the study. | +| `year` | string | The year of the study. | +| `year_id` | integer | The system ID of the year. | +| `country` | string | The name of the country (market) of the study. | +| `country_id` | integer | The system ID of the country. | +| `quarter` | integer | The quarter of the data point, when it applies. Otherwise null. | +| `audience_id` | integer | The system ID of the audience the data is for. | +| `audience` | string | The name of the audience the data is for. | +| `metrics` | object | The data for each metric, keyed by the metric `key`. See below. | + +### Metric data + +| Key | Type | Description | +|------------------|---------|---------------------------------------------------------------------------------------------------------------| +| `id` | integer | The system ID of the [metric](metrics.md). | +| `key` | string | The key of the metric. | +| `name` | string | The name of the metric. | +| `label` | string | The label of the metric. Falls back to the name. | +| `type` | string | The type of the metric, such as `dictionary`, `boolean`, `integer` or `decimal`. | +| `values` | object | The scores for the metric, keyed by value. See below. | +| `dictionary` | object | The answer options for the metric, as a map of values to labels. | +| `primaryGroup` | string | The name of the parent [metric group](metric-groups.md), if any. | +| `secondaryGroup` | string | The name of the metric group the metric belongs to, if any. | + +How `values` is built depends on the type of the metric: + +- **Dictionary and integer metrics.** One entry per value, with the `value`, its `label`, the `score` and a + `full_label` that combines the metric label and the value label. The score is the weighted percentage of respondents + who gave that answer. +- **Decimal metrics.** A single `average` entry with the weighted average as the `score`. +- **Boolean metrics.** A plain map with the weighted percentage of respondents for `1` (yes) and `0` (no). + +All scores are weighted. diff --git a/docs/audience-origin/touchpoints.md b/docs/audience-origin/touchpoints.md new file mode 100644 index 0000000..5140661 --- /dev/null +++ b/docs/audience-origin/touchpoints.md @@ -0,0 +1,62 @@ +# Audience Origin Touchpoints + +## What are touchpoints? + +Some [Audience Origin metrics](metrics.md) measure a touchpoint. A metric that measures a touchpoint is linked to it, +which lets you find all the metrics for a given touchpoint, either with the `metrics` include here or with the +`touchpoint_id` filter on the metrics endpoint. + +## List all touchpoints + +To list all of the touchpoints and browse them via the API, use the list endpoint: + +```http request +GET /api/v2/audience-origin/touchpoints +``` + +## Get a touchpoint + +You may also directly retrieve a touchpoint's details if you already have its system ID. + +```http request +GET /api/v2/audience-origin/touchpoints/123 +``` + +Where `123` is the system ID of the touchpoint. + +## Schema + +### Full response schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|--------------|---------|:-----------------------------------------:|:------------------:|:------------------:|------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the touchpoint. | +| `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The key of the touchpoint. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this touchpoint was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this touchpoint was last updated. | + +### Relationship Response Schema + +The slim relationship schema is used when the touchpoint is used as part of an include in another resource. + +| Key | Type | Description | +|--------|---------|------------------------------------| +| `id` | integer | The system ID for the touchpoint. | +| `name` | string | The name of the touchpoint. | +| `key` | string | The key of the touchpoint. | + +## Additional Filters + +For convenience, we have a set of additional filters that are not available in +the [default filters](../customizing/filters.md) or are part of the columns. These are: + +- `has_metrics` - Set to `1` to only return touchpoints that are used by at least one metric. + +## Relationships & includes + +By default, relationships are not included. See +the [includes section](../customizing/includes) for more information on how this works. The following relationships +are available: + +- `metrics` - The [metrics](metrics.md) that measure this touchpoint. diff --git a/docs/audiences/managing-audiences.md b/docs/audiences/managing-audiences.md new file mode 100644 index 0000000..1db50f3 --- /dev/null +++ b/docs/audiences/managing-audiences.md @@ -0,0 +1,400 @@ +--- +sidebar_label: Managing Audiences +--- + +# Managing Audiences + +In addition to reading [audiences](audiences.md), you may create your own audiences through the API, define who is +part of them and deploy them so that their data becomes available. + +## How audiences are built + +An audience is made up of a few layers: + +- **Audience.** The audience itself with its name, description and visibility. +- **Definitions.** An audience has one or more definitions. Each definition reads from a dataset (`bav` or + `audience-origin`) and uses the questions of a base study. A definition can also be limited to a specific country or + study. A definition that is not limited applies to all of the audience's data. +- **Segments.** Each definition contains segments. A segment is a group of conditions that a respondent has to meet. + The `within_segment_operator` decides how the conditions inside the segment combine (`AND` requires all of them, `OR` + requires any of them). The `between_segments_operator` decides how the segment combines with the segment before it. + Segments are combined in their `sort_order`. +- **Segment metrics.** Each segment contains metrics. A segment metric points to an + [Audience Origin metric](../audience-origin/metrics.md), a [BAV brand measure](../measures/brand-measures.md) or a + [BAV question](../measures/bav-questions.md) and the values a respondent must have given. + +A new audience has no data. Once the definition is in place, you [deploy](#deploy-an-audience) the audience. The data +is built in the background and shows up in the data endpoints shortly after. Whenever you change the definition of an +audience, you need to deploy it again for the change to show in its data. + +You can see whether an audience needs to be deployed again by comparing `definitions_updated_at` with `deployed_at` on +the [audience](audiences.md). If `definitions_updated_at` is later, the audience has changed since it was last deployed. + +## Access + +Reading audiences, segments and segment metrics uses the `bav:shared-resources` scope like the rest of +the [Audiences](audiences.md) endpoints. + +Creating, updating, deleting and deploying audiences requires the `bav:audiences:write` scope (shown as **Build +Audiences** when you create your API key). Your user also needs the permission to build audiences in The Fount. + +In addition to the scope, regular audience permissions apply: + +- You may only update an audience that you own, that has been shared with you with edit rights, or if you have access + to manage all audiences. +- You may only delete audiences that you own. + +## Create an audience + +To create an audience, send a `POST` request to the audiences endpoint: + +```http request +POST /api/v2/audiences +``` + +You may create an empty audience with just a name, or create the whole audience with its definitions, segments and +metrics in one call. Definitions can only be created as part of this request. + +```json +{ + "name": "Frequent Flyers", + "description": "People who fly at least once a month.", + "is_active": true, + "is_public": false, + "definitions": [ + { + "dataset": "bav", + "base_study_id": 635, + "definitionable_type": "study", + "definitionable_id": 635, + "segments": [ + { + "name": "Flyers", + "sort_order": 0, + "within_segment_operator": "AND", + "between_segments_operator": "OR", + "metrics": [ + { + "metric_type": "bav-study-question", + "metric_id": 12, + "operator": "is", + "values": ["1"] + } + ] + } + ] + } + ] +} +``` + +The response has the status code `201` and contains the created [audience](audiences.md), with its definitions, +segments and metrics included. + +### Request body + +| Key | Type | Required | Description | +|---------------|---------|:--------:|---------------------------------------------------------------------------------------------------------------------| +| `name` | string | :x: | The name of the audience. Maximum 255 characters. | +| `description` | string | :x: | A description of the audience. | +| `is_active` | boolean | :x: | Whether the audience should be active. | +| `is_public` | boolean | :x: | Whether the audience is available to all users (true) or just you and the users you share it with (false). | +| `group_id` | integer | :x: | The ID of the [audience group](audience-groups.md) to put the audience in. | +| `user_id` | integer | :x: | The ID of the user who owns the audience. Only your own user ID is accepted. If omitted, you become the owner. | +| `definitions` | array | :x: | The audience's definitions. See below. Only used when creating an audience. | + +Each definition in `definitions` accepts: + +| Key | Type | Required | Description | +|-----------------------|---------|:------------------:|-------------------------------------------------------------------------------------------------------------------------------------| +| `dataset` | string | :white_check_mark: | The dataset the definition reads from. One of `bav`, `audience-origin`, `best-countries` or `momentum`. | +| `base_study_id` | integer | :white_check_mark: | The ID of the [study](../studies/studies.md) whose questions the definition uses. | +| `definitionable_type` | string | :x: | What the definition is limited to: `country` or `study`. Leave empty for a definition that applies to all of the audience's data. | +| `definitionable_id` | integer | :x: | The ID of the country or study the definition is limited to. | +| `segments` | array | :x: | The segments in the definition. Each segment accepts the same fields as when [creating a segment](#create-a-segment), apart from `definition_id`. | + +### Validation + +Validation errors are returned with the status code `422` and follow the +standard [error format](../errors.md). In particular: + +- `definitions.*.dataset` and `definitions.*.base_study_id` are required for each definition. +- `within_segment_operator` and `between_segments_operator` must be `AND` or `OR`. +- `metric_type` and `metric_id` are required for each segment metric. +- `brands` may not be set on an Audience Origin metric. + +## Update an audience + +You may update an audience's name, description, visibility, group or owner with a `PUT` or `PATCH` request: + +```http request +PUT /api/v2/audiences/123 +``` + +Where `123` is the system ID of the audience. + +The request accepts the same top-level fields as when creating an audience (`name`, `description`, `is_active`, +`is_public`, `group_id` and `user_id`). Only the fields you send are changed. The definitions of the audience are not +changed by this endpoint. Use the [segment](#segments) and [segment metric](#segment-metrics) endpoints to change who is +part of the audience. + +The response contains the updated [audience](audiences.md), with its definitions, segments, metrics, user and group +included. + +## Delete an audience + +To delete an audience, send a `DELETE` request: + +```http request +DELETE /api/v2/audiences/123 +``` + +Where `123` is the system ID of the audience. + +The response contains the [audience](audiences.md) that was deleted. + +## Segments + +Segments live inside one of the audience's definitions. To find the definitions of an audience and their IDs, get the +audience with the `definitions` include: + +```http request +GET /api/v2/audiences/123?include=definitions.segments.metrics +``` + +### List all segments + +To list all of the segments of an audience, across all of its definitions, use the list endpoint: + +```http request +GET /api/v2/audiences/123/segments +``` + +Where `123` is the system ID of the audience. + +### Get a segment + +```http request +GET /api/v2/audiences/123/segments/456 +``` + +Where `123` is the system ID of the audience and `456` is the system ID of the segment. + +### Create a segment + +To add a segment to one of the audience's definitions, send a `POST` request. You may create the segment's metrics in +the same call. + +```http request +POST /api/v2/audiences/123/segments +``` + +```json +{ + "definition_id": 12, + "name": "Frequent flyers", + "sort_order": 10, + "within_segment_operator": "AND", + "between_segments_operator": "OR", + "metrics": [ + { + "metric_type": "audience-origins-metric", + "metric_id": 1520, + "operator": "is", + "values": ["1", "2"] + } + ] +} +``` + +| Key | Type | Required | Description | +|-----------------------------|---------|:----------------------------------:|----------------------------------------------------------------------------------------------------------------| +| `definition_id` | integer | :white_check_mark: (when creating) | The ID of the definition the segment belongs to. It has to be a definition of the audience in the path. | +| `sort_order` | integer | :x: | The position of the segment within its definition. Segments are combined in this order. Minimum `0`. | +| `name` | string | :x: | The name of the segment. Maximum 255 characters. | +| `within_segment_operator` | string | :x: | How the metrics in this segment combine. `AND` requires all of them, `OR` requires any. | +| `between_segments_operator` | string | :x: | How this segment combines with the one before it. `AND` or `OR`. | +| `metrics` | array | :x: | The metrics that make up the segment. Each accepts the same fields as when [creating a segment metric](#create-a-segment-metric). Only used when creating a segment. | + +The response has the status code `201` and contains the created segment with its metrics. + +### Update a segment + +```http request +PUT /api/v2/audiences/123/segments/456 +``` + +The request accepts the same fields as when creating a segment, except `metrics`. The segment's metrics are managed +through the [segment metric endpoints](#segment-metrics). You may move a segment to another definition of the same +audience by changing `definition_id`. + +### Delete a segment + +```http request +DELETE /api/v2/audiences/123/segments/456 +``` + +Deleting a segment also deletes its metrics. The response has the status code `204` and no content. + +### Segment schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|-----------------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|----------------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `uuid` | string | :white_check_mark: | :x: | :white_check_mark: | The unique identifier for the segment. | +| `sort_order` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The position of the segment within its definition. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the segment. | +| `within_segment_operator` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | How the metrics in the segment combine: `AND` or `OR`. | +| `between_segments_operator` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | How the segment combines with the one before it: `AND` or `OR`. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this segment was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this segment was last updated. | +| `metrics` | array | :x: | :x: | :x: | The [segment metrics](#segment-metric-schema) that make up the segment. Always included. | + +The following relationships are available as includes on the segment endpoints: + +- `definition` - The audience definition that the segment belongs to. + +## Segment metrics + +A segment metric is a single condition in a segment. It names a metric and the values a respondent must have given. + +### List all segment metrics + +```http request +GET /api/v2/audiences/123/segments/456/metrics +``` + +Where `123` is the system ID of the audience and `456` is the system ID of the segment. + +### Get a segment metric + +```http request +GET /api/v2/audiences/123/segments/456/metrics/789 +``` + +Where `789` is the system ID of the segment metric. + +### Create a segment metric + +```http request +POST /api/v2/audiences/123/segments/456/metrics +``` + +```json +{ + "metric_type": "bav-study-measure", + "metric_id": 85, + "operator": "is", + "brands": [148], + "values": ["1"] +} +``` + +| Key | Type | Required | Description | +|---------------|---------|:------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `metric_type` | string | :white_check_mark: | The kind of metric. One of `audience-origins-metric` ([Audience Origin metric](../audience-origin/metrics.md)), `bav-study-measure` ([brand measure](../measures/brand-measures.md)) or `bav-study-question` ([BAV question](../measures/bav-questions.md)). | +| `metric_id` | integer | :white_check_mark: | The ID of the metric, of the kind given in `metric_type`. | +| `operator` | string | :x: | How the values are compared. The operators accepted depend on the type of the metric. See [operators](#operators). Defaults to `eq`. | +| `brands` | array | Sometimes | The IDs of the [brands](../brands/brands.md) the metric applies to. Required for metrics that support a brand filter (see `supports_brands_filter` in the response). | +| `values` | array | :x: | The values a respondent must have given. Which values are valid depends on the metric. For Audience Origin metrics the values are validated against the metric's type and answer options. | + +The response has the status code `201` and contains the created segment metric. + +:::caution Every metric needs values +An audience with a segment metric that has no values selected cannot be deployed. +::: + +### Update a segment metric + +```http request +PUT /api/v2/audiences/123/segments/456/metrics/789 +``` + +The request accepts the same fields as when creating a segment metric. + +### Delete a segment metric + +```http request +DELETE /api/v2/audiences/123/segments/456/metrics/789 +``` + +The response has the status code `204` and no content. + +### Operators + +The operators you can use depend on the type of the metric: + +| Metric type | Operators | +|-----------------------------------------------------|---------------------------------------------------------------------------------| +| `boolean` | `true` (is selected), `false` (is not selected) | +| `dictionary` | `is`, `isnot` | +| `string`, `text` | `eq` (equals), `neq` (does not equal) | +| `integer`, `decimal`, `seven_scalar`, `six_scalar` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte` | + +### Segment metric schema + +| Key | Type | Description | +|--------------|---------|-----------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | The system ID of the segment metric. | +| `metric` | object | The metric. See below. | +| `operator` | object | How the values are compared. Contains `id` (for example `is`), `label`, `is_multiple_choice` and `mysql_operator`. | +| `brands` | array | The IDs of the brands the metric applies to, for metrics that support a brand filter. | +| `values` | object | The values a respondent must have given. `raw` is the list of values and `formatted` is a list of objects with an `id` and `label`. | +| `created_at` | string | A datetime string when this segment metric was first created. | +| `updated_at` | string | A datetime string when this segment metric was last updated. | + +The `metric` object contains: + +| Key | Type | Description | +|--------------------------|---------|--------------------------------------------------------------------------------------------------------------| +| `id` | integer | The system ID of the metric. | +| `type` | string | The kind of metric: `audience-origins-metric`, `bav-study-measure` or `bav-study-question`. | +| `label` | string | The name of the metric. | +| `key` | string | The key of the metric. | +| `dataset` | string | The acronym of the dataset the metric belongs to, for example `BAV` or `AO`. | +| `default_value` | mixed | The default value for the metric. | +| `supports_brands_filter` | boolean | Whether the metric is asked per brand, and so needs `brands` to be set. | +| `group` | object | The group the metric belongs to, with an `id` and `label`. Null if the metric has no group. | +| `variable` | string | The Audience Origin questionnaire variable. Only present for Audience Origin metrics. | + +## Audience studies + +To see which studies an audience has data in, including population projections, see +[Get the studies for an audience](./audiences.md#get-the-studies-for-an-audience). + +## Deploy an audience + +Once your audience is defined, deploy it to build its data: + +```http request +GET /api/v2/audiences/123/deploy +``` + +Where `123` is the system ID of the audience. + +The audience is queued for deployment and the data is built in the background. It shows up in the data endpoints +shortly after the request returns. Deploy the audience again every time you change its definition. + +A successful request returns: + +```json +{ + "data": { + "message": "The audience has been deployed." + } +} +``` + +If the audience cannot be deployed, the endpoint returns the status code `422` with a message explaining why. This +happens when: + +- The audience has no definitions. +- One or more segment metrics have no values selected. The message lists the names of these metrics. + +```json +{ + "data": { + "message": "The audience has no definitions and cannot be deployed." + } +} +``` diff --git a/docs/best-countries/factors.md b/docs/best-countries/factors.md index 9ee569f..e989895 100644 --- a/docs/best-countries/factors.md +++ b/docs/best-countries/factors.md @@ -1 +1,65 @@ -# Factors \ No newline at end of file +--- +sidebar_label: Factors +--- + +# Best Countries Factors + +## What are best countries factors? + +In Best Countries, the individual [metrics](metrics.md) (attributes) that countries are surveyed on are aggregated into +a smaller number of broader factors, such as Adventure or Entrepreneurship. The factors are weighted together to +calculate the overall Best Countries ranking, which is returned as `total` in the factor data. + +The factors endpoint gives you the list of factors and which metrics each factor is built from. To get the scores and +ranks for each country on the factors, use the [country data](country-data.md) endpoint with the `factors` data type, or +the [country factors model](models.md#country-factors). + +This endpoint requires the **Best Countries Data** (`bav:best-countries-data`) scope. + +## List all best countries factors + +To list all of the best countries factors and browse them via the API, use the list endpoint: + +```http request +GET /api/v2/best-countries-factors +``` + +## Get a best countries factor + +You may also directly retrieve a best countries factor's details if you already have its system ID. + +```http request +GET /api/v2/best-countries-factors/123 +``` + +Where `123` is the system ID of the factor. + +## Schema + +### Full response schema + +The factor endpoint returns every column of the factor. The `name` and `description` are translatable and are returned +as an object keyed by locale, for example `{"en": "Adventure"}`. + +| Key | Type | Description | +|---------------|---------|---------------------------------------------------------------------------------------------------------------------| +| `id` | integer | The system ID. | +| `name` | object | The name of the factor, keyed by locale. | +| `key` | string | The machine-readable key of the factor. The [country data](country-data.md) endpoint names its factor fields after it. | +| `description` | object | A description of the factor, keyed by locale. May be `null`. | +| `created_at` | string | A datetime string when this factor was first created. | +| `updated_at` | string | A datetime string when this factor was last updated. | + +## Filters & Sorting + +This endpoint does not support any filters or sorting. As there are only a handful of factors, we recommend that you +retrieve the full list and filter it in your application. + +## Relationships & includes + +By default, relationships are not included. See the [includes section](../customizing/includes) for more information +on how this works. The following relationships are available: + +- `metrics` - The [best countries metrics](metrics.md) that the factor is built from. The metrics are returned with all + of their stored columns, along with a `pivot` object linking the metric to the factor. For the documented metric + schema, use the [best countries metrics](metrics.md) endpoint. diff --git a/docs/best-countries/metric-groups.md b/docs/best-countries/metric-groups.md index 94a2e62..da87c0b 100644 --- a/docs/best-countries/metric-groups.md +++ b/docs/best-countries/metric-groups.md @@ -1 +1,69 @@ -# Metric Groups \ No newline at end of file +--- +sidebar_label: Metric Groups +--- + +# Best Countries Metric Groups + +## What are best countries metric groups? + +The [best countries metrics](metrics.md) are divided into groups for easier browsing, such as imagery, visiting, +doing business, product origin and education. The groups also make up the basis for the +Best Countries [models](models.md). For example, the country imagery model returns the metrics in the `imagery` group. + +This endpoint requires the **Best Countries Data** (`bav:best-countries-data`) scope. + +## List all best countries metric groups + +To list all of the best countries metric groups and browse them via the API, use the list endpoint: + +```http request +GET /api/v2/best-countries-metric-groups +``` + +## Get a best countries metric group + +You may also directly retrieve a best countries metric group's details if you already have its system ID. + +```http request +GET /api/v2/best-countries-metric-groups/123 +``` + +Where `123` is the system ID of the metric group. + +## Schema + +### Full response schema + +The metric group endpoint returns every column of the group. The `name` and `description` are translatable and are +returned as an object keyed by locale, for example `{"en": "Imagery"}`. + +| Key | Type | Description | +|---------------|---------|------------------------------------------------------------------------------------------------| +| `id` | integer | The system ID. | +| `is_active` | integer | Whether the group is active (`1`) or not (`0`). | +| `name` | object | The name of the group, keyed by locale. | +| `key` | string | The machine-readable key of the group, for example `imagery` or `doing-business`. | +| `description` | object | A description of the group, keyed by locale. May be `null`. | +| `created_at` | string | A datetime string when this group was first created. | +| `updated_at` | string | A datetime string when this group was last updated. | + +The groups used by the Best Countries [models](models.md) are: + +- `imagery` - The imagery/perception attributes. Used by the country and city imagery models. +- `visiting` - Visiting and visit consideration. Used by the visit consideration models. +- `doing-business` - Doing business and business consideration. Used by the doing business models. +- `origin` - Products made in the country. Used by the product origin model. +- `education` - University consideration and education. Used by the education model. + +## Filters & Sorting + +This endpoint does not support any filters or sorting. As there are only a handful of groups, we recommend that you +retrieve the full list and filter it in your application. + +## Relationships & includes + +By default, relationships are not included. See the [includes section](../customizing/includes) for more information +on how this works. The following relationships are available: + +- `metrics` - The [best countries metrics](metrics.md) in the group. The metrics are returned with all of their stored + columns. For the documented metric schema, use the [best countries metrics](metrics.md) endpoint. diff --git a/docs/best-countries/models.md b/docs/best-countries/models.md new file mode 100644 index 0000000..a6ed547 --- /dev/null +++ b/docs/best-countries/models.md @@ -0,0 +1,190 @@ +# Models + +The Best Countries model endpoints return the calculated Best Countries data for a specific model, such as country +imagery or visit consideration. Each model returns the metrics in one [metric group](metric-groups.md) (or the +[factors](factors.md)) for each country or city, year and audience. + +Unlike the [country data](country-data.md) endpoint, the models support audiences and return data for both countries +and cities. + +All model endpoints require the **Best Countries Data** (`bav:best-countries-data`) scope. + +## Available models + +| Model | Endpoint | Default score type | +|----------------------------------------------------------|--------------------------------------------------------------|--------------------| +| [Country Imagery](#country-imagery) | `POST /api/v2/best-countries/countries/imagery` | `rank` | +| [Country Factors](#country-factors) | `POST /api/v2/best-countries/countries/factors` | `rank` | +| [Country Doing Business](#country-doing-business) | `POST /api/v2/best-countries/countries/business` | `percentage` | +| [Country Visit Consideration](#country-visit-consideration) | `POST /api/v2/best-countries/countries/visit-consideration` | `rank` | +| [Country Education](#country-education) | `POST /api/v2/best-countries/countries/education` | `percentage` | +| [Country Product Origin](#country-product-origin) | `POST /api/v2/best-countries/countries/product-origin` | `percentage` | +| [City Imagery](#city-imagery) | `POST /api/v2/best-countries/cities/imagery` | `rank` | +| [City Doing Business](#city-doing-business) | `POST /api/v2/best-countries/cities/doing-business` | `percentage` | +| [City Visit Consideration](#city-visit-consideration) | `POST /api/v2/best-countries/cities/visit-consideration` | `percentage` | + +## Parameters + +The parameters are sent as a JSON body. List parameters are arrays, and each value can be either an ID or a name. + +### Country models + +| Key | Required? | Type | Description | +|-------------|:----------------------------:|--------|------------------------------------------------------------------------------------------------------------------------------| +| `years` | :white_check_mark: | array | The [years](../metadata/years.md) to read, as year IDs or calendar years. | +| `countries` | :x: (defaults to all) | array | The [countries](../metadata/countries.md) to read, by country ID, two- or three-letter ISO code, or name. Returns every country measured in the year when left out. | +| `audiences` | :x: (defaults to All Adults) | array | The [audiences](../audiences/audiences.md) to read, by audience ID or name. | +| `scoreType` | :x: (depends on the model) | string | The score type. See [score types](#score-types). | +| `format` | :x: (defaults to `json`) | string | The response format: `json`, `llm` or `mcp`. See [response formats](../brandscape-models/index.md#response-formats). | + +### City models + +The city models take the same parameters as the country models, but with `cities` in place of `countries`. + +| Key | Required? | Type | Description | +|-------------|:----------------------------:|--------|---------------------------------------------------------------------------------------------------------------------| +| `years` | :white_check_mark: | array | The [years](../metadata/years.md) to read, as year IDs or calendar years. | +| `cities` | :x: (defaults to all) | array | The [cities](../metadata/cities.md) to read, by city ID or name. Returns every city measured in the year when left out. | +| `audiences` | :x: (defaults to All Adults) | array | The [audiences](../audiences/audiences.md) to read, by audience ID or name. | +| `scoreType` | :x: (depends on the model) | string | The score type. See [score types](#score-types). | +| `format` | :x: (defaults to `json`) | string | The response format: `json`, `llm` or `mcp`. See [response formats](../brandscape-models/index.md#response-formats). | + +### Score types + +The `scoreType` parameter accepts: + +- `rank` - The country's or city's rank against the others, where 1 is best. +- `percentage` - The percentage of respondents, for example those who would consider visiting. +- `score` - A score from 0 to 100. + +The default score type depends on the model and is listed in the [table above](#available-models). + +### Example + +```http request +POST /api/v2/best-countries/countries/imagery +``` + +```json +{ + "years": [2025], + "countries": ["US", "GB"], + "audiences": [1], + "scoreType": "score" +} +``` + +## Schema + +The `json` response is an array with one object per country (or city), year and audience combination. Each object +contains: + +| Key | Type | Description | +|------------------|---------|--------------------------------------------------------------------------------------------------------------------| +| `country` | string | The name of the country. Only on the country models. | +| `city` | string | The name of the city. Only on the city models. | +| `year` | integer | The calendar year. | +| `year_id` | integer | The system ID of the [year](../metadata/years.md). Only on the country models. | +| `audience_id` | integer | The system ID of the [audience](../audiences/audiences.md). | +| `audience` | string | The name of the audience. | +| _metric keys_ | number | One field per metric in the model, named after the [metric](metrics.md) or [factor](factors.md) `key`, holding the value for the requested score type. | + +```json +[ + { + "country": "United States", + "year_id": 45, + "friendly": 12, + "safe": 20, + "audience_id": 1, + "audience": "All Adults", + "year": 2025 + } +] +``` + +The values in the example are illustrative, and only some of the metrics are shown. + +## Country Imagery + +```http request +POST /api/v2/best-countries/countries/imagery +``` + +How people describe each country, attribute by attribute. Returns the metrics in the `imagery` metric group. Uses +the `rank` score type by default. + +## Country Factors + +```http request +POST /api/v2/best-countries/countries/factors +``` + +Each country's scores on the Best Countries [factors](factors.md), the weighted categories that the overall ranking is +calculated from. Returns one field per factor `key`, along with the overall `total`. Uses the `rank` score type by +default. + +## Country Doing Business + +```http request +POST /api/v2/best-countries/countries/business +``` + +Whether business decision makers would consider doing business in each country, have done business there, or would +never consider it. Returns the metrics in the `doing-business` metric group. Uses the `percentage` score type by +default. + +## Country Visit Consideration + +```http request +POST /api/v2/best-countries/countries/visit-consideration +``` + +Whether people would consider visiting each country, have visited it, or would never consider it. Returns the metrics in +the `visiting` metric group. Uses the `rank` score type by default. + +## Country Education + +```http request +POST /api/v2/best-countries/countries/education +``` + +Whether people would consider going to university in each country, and whether they believe it has top universities. +Returns the metrics in the `education` metric group. Uses the `percentage` score type by default. + +## Country Product Origin + +```http request +POST /api/v2/best-countries/countries/product-origin +``` + +Whether people would consider, prefer or have bought products made in each country. Returns the metrics in the `origin` +metric group. Uses the `percentage` score type by default. + +## City Imagery + +```http request +POST /api/v2/best-countries/cities/imagery +``` + +How people describe each city, attribute by attribute. Returns the metrics in the `imagery` metric group that apply to +cities. Uses the `rank` score type by default. + +## City Doing Business + +```http request +POST /api/v2/best-countries/cities/doing-business +``` + +Whether people would consider doing business in each city, have done business there, or would never consider it. +Returns the metrics in the `doing-business` metric group that apply to cities. Uses the `percentage` score type by +default. + +## City Visit Consideration + +```http request +POST /api/v2/best-countries/cities/visit-consideration +``` + +Whether people would consider visiting each city, have visited it, or would never consider it. Returns the metrics in +the `visiting` metric group that apply to cities. Uses the `percentage` score type by default. diff --git a/docs/best-countries/raw-data.md b/docs/best-countries/raw-data.md new file mode 100644 index 0000000..03b967f --- /dev/null +++ b/docs/best-countries/raw-data.md @@ -0,0 +1,65 @@ +# Raw Data + +The raw data endpoint gives you the respondent-level Best Countries data for one year, with every stored answer and no +ranking or scoring applied. Each row is one respondent's answers about one country. + +:::tip Use the calculated data where you can +The respondent-level data is put through a series of processing pipelines to arrive at the Best Countries scores and +ranks. For building on top of Best Countries, you typically want the [country data](country-data.md) or +the [models](models.md) instead. We do not recommend that you calculate the scores yourself. +::: + +This endpoint requires the **Best Countries Data** (`bav:best-countries-data`) scope. + +## Creating a query + +```http request +GET /api/v2/best-countries/countries/raw/{year} +``` + +Where `{year}` is either the system ID of the [year](../metadata/years.md) or the calendar year, for example: + +```http request +GET /api/v2/best-countries/countries/raw/2024 +``` + +The endpoint returns a `404` if the year cannot be found or has no Best Countries data. + +:::note Cities and Origin Index +The equivalent raw data endpoints for cities (`/api/v2/best-countries/cities/raw/{year}`) and the Origin Index +(`/api/v2/best-countries/origin-index/raw/{year}`) are not available and return a `400` response. +::: + +## Schema + +The response is [paginated](../pagination.md). Each row contains: + +| Key | Type | Sortable | Configurable | Description | +|-----------------|---------|:------------------:|:------------------:|---------------------------------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: | :white_check_mark: | The record ID. | +| `respondent_id` | integer | :white_check_mark: | :white_check_mark: | The respondent ID. Rows with the same respondent ID are one person's answers about different countries. | +| `year` | object | :x: | :x: | The [year](../metadata/years.md) the answers were collected, with `id` and `year`. | +| `country` | object | :x: | :x: | The [country](../metadata/countries.md) the answers are about, with `id`, `name`, `region`, `code`, `code_alpha3` and `code_numeric`. | +| _metric keys_ | number | :white_check_mark: | :white_check_mark: | One field per [best countries metric](metrics.md) asked about countries, holding the respondent's answer. | + +The metric fields are named after the metric `key`, for example `familiarity`, `friendly`, `safe`, +`consider_visiting`, `consider_doing_business` or `has_top_universities`. + +## Configurable fields + +You may limit the response to specific fields with the `fields` parameter, passing a comma-separated list of field +names. Any column of the data can be used. When you limit the fields, include `id`, `year_id` and `country_id` in the +list to keep the record ID, the year and the country populated in the response. + +```http request +GET /api/v2/best-countries/countries/raw/2024?fields=id,year_id,country_id,respondent_id,familiarity +``` + +## Sorting + +All data fields can be [sorted](../customizing/filters#sorting-results) on. In addition, you can sort by the country +using `country.name`, `country.code`, `country.code_alpha3` and `country.code_numeric`. + +```http request +GET /api/v2/best-countries/countries/raw/2024?sort=country.code,-familiarity +``` diff --git a/docs/brands/brand-tags.md b/docs/brands/brand-tags.md new file mode 100644 index 0000000..bcf2f93 --- /dev/null +++ b/docs/brands/brand-tags.md @@ -0,0 +1,83 @@ +# Brand Tags + +## What are brand tags? + +Brand tags describe [brands](brands.md) beyond their sector, for example their ownership, business model or reach. A +brand can have any number of tags. + +Each tag belongs to a category: + +- `brand_characteristics` +- `business_model` +- `ownership` +- `reach_and_channel` +- `career_industry` (personal brands only) +- `career_stage` (personal brands only) + +You can use the tags to filter brands with the `tags` filter on the [brands endpoint](brands.md). The filter accepts +both tag IDs and tag keys. + +```http request +GET /api/v2/brands?filter[tags]=luxury +``` + +## List all brand tags + +To list all of the brand tags and browse them via the API, use the list endpoint: + +```http request +GET /api/v2/brand-tags +``` + +The tags are sorted by category and name by default. + +## Get a brand tag + +You may also directly retrieve a brand tag's details if you already have its system ID. + +```http request +GET /api/v2/brand-tags/123 +``` + +Where `123` is the system ID of the brand tag. + +## Schema + +### Full response schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|-----------------|---------|:-----------------------------------------:|:------------------:|:------------------:|--------------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the tag, for example "Luxury". | +| `key` | string | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The key of the tag, for example `luxury`. The brands endpoint accepts it in `filter[tags]`. | +| `category` | string | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The category the tag belongs to. See the list above. | +| `category_name` | string | :x: | :x: | :x: | The translated label of the category, for display. | +| `description` | string | :x: | :x: | :white_check_mark: | What the tag means and when it applies. | +| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the tag is active. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this tag was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this tag was last updated. | + +### Relationship Response Schema + +The slim relationship schema is used when the brand tag is used as part of an include in another resource, such as +the `tags` include on [brands](brands.md). + +| Key | Type | Description | +|-------------------|---------|--------------------------------------------------------------------------------------------------------| +| `id` | integer | The system ID for the tag. | +| `name` | string | The name of the tag. | +| `key` | string | The key of the tag. | +| `category` | string | The category the tag belongs to. | +| `is_ai_generated` | boolean | Whether the tag was assigned to the brand by AI rather than by hand. Only present when included on a brand. | + +## Relationships & includes + +By default, relationships are not included. See +the [includes section](../customizing/includes) for more information on how this works. The following relationships +are available: + +- `brands` - The [brands](brands.md) that carry this tag. + +## Searching + +This endpoint supports searching. See the [searching section](../customizing/searching) for more details. diff --git a/docs/brands/brand-variations.md b/docs/brands/brand-variations.md new file mode 100644 index 0000000..7fb6357 --- /dev/null +++ b/docs/brands/brand-variations.md @@ -0,0 +1,93 @@ +# Brand Variations + +## What are brand variations? + +A [brand](brands.md) can be known under more than one name. Brand variations are the names a brand is studied under. +A variation is either: + +- `equivalent` - Another name for the brand. +- `previously` - A name the brand was previously known as. + +Each brand variation has a unique numeric `key`, which can be negative, and a short `code`. When a brand variation is +deprecated, it may point to the variation that replaced it. + +This endpoint requires the `bav:brand-data` scope. + +## List all brand variations + +To list all of the brand variations and browse them via the API, use the list endpoint: + +```http request +GET /api/v2/brand-variations +``` + +## Get a brand variation + +You may also directly retrieve a brand variation's details if you already have its system ID. + +```http request +GET /api/v2/brand-variations/123 +``` + +Where `123` is the system ID of the brand variation. + +## Schema + +### Full response schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|-----------------|---------|:-----------------------------------------:|:------------------:|:------------------:|--------------------------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `name` | string | :white_check_mark: (search) | :white_check_mark: | :white_check_mark: | The name of the brand variation. Filtering on the name uses the search index, the same as `search`. | +| `brand_id` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The system ID of the [brand](brands.md) this is a variation of. | +| `type` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The type of brand variation: `equivalent` or `previously`. | +| `key` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The numeric key of the brand variation. Keys are unique and can be negative. | +| `code` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The code of the brand variation, three or four uppercase letters. | +| `is_core` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the brand variation is a core brand, always included in quarterly US studies. | +| `is_ranked` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the brand variation is ranked by default, as opposed to a holdout brand. Used together with core brands in the US. | +| `is_global` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the brand variation is a global brand, included in all studies. | +| `is_deprecated` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the brand variation is deprecated. | +| `url` | string | :x: | :x: | :x: | The URL of the brand variation's page on The Fount. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this brand variation was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this brand variation was last updated. | + +### Relationship Response Schema + +The slim relationship schema is used when the brand variation is used as part of an include in another resource, such +as the brandscape data. + +| Key | Type | Description | +|---------|---------|---------------------------------------------------------------------| +| `id` | integer | The system ID for the brand variation. | +| `name` | string | The name of the brand variation. | +| `brand` | object | The [brand](brands.md) this is a variation of, when included. | +| `type` | string | The type of brand variation: `equivalent` or `previously`. | +| `key` | integer | The numeric key of the brand variation. | + +## Additional Filters + +For convenience, we have a set of additional filters that are not available in +the [default filters](../customizing/filters.md) or are part of the columns. These are: + +- `brands` - A comma-separated list of brand IDs. Only variations of these brands are returned. +- `keys` - A comma-separated list of brand variation keys. +- `studies` - A comma-separated list of study IDs. Only variations included in these studies are returned. +- `has_studies` - Set to `1` to only return variations that have been measured in at least one study, or `0` for + variations that have not. + +## Relationships & includes + +By default, relationships are not included. See +the [includes section](../customizing/includes) for more information on how this works. The following relationships +are available: + +- `brand` - The [brand](brands.md) this is a variation of. +- `replacement` - The brand variation that replaced this one, if it is deprecated. + +## Searching + +This endpoint supports searching by name. See the [searching section](../customizing/searching) for more details. + +When searching, either with `search` or `filter[name]`, only these filters apply: `id`, `brand_id`, `type`, `code`, +`keys`, `studies`, `is_core`, `is_global`, `is_ranked`, `is_deprecated` and `has_studies`. Sorting is also limited to a +single column. diff --git a/docs/brandscape-models/agency-change-predictor.md b/docs/brandscape-models/agency-change-predictor.md new file mode 100644 index 0000000..336f1f3 --- /dev/null +++ b/docs/brandscape-models/agency-change-predictor.md @@ -0,0 +1,127 @@ +# Agency Change Predictor + +The Agency Change Predictor (ACP) analyzes brand vulnerability using ten weighted checks to determine the likelihood of +an agency change. It combines brand equity metrics with category comparisons to provide a vulnerability assessment for +each brand. + +## Creating a query + +The endpoint accepts both `GET` (with query parameters) and `POST` (with a JSON body) requests. + +```http request +GET /api/v2/tools/agency-change-predictor +POST /api/v2/tools/agency-change-predictor +``` + +This endpoint requires the `bav:brand-data` scope and that your account has access to the Agency Change Predictor in +The Fount. + +## Parameters + +The ACP takes the same filters as the [brandscape models](index.md#parameters), apart from `benchmarks` and `format`. +The filters can be passed as arrays (`brands[]=148&brands[]=149`) or, for backwards compatibility, as comma-separated +lists (`brands=148,149`). + +| Key | Required? | Type | Description | +|---------------|:------------------------------:|---------|---------------------------------------------------------------------------------------------------------------------| +| `brands` | At least one* | array | [Brand](../brands/brands.md) IDs or names. | +| `studies` | At least one* | array | [Study](../studies/studies.md) IDs or names. | +| `countries` | At least one* | array | [Country](../metadata/countries.md) IDs, codes or names. | +| `years` | At least one* | array | [Year](../metadata/years.md) IDs or year numbers. | +| `audiences` | :x: (defaults to All Adults) | array | [Audience](../audiences/audiences.md) IDs or names. | +| `study_types` | :x: (defaults to `syndicated`) | array | The kinds of study that a `countries` and `years` filter may resolve to. See [brandscape models](index.md#parameters). | +| `category` | :x: | integer | Only include brands in this [category](../studies/categories.md) ID. | +| `search` | :x: | string | Search brands by name. | +| `customWeights` | :x: | object | Custom weights for the checks, keyed by check name. See [custom weights](#custom-weights). | +| `mustPass` | :x: | array | Checks the brand must pass, i.e. problems it must not have. Max 10. | +| `mustNotPass` | :x: | array | Checks the brand must not pass, i.e. problems it must have. Max 10. | + +\* At least one of `brands`, `studies`, `countries` or `years` is required. + +## The checks + +Each check names a problem, so a brand passes a check when it does not have that problem. Each check has a default +weight that is used in the standard vulnerability score. + +| Check | Weight | Name | Description | +|---------------------------------------------|:------:|-------------------------------------|-----------------------------------------------------------------------------------------------------| +| `is_vulnerable` | 3 | Eroded Brand Equity | `differentiation < relevance < esteem < knowledge` | +| `has_momentum_warning` | 1 | Low Growth Potential | `brand_strength < brand_stature * 1.1` | +| `low_differentiation` | 1 | Low Differentiation | Differentiation rank below 30. | +| `has_low_popularity_growth` | 1 | Low Momentum | Popularity rank below 30. | +| `has_high_churn` | 3 | High Churn | Lapsed users outnumber current users. | +| `has_lower_differentation_than_category` | 3 | Lower Differentiation vs Category | Differentiation below the category average. | +| `has_lower_popularity_growth_than_category` | 3 | Weaker Popularity vs Category | Popularity rank below the category average. | +| `has_bigger_churn_than_category` | 2 | Greater Churn vs Category | Churn ratio above the category average. | +| `has_advocacy_under_category` | 2 | Lower Advocacy | Recommendation below the category average. | +| `has_lower_preference_than_category` | 1 | Lower Preference | Preference below the category average. | + +The popularity rank is the "gaining in popularity" rank on the classic BAV methodology and the "trendy" rank on the +2025 methodology. It is returned as `raw_metrics.popularity_rank`. + +:::note Spelling +The check `has_lower_differentation_than_category` contains a legacy typo ("differentation" instead of +"differentiation"). It is kept for backwards compatibility. +::: + +The category comparisons average every brand that the study measured in the category, regardless of which brands you +asked for. They are worked out per study, so a brand is always compared with its own market. + +A check is `null` when a metric it needs is missing for the brand, for example when usage was not asked. A `null` +check counts as passed in the score, and neither `mustPass` nor `mustNotPass` on that check matches the brand. + +### Filtering on checks + +Use `mustPass` and `mustNotPass` to filter the brands by their check results. A check cannot be in both lists. For +example, to get brands that are not vulnerable and not churning, but are poorly differentiated: + +```http request +GET /api/v2/tools/agency-change-predictor?studies[]=635&mustPass[]=is_vulnerable&mustPass[]=has_high_churn&mustNotPass[]=low_differentiation +``` + +### Custom weights + +Use `customWeights` to calculate a second vulnerability score with your own weights. Each weight is an integer from 0 +to 10, keyed by check name. A weight of `0` drops the check from the score. A check that you leave out keeps its default +weight. At least one weight must be greater than 0. + +```http request +GET /api/v2/tools/agency-change-predictor?studies[]=635&customWeights[is_vulnerable]=5&customWeights[has_high_churn]=4 +``` + +## Response + +The response contains a `meta` object and a `data` array. Every brand matching the filters is returned, including +brands that pass every check and so score zero. + +### Meta + +| Key | Type | Description | +|------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| `source` | string | A source label naming the studies and audiences, suitable for captioning. | +| `studies_used` | array | The studies the data came from. This is useful when you filter by `countries`, since the studies are then chosen for you. Each study includes its `study_id`, `name`, `country`, `year` and `type`, along with other details where available. | +| `is_category_specific` | boolean | Whether the data is category specific. | + +### Data + +| Key | Type | Description | +|-------------------|--------|-------------------------------------------------------------------------------------| +| `brand` | object | The [brand](../brands/brands.md), with `id` and `name`. | +| `brand_variation` | object | The brand variation, with `id` and `name`. | +| `sector` | object | The [sector](../metadata/sectors.md), with `id` and `name`. | +| `category` | object | The [category](../studies/categories.md), with `id` and `name`. | +| `study` | object | The [study](../studies/studies.md), with `id` and `name`. | +| `country` | object | The [country](../metadata/countries.md), with `id` and `name`. | +| `year` | object | The [year](../metadata/years.md), with `id` and `name`. | +| `audience` | object | The [audience](../audiences/audiences.md), with `id` and `name`. | +| `data` | object | The vulnerability scores and check results. See below. | + +The `data` object contains: + +| Key | Type | Description | +|--------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `vulnerability_score_standard` | float | The vulnerability score (0-100) using the default weights. | +| `vulnerability_score_custom` | float | The vulnerability score (0-100) using your `customWeights`. | +| `checks` | object | The result of each of the ten [checks](#the-checks), keyed by check name. `true` when the brand has the problem, `false` when it does not, and `null` when the check could not be evaluated. | +| `category_comparisons` | object | The category averages used by the comparison checks: `differentiation_average`, `gaining_in_popularity_average`, `one_i_prefer_average`, `recommendation_average` and `churn_ratio`. | +| `raw_metrics` | object | The metric values used in the checks: `differentiation_rank`, `relevance_rank`, `esteem_rank`, `knowledge_rank`, `brand_strength_rank`, `brand_stature_rank`, `gaining_in_popularity_rank`, `popularity_rank`, `total_users_pct`, `lapsed_user_pct`, `churn_ratio`, `recommend_to_a_friend_pct` and `one_i_prefer_pct`. | diff --git a/docs/brandscape-models/brand-worth.md b/docs/brandscape-models/brand-worth.md new file mode 100644 index 0000000..90bb8ac --- /dev/null +++ b/docs/brandscape-models/brand-worth.md @@ -0,0 +1,37 @@ +# Brand Worth + +Brand Worth returns the data behind the Brand Worth Map: each brand's percentile ranks for "Worth paying more for" and +"Providing good value". The map places each brand in one of four quadrants: + +- **Brand Worth** - `worth_more` rank above 50 and `good_value` rank above 50. +- **Desire** - `worth_more` rank above 50 and `good_value` rank below 50. +- **Emotional Choice** - `worth_more` rank below 50 and `good_value` rank below 50. +- **Value Champion** - `worth_more` rank below 50 and `good_value` rank above 50. + +Brand Worth is only available as a `POST` request. For the Brand Worth Map tool, see +the [Brand Worth Map](../brand-data/brand-worth-map.md) endpoint. + +## Creating a query + +```http request +POST /api/v2/brandscape/brand-worth +``` + +This endpoint requires the `bav:brand-data` scope. + +## Parameters + +This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +`years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or +`years` is required. + +## Response + +The response follows the [standard brandscape model schema](index.md#schema). + +### Metrics + +The data points include the `good_value` and `worth_more` metrics with their `rank` scores. Brands that are studied in +more than one category are only included once. + +The quadrant is not returned as a `classification` on this endpoint. Use the rules above to place the brands. diff --git a/docs/brandscape-models/imagery.md b/docs/brandscape-models/imagery.md new file mode 100644 index 0000000..49abf5e --- /dev/null +++ b/docs/brandscape-models/imagery.md @@ -0,0 +1,39 @@ +# Imagery + +Imagery shows how consumers perceive a brand against a set of imagery attributes. It helps you understand on a deep +level how a brand is perceived and what associations it evokes in the minds of consumers. + +The available attributes can vary between studies. Studies with the same methodology generally have the same attributes, +but there have been variations over time and for some markets. If an attribute is not present in the response, it is +not available for the given study. + +Imagery is category agnostic. + +## Creating a query + +```http request +POST /api/v2/brandscape/imagery +GET /api/v2/tools/imagery +``` + +The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query +parameters. Both return the same response. + +This endpoint requires the `bav:brand-data` scope. + +## Parameters + +This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +`years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or +`years` is required. + +## Response + +The response follows the [standard brandscape model schema](index.md#schema). + +### Metrics + +The data points include the metrics in the `imagery` [metric group](../metrics/metric-groups.md), each with: + +- `percentage` - The percentage of respondents who associate the brand with the attribute. +- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. diff --git a/docs/brandscape-models/index.md b/docs/brandscape-models/index.md new file mode 100644 index 0000000..0514996 --- /dev/null +++ b/docs/brandscape-models/index.md @@ -0,0 +1,249 @@ +--- +sidebar_label: Overview +--- + +# Brandscape Models + +The brandscape model endpoints return the data behind the core BAV data models, such as the Powergrid, Pillars and +Imagery. Rather than having to know which [brand metrics](../metrics/metrics.md) make up each model, you ask for the +model and get back the relevant metrics for each brand, together with the brand, study, audience and category they +belong to. + +The following models are available: + +| Model | Endpoint | Category specific? | Also available as | +|-------------------------------------------|-----------------------------------|:------------------:|----------------------------| +| [Powergrid](powergrid.md) | `POST /api/v2/brandscape/powergrid` | :x: | `GET /api/v2/tools/powergrid` | +| [Pillars](pillars.md) | `POST /api/v2/brandscape/pillars` | :x: | `GET /api/v2/tools/pillars` | +| [Imagery](imagery.md) | `POST /api/v2/brandscape/imagery` | :x: | `GET /api/v2/tools/imagery` | +| [Personality](personality.md) | `POST /api/v2/brandscape/personality` | :x: | `GET /api/v2/tools/personality` | +| [Influence](influence.md) | `POST /api/v2/brandscape/influence` | :x: | - | +| [Brand Worth](brand-worth.md) | `POST /api/v2/brandscape/brand-worth` | :x: | - | +| [Preferences](preferences.md) | `POST /api/v2/brandscape/preferences` | :white_check_mark: | `GET /api/v2/tools/preferences` | +| [Usage](usage.md) | `POST /api/v2/brandscape/usage` | :white_check_mark: | `GET /api/v2/tools/usage` | +| [Recommendation](recommendation.md) | `POST /api/v2/brandscape/recommendation` | :white_check_mark: | `GET /api/v2/tools/recommendation` | +| [Super CX](super-cx.md) | `POST /api/v2/brandscape/super-cx` | :white_check_mark: | `GET /api/v2/tools/super-cx`* | + +\* `GET /api/v2/tools/super-cx` is a separate tool endpoint with its own parameters and response. See +the [Super CX](super-cx.md) page. + +The [Agency Change Predictor](agency-change-predictor.md) is built on the same filters, but returns its own response. + +All brandscape model endpoints require the **BAV Brand Data** (`bav:brand-data`) scope. + +## Category specific and category agnostic models + +Most BAV metrics are category agnostic. Respondents are asked to evaluate the brand without a specific category in mind. +For these models, the category in the response has no analytical significance. + +Usage, preferences, recommendation and Super CX are category specific. Respondents are asked about the brand in the +specific category it is studied in. For these models the category should always be shown together with the brand, as +it can significantly change the interpretation of the results. + +## Creating a query + +Each model is available as a `POST` request to `/api/v2/brandscape/{model}` where the parameters are sent as a JSON +body. Most models are also available as a `GET` request to `/api/v2/tools/{model}` where the same parameters are sent +as query parameters. The two return the same response. + +```http request +POST /api/v2/brandscape/pillars +GET /api/v2/tools/pillars?brands[]=148&countries[]=US&years[]=2025 +``` + +## Parameters + +All brandscape model endpoints share the same set of parameters. + +List parameters are arrays. In a query string, pass repeated values (`brands[]=148&brands[]=149`). Each value can be +either an ID or a name. When you pass a name, the system will attempt to find the right record based on the similarity +of the name. + +| Key | Required? | Type | Description | +|---------------|:----------------------------------------:|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `brands` | At least one* | array | [Brand](../brands/brands.md) IDs or names. Max 50. | +| `studies` | At least one* | array | [Study](../studies/studies.md) IDs or names. Max 50. | +| `countries` | At least one* | array | [Country](../metadata/countries.md) IDs, ISO 3166-1 alpha-2 or alpha-3 codes, or names. Max 50. | +| `years` | At least one* | array | [Year](../metadata/years.md) IDs or year numbers (e.g. `2025`). Max 50. | +| `audiences` | :x: (defaults to All Adults) | array | [Audience](../audiences/audiences.md) IDs or names. Max 50. | +| `study_types` | :x: (defaults to `syndicated`) | array | The kinds of study that a `countries` and `years` filter may resolve to: `syndicated` (the full BAV study), `snap` (SnapBAV), `fused` (AO+BAV, not comparable to syndicated studies) or `custom` (bespoke studies). Ignored when `studies` is set. | +| `benchmarks` | :x: | object | Benchmark the brands against the average of a competitive set. See [benchmarks](#benchmarks). | +| `format` | :x: (defaults to `json`) | string | The response format. See [response formats](#response-formats). | + +\* At least one of `brands`, `studies`, `countries` or `years` is required. + +When you filter by `countries` and `years` rather than `studies`, the studies are chosen for you, limited to +the `study_types` you ask for. By default only the syndicated studies are used, so that the response does not mix in +SnapBAV or fused studies that are not comparable to them. + +An example `POST` body: + +```json +{ + "brands": ["148", "149"], + "countries": ["US"], + "years": ["2025"], + "audiences": ["1"] +} +``` + +### Benchmarks + +You can add comparison rows to the response by benchmarking the brands against the average of one or more competitive +sets. Each benchmark adds a row to the response. + +- `benchmarks[categories]` - A comma-separated list of [category](../studies/categories.md) IDs. +- `benchmarks[collections]` - A comma-separated list of [collection](../brands/collections.md) IDs. +- `benchmarks[sectors]` - A comma-separated list of [sector](../metadata/sectors.md) IDs. + +```json +{ + "brands": ["148"], + "studies": ["635"], + "benchmarks": { + "categories": "12,13" + } +} +``` + +## Response formats + +The `format` parameter accepts: + +- `json` - The default. The standard API response documented below. +- `llm` - The data formatted for use in AI prompts. The response contains `model_instructions` (instructions describing + the model), `data` (the data as a CSV string) and `prompt` (a finished prompt that combines the instructions and the + data, ready to send to an AI model). +- `mcp` - The response shape used by our [MCP servers](../ai/mcp/intro.md). + +## Schema + +The `json` response is an object with a `meta` object and a `data` array. + +### Meta + +| Key | Type | Description | +|------------------------|---------|-------------------------------------------------------------------------------------------------| +| `source` | string | A source label naming the studies and audiences the data came from, suitable for captioning. | +| `is_category_specific` | boolean | Whether the model is category specific. See [above](#category-specific-and-category-agnostic-models). | + +Some models add extra keys to the meta object. These are listed on the model's page. + +### Data + +Each item in `data` is a data point for one brand, in one study, category and audience. + +| Key | Type | Description | +|------------------------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | string | `brand` for individual brand data points. Benchmark rows have a different type. | +| `study` | string | The name of the [study](../studies/studies.md). | +| `study_id` | integer | The system ID of the study. | +| `year` | string | The year. | +| `year_id` | integer | The system ID of the [year](../metadata/years.md). | +| `country` | string | The country name. | +| `country_id` | integer | The system ID of the [country](../metadata/countries.md). | +| `base` | string | The audience name. | +| `base_id` | integer | The system ID of the [audience](../audiences/audiences.md). | +| `brand` | string | The brand name. | +| `brand_id` | integer | The system ID of the [brand](../brands/brands.md). | +| `brand_variation` | string | The brand variation, used to differentiate between different spellings of the same brand. | +| `brand_variation_id` | integer | The system ID of the brand variation. | +| `brand_variation_key` | integer | The key of the brand variation. This can be both a positive and negative integer. | +| `local_name` | string | The name of the brand (in English) as shown to the respondent in the survey. | +| `category` | string | The category that respondents were asked the brand's usage, preference and recommendation in. All other metrics are category agnostic and unrelated to the category. | +| `category_id` | integer | The system ID of the [category](../studies/categories.md). | +| `sector` | string | The sector that the brand belongs to. | +| `sector_id` | integer | The system ID of the [sector](../metadata/sectors.md). | +| `period` | integer | The period the data point is for. Typically Full Year (`1`) or Full Year - Rolling (`8`). | +| `company` | string | The name of the company that owns the brand. | +| `company_id` | integer | The system ID of the [company](../company-data/companies.md). | +| `competitive_set` | string\|null | The name of the competitive set. Only set for benchmark rows. | +| `competitive_set_id` | integer\|null | The system ID of the competitive set. Only set for benchmark rows. | +| `competitive_set_type` | string\|null | The type of competitive set. Only set for benchmark rows. | +| `classification` | object\|null | The model's own reading of the data point, such as the Powergrid quadrant or pillar pattern. Only set on models that classify brands. See [classification](#classification). | +| `metrics` | object | The metrics for the data point, keyed by metric key. See [metrics](#metrics). | + +### Metrics + +The `metrics` object is keyed by the metric key (for example `differentiation`). Each metric is an object with all of +the score types. A score type that the metric does not support is `null`. + +| Key | Type | Description | +|--------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------| +| `key` | string | The metric key. See [brand metrics](../metrics/metrics.md). | +| `rank` | float\|null | The percentile rank (0-100) comparing the brand to all other brands in the market. | +| `value` | float\|null | A raw value for metrics that have none of the other score types, such as base sizes. | +| `percentage` | float\|null | The percentage (0-100) of respondents, for example those who selected the attribute. | +| `construct` | float\|null | The underlying calculated score for metrics built from other metrics or respondent-level measures. This is not meant for display or analysis. | +| `brandscape_index` | float\|null | An index of the brand against the whole brandscape. Values above 100 are above average. | +| `category_index` | float\|null | An index of the brand against its category. Values above 100 are above average. | + +### Classification + +Models that classify brands, such as the [Powergrid](powergrid.md) and [Pillars](pillars.md), return a +`classification` object on each data point they could classify. Use it rather than deriving the classification from +the scores yourself. + +| Key | Type | Description | +|---------------|--------------|-----------------------------------------------------------------------------------------------------| +| `key` | string | The machine-readable key for the classification. This is stable, and what you should branch on. | +| `label` | string | The human-readable name of the classification, as The Fount labels it. | +| `description` | string\|null | Copy describing what the classification means for the brand. Only set on some models. | + +### Example + +```json +{ + "meta": { + "source": "Source: WPP BAV, USA 2025 (All Adults)", + "is_category_specific": false + }, + "data": [ + { + "type": "brand", + "study": "USA 2025", + "study_id": 635, + "year": "2025", + "year_id": 45, + "country": "United States", + "country_id": 6, + "base": "All Adults", + "base_id": 1, + "brand": "Coca-Cola", + "brand_id": 148, + "brand_variation": "Coca-Cola", + "brand_variation_id": 1, + "brand_variation_key": 12345, + "local_name": "Coca-Cola", + "category": "Soft Drinks", + "category_id": 1, + "sector": "Food & Drink", + "sector_id": 1, + "period": 1, + "company": "The Coca-Cola Company", + "company_id": 1, + "competitive_set": null, + "competitive_set_id": null, + "competitive_set_type": null, + "classification": { + "key": "balanced-leader", + "label": "Balanced Leader", + "description": "..." + }, + "metrics": { + "differentiation": { + "key": "differentiation", + "rank": 86.65, + "value": null, + "percentage": null, + "construct": 1.12, + "brandscape_index": null, + "category_index": null + } + } + } + ] +} +``` + +The values in the example are illustrative. diff --git a/docs/brandscape-models/influence.md b/docs/brandscape-models/influence.md new file mode 100644 index 0000000..0d4ea98 --- /dev/null +++ b/docs/brandscape-models/influence.md @@ -0,0 +1,32 @@ +# Influence + +Influence shows how a brand influences consumers in its market, across the BAV influence dimensions such as +Innovation, Authenticity, Status, Trust, Convenience, Contemporary, Performance, Fun and Purpose. + +Influence is category agnostic. + +Influence is only available as a `POST` request. There is no `GET /api/v2/tools/influence` endpoint. + +## Creating a query + +```http request +POST /api/v2/brandscape/influence +``` + +This endpoint requires the `bav:brand-data` scope. + +## Parameters + +This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +`years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or +`years` is required. + +## Response + +The response follows the [standard brandscape model schema](index.md#schema). + +### Metrics + +The data points include the metrics in the `influence` [metric group](../metrics/metric-groups.md), such as +`mib_innovation`, `mib_authenticity`, `mib_status` and `mib_trust`. The overall `mib_influential` metric is not +included in this model. diff --git a/docs/brandscape-models/personality.md b/docs/brandscape-models/personality.md new file mode 100644 index 0000000..c20d4cf --- /dev/null +++ b/docs/brandscape-models/personality.md @@ -0,0 +1,36 @@ +# Personality + +Personality types provide a higher-level understanding of how a brand is perceived by consumers. They categorize brands +into ten distinct personality types based on the [imagery](imagery.md) attributes. The personality types are consistent +across all studies. + +Personality is category agnostic. + +## Creating a query + +```http request +POST /api/v2/brandscape/personality +GET /api/v2/tools/personality +``` + +The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query +parameters. Both return the same response. + +This endpoint requires the `bav:brand-data` scope. + +## Parameters + +This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +`years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or +`years` is required. + +## Response + +The response follows the [standard brandscape model schema](index.md#schema). + +### Metrics + +The data points include the metrics in the `personality` [metric group](../metrics/metric-groups.md), each with: + +- `percentage` - The percentage of respondents who associate the brand with the personality type. +- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. diff --git a/docs/brandscape-models/pillars.md b/docs/brandscape-models/pillars.md new file mode 100644 index 0000000..58a1802 --- /dev/null +++ b/docs/brandscape-models/pillars.md @@ -0,0 +1,48 @@ +# Pillars + +The four pillars of brand equity are one of the foundational concepts of BAV. They break down the +[Powergrid](powergrid.md) into the four key dimensions that define a brand's position: + +- **Differentiation** +- **Relevance** +- **Esteem** +- **Knowledge** + +When charted, the pillars should be displayed as a column chart in the order above. + +Pillars are category agnostic. + +## Creating a query + +```http request +POST /api/v2/brandscape/pillars +GET /api/v2/tools/pillars +``` + +The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query +parameters. Both return the same response. + +This endpoint requires the `bav:brand-data` scope. + +## Parameters + +This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +`years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or +`years` is required. + +## Response + +The response follows the [standard brandscape model schema](index.md#schema). + +### Metrics + +The data points include the `differentiation`, `relevance`, `esteem` and `knowledge` metrics, each with: + +- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. +- `construct` - The underlying construct score. This should not be used for display or analysis. + +### Classification + +The shape the four pillars make together is the brand's pillar pattern. Each data point includes its pattern as +`classification`, with a `key` (for example `balanced-leader` or `cultural-icon`), a translated `label` and a +`description` of what the pattern means for the brand. diff --git a/docs/brandscape-models/powergrid.md b/docs/brandscape-models/powergrid.md new file mode 100644 index 0000000..ccb9be7 --- /dev/null +++ b/docs/brandscape-models/powergrid.md @@ -0,0 +1,62 @@ +# Powergrid + +The BAV Powergrid is the core of the BAV brand equity model. It represents a brand's position based on two key +dimensions: + +- **Brand Strength** (the Y-axis) - How well a brand is perceived in terms of its differentiation and relevance. +- **Brand Stature** (the X-axis) - How well a brand is respected and known (esteem and knowledge). + +The Powergrid is a two-by-two matrix that categorizes brands into four quadrants, where a percentile rank of 50 or above +is high and anything below 50 is low: + +- **Leadership** - High Brand Strength and high Brand Stature. Top right quadrant. +- **Momentum** - High Brand Strength and low Brand Stature. Top left quadrant. +- **Fatigued** - Low Brand Strength and high Brand Stature. Bottom right quadrant. +- **Unfocused** - Low Brand Strength and low Brand Stature. Bottom left quadrant. + +The Leadership quadrant can be further divided by a diagonal line from (50, 50) to (100, 100). Brands above the line are +in **Leadership** and brands below the line are in **Mass Market**. + +When charted, the Powergrid should be displayed as a scatter plot with lines crossing at 50 on both axes and with the +quadrant labels always shown. + +The Powergrid is category agnostic. + +## Creating a query + +```http request +POST /api/v2/brandscape/powergrid +GET /api/v2/tools/powergrid +``` + +The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query +parameters. Both return the same response. + +This endpoint requires the `bav:brand-data` scope. + +## Parameters + +This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +`years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or +`years` is required. + +## Response + +The response follows the [standard brandscape model schema](index.md#schema). + +### Metrics + +The data points include the `brand_strength` and `brand_stature` metrics, each with: + +- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. +- `construct` - The underlying construct score. This should not be used for display or analysis. + +### Classification + +Each data point includes its quadrant as `classification`, with a `key` of `leadership`, `momentum`, `fatigued` or +`unfocused`, and a translated `label`. Use it rather than deriving the quadrant from the ranks yourself. + +### Meta + +In addition to the standard meta keys, the Powergrid adds a `labels` object with the translated axis labels +(`labels.axis.x` and `labels.axis.y`) and quadrant labels (`labels.quadrants`) for use when drawing the chart. diff --git a/docs/brandscape-models/preferences.md b/docs/brandscape-models/preferences.md new file mode 100644 index 0000000..02119c0 --- /dev/null +++ b/docs/brandscape-models/preferences.md @@ -0,0 +1,43 @@ +# Preferences + +Preferences show consumers' preference for brands on a scale: + +- Would never consider +- Only if no alternative +- One of several +- One I prefer + +Preferences are consistent across all studies and can be used to understand how likely consumers are to choose a brand. + +Preferences are category specific. Respondents are asked about their preference for the brand in the specific +category. The category should always be shown together with the brand, as it can significantly change the +interpretation of the results. + +## Creating a query + +```http request +POST /api/v2/brandscape/preferences +GET /api/v2/tools/preferences +``` + +The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query +parameters. Both return the same response. + +This endpoint requires the `bav:brand-data` scope. + +## Parameters + +This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +`years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or +`years` is required. + +## Response + +The response follows the [standard brandscape model schema](index.md#schema). + +### Metrics + +The data points include the metrics in the `preference` [metric group](../metrics/metric-groups.md), each with: + +- `percentage` - The percentage of respondents who fall into each preference level. +- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. diff --git a/docs/brandscape-models/recommendation.md b/docs/brandscape-models/recommendation.md new file mode 100644 index 0000000..a8ab646 --- /dev/null +++ b/docs/brandscape-models/recommendation.md @@ -0,0 +1,36 @@ +# Recommendation + +Recommendation shows how likely consumers are to recommend a brand to a friend. It is consistent across all studies. + +Recommendation is category specific. Respondents are asked about their likelihood to recommend the brand in the +specific category. The category should always be shown together with the brand, as it can significantly change the +interpretation of the results. + +## Creating a query + +```http request +POST /api/v2/brandscape/recommendation +GET /api/v2/tools/recommendation +``` + +The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query +parameters. Both return the same response. + +This endpoint requires the `bav:brand-data` scope. + +## Parameters + +This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +`years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or +`years` is required. + +## Response + +The response follows the [standard brandscape model schema](index.md#schema). + +### Metrics + +The data points include the metrics in the `recommendation` [metric group](../metrics/metric-groups.md), each with: + +- `percentage` - The percentage of respondents who would recommend the brand. +- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. diff --git a/docs/brandscape-models/super-cx.md b/docs/brandscape-models/super-cx.md new file mode 100644 index 0000000..635776c --- /dev/null +++ b/docs/brandscape-models/super-cx.md @@ -0,0 +1,93 @@ +# Super CX + +Super CX measures a brand's perceived customer experience. It is made up of the overall Super CX score and its Head, +Heart and X Factor components, which in turn are built from a set of underlying measures. + +Super CX is category specific. The category should always be shown together with the brand, as it can significantly +change the interpretation of the results. + +There are two ways to get Super CX data: the brandscape model endpoint and the Super CX tool endpoint. We recommend the +brandscape model endpoint for new integrations, as it shares its parameters and response with the +other [brandscape models](index.md). + +## Brandscape model + +### Creating a query + +```http request +POST /api/v2/brandscape/super-cx +``` + +This endpoint requires the `bav:brand-data` scope. + +### Parameters + +This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +`years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or +`years` is required. + +### Response + +The response follows the [standard brandscape model schema](index.md#schema). The data points include the metrics in +the `super-cx` [metric group](../metrics/metric-groups.md). + +## Super CX tool + +The Super CX tool endpoint returns the percentile ranks of the Super CX metrics for a set of brands in one study. + +### Creating a query + +```http request +GET /api/v2/tools/super-cx +``` + +This endpoint requires the `bav:brand-data` scope and that your account has access to the Super CX tool in The Fount. + +### Parameters + +| Key | Required? | Type | Description | +|-------------|:----------------------------:|---------------|------------------------------------------------| +| `brands` | :white_check_mark: | numeric array | A comma-separated list of Brand IDs. | +| `studies` | :white_check_mark: | numeric | A single Study ID. | +| `audiences` | :x: (defaults to All Adults) | numeric | A single Audience ID. | + +### Response + +The response contains a `data` array with one object per brand. + +| Key | Type | Description | +|------------|--------|-------------------------------------------------------------------------------------| +| `name` | string | The series name for the brand, for use as a label. | +| `study` | object | The [study](../studies/studies.md), with `id` and `name`. | +| `country` | object | The [country](../metadata/countries.md), with `id` and `name`. | +| `year` | object | The [year](../metadata/years.md), with `id` and `name`. | +| `audience` | object | The [audience](../audiences/audiences.md), with `id` and `name`. | +| `data` | object | The Super CX metrics, keyed by metric key. Each has a `label` and a `value`, where the `value` is the percentile rank (0-100). | + +The metric keys in `data` are: + +- `super_cx` - The overall Super CX score. +- `head`, `heart` and `x_factor` - The three components of Super CX. +- `value`, `simplicity`, `courtesy`, `committed`, `attracted` and `evangelical` - The underlying measures. + +```json +{ + "data": [ + { + "name": "Coca-Cola", + "study": { "id": 635, "name": "USA 2025" }, + "country": { "id": 6, "name": "United States" }, + "year": { "id": 45, "name": "2025" }, + "audience": { "id": 1, "name": "All Adults" }, + "data": { + "super_cx": { "label": "Super CX", "value": 82.4 }, + "head": { "label": "Head", "value": 75.1 }, + "heart": { "label": "Heart", "value": 88.0 }, + "x_factor": { "label": "X Factor", "value": 79.3 } + } + } + ] +} +``` + +The values in the example are illustrative, and only some of the metrics are shown. diff --git a/docs/brandscape-models/usage.md b/docs/brandscape-models/usage.md new file mode 100644 index 0000000..dab7653 --- /dev/null +++ b/docs/brandscape-models/usage.md @@ -0,0 +1,43 @@ +# Usage + +Usage shows how consumers use brands on a scale: + +- Never used +- Lapsed user (used in the past but not anymore) +- Use occasionally +- Use regularly + +Usage is consistent across all studies. + +Usage is category specific. Respondents are asked about their usage of the brand in the specific category. The +category should always be shown together with the brand, as it can significantly change the interpretation of the +results. + +## Creating a query + +```http request +POST /api/v2/brandscape/usage +GET /api/v2/tools/usage +``` + +The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query +parameters. Both return the same response. + +This endpoint requires the `bav:brand-data` scope. + +## Parameters + +This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +`years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or +`years` is required. + +## Response + +The response follows the [standard brandscape model schema](index.md#schema). + +### Metrics + +The data points include the metrics in the `usage` [metric group](../metrics/metric-groups.md), each with: + +- `percentage` - The percentage of respondents who fall into each usage level. +- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. diff --git a/docs/market-share/brand-shares.md b/docs/market-share/brand-shares.md new file mode 100644 index 0000000..8d69f34 --- /dev/null +++ b/docs/market-share/brand-shares.md @@ -0,0 +1,149 @@ +# Brand Shares + +The brand shares endpoint returns Euromonitor's market share for brands. Each row is one brand, in one category, +geography (market), data type and year. + +Before using this endpoint, please read the [market share overview](index.md). In particular, note +that [Euromonitor IDs are not BAV IDs](index.md#euromonitor-ids-are-not-bav-ids) and +that [null is not zero](index.md#null-is-not-zero). + +## Creating a query + +The endpoint accepts both `GET` (with query parameters) and `POST` (with a JSON body) requests. The parameters are the +same for both. + +```http request +GET /api/v2/market-share/brand-shares +POST /api/v2/market-share/brand-shares +``` + +This endpoint requires the `bav:market-share-data` scope. + +## Parameters + +All list parameters are arrays. In a query string, pass repeated values (`categories[]=1&categories[]=2`) rather than a +single comma-separated string. Each value can be either an ID or a name. When you pass a name, the system attempts to +find the matching record. If no record matches a name, the request fails with a validation error. An ID that does not +exist simply matches nothing. + +| Key | Required? | Type | Description | +|-----------------|:---------------------:|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `brands` | One narrowing filter* | array | Euromonitor brands, as Euromonitor brand IDs or names. Use the [brands catalog](catalog.md#brands) to find them. Max 50. | +| `companies` | One narrowing filter* | array | Owning companies, as Euromonitor company IDs or names. Filters the rows down to brands owned by these companies at the time of the extract. Max 50. | +| `bav_brands` | One narrowing filter* | array | [BAV brands](../brands/brands.md), as BAV brand IDs or names. Resolved to Euromonitor brands through the link held on the brand, so a brand that has not been linked matches nothing. Max 50. | +| `bav_companies` | One narrowing filter* | array | [BAV companies](../company-data/companies.md), as BAV company IDs or names. Resolved to Euromonitor companies through the link held on the company, so a company that has not been linked matches nothing. Max 50. | +| `categories` | One narrowing filter* | array | Euromonitor categories, as IDs or names. Max 50. | +| `geographies` | One narrowing filter* | array | Euromonitor geographies (markets), as IDs or names. These are not BAV countries. Use the [geographies catalog](catalog.md#geographies) to find them. Max 50. | +| `industries` | One narrowing filter* | array | Euromonitor industries, as IDs or names. Max 50. | +| `data_types` | :x: | array | What is being measured, as Euromonitor data type IDs or names. Rows that differ only by data type are not comparable, so filtering to one is usually what you want. Max 50. | +| `years` | :x: | array | The [years](../metadata/years.md), as year IDs or year numbers. A year does not narrow a query on its own and has to be combined with a narrowing filter. Max 50. | +| `score_type` | :x: | string | Which measure the `value` of each row carries. One of `actual_usd` (default), `actual_local`, `percentage` or `rank`. See [score types](#score-types). | +| `format` | :x: | string | The response format: `json` (default), `llm` (the data as CSV with instructions for use in AI prompts, see [response formats](../brandscape-models/index.md#response-formats)) or `mcp` (the response shape used by our MCP servers). | + +\* At least one of `brands`, `companies`, `bav_brands`, `bav_companies`, `categories`, `geographies` or `industries` is +required. A request without any of these is rejected with a validation error. + +### Score types + +The `score_type` parameter decides which measure each row's `value` holds: + +- `actual_usd` - The absolute value in USD at a fixed exchange rate. This is the default. +- `actual_local` - The absolute value in the market's own currency. +- `percentage` - The share of the category in that market, on a 0-100 scale. +- `rank` - The position within the category in that market, where 1 is the largest. A rank only means something when + compared against the other brands in the same category, geography, data type and year. Ranks must never be summed + or averaged. + +Not every slice carries every measure. A `null` value means that the figure was not supplied, not that it is zero. + +## Example + +To get the percentage share of a BAV brand in the United Kingdom, measured as retail value, for 2024: + +```http request +GET /api/v2/market-share/brand-shares?bav_brands[]=148&geographies[]=United%20Kingdom&data_types[]=Retail%20Value%20RSP&years[]=2024&score_type=percentage +``` + +Or as a `POST` request: + +```json +{ + "bav_brands": [148], + "geographies": ["United Kingdom"], + "data_types": ["Retail Value RSP"], + "years": [2024], + "score_type": "percentage" +} +``` + +## Schema + +The response is not paginated. It contains a `meta` object and a `data` array with one object per row. + +:::note Row limit +A query matching more than 25,000 rows is rejected with a validation error rather than truncated. Narrow the query with +a geography, category or year filter if this happens. +::: + +### Meta + +| Key | Type | Description | +|--------------|--------|-----------------------------------------------------------------| +| `source` | string | A source label suitable for captioning the data. | +| `score_type` | string | The score type that each row's `value` holds. | + +### Data + +Each entity in a row is a nested object with an `id` and a `name` (the year has an `id` and a `year`). An entity is +`null` where there is nothing to point at, such as an unlinked brand or a dimension that Euromonitor left blank. + +| Key | Type | Description | +|---------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| +| `brand` | object | The Euromonitor brand. | +| `bav_brand` | object\|null | The [BAV brand](../brands/brands.md) the Euromonitor brand is linked to. `null` when there is no link, in which case the row cannot be compared with BAV brand data. | +| `company` | object | The Euromonitor company that owns the brand. | +| `bav_company` | object\|null | The [BAV company](../company-data/companies.md) the Euromonitor company is linked to, or `null`. | +| `category` | object | The Euromonitor category. | +| `geography` | object | The Euromonitor geography (market). | +| `industry` | object | The Euromonitor industry. | +| `data_type` | object | The Euromonitor data type, i.e. what the row measures. | +| `year` | object | The [year](../metadata/years.md), with `id` and `year`. | +| `value` | number\|null | The measure requested in `score_type`. `null` means the figure was not supplied for this row. It never means zero. | +| `unit` | string\|null | What `value` is measured in: `USD`, the local currency code, or `%`. `null` for ranks. | +| `score_type` | string | The score type that `value` holds. | + +Rows that differ only by data type measure different things and should not be summed or averaged. + +```json +{ + "meta": { + "source": "Euromonitor", + "score_type": "percentage" + }, + "data": [ + { + "brand": { "id": 1234, "name": "Andrex" }, + "bav_brand": { "id": 148, "name": "Andrex" }, + "company": { "id": 567, "name": "Essity AB" }, + "bav_company": null, + "category": { "id": 89, "name": "Toilet Paper" }, + "geography": { "id": 12, "name": "United Kingdom" }, + "industry": { "id": 3, "name": "Tissue and Hygiene" }, + "data_type": { "id": 1, "name": "Retail Value RSP" }, + "year": { "id": 45, "year": 2024 }, + "value": 31.2, + "unit": "%", + "score_type": "percentage" + } + ] +} +``` + +The values in the example are illustrative. + +## Errors + +- `403` - Your account does not have access to Euromonitor market share data. +- `422` - A validation error. This is returned when no narrowing filter is provided, when a name could not be matched + to a record, or when the query matches more than 25,000 rows. The `errors` object is keyed by the filter you sent, + for example `geographies.0`, or `filters` for errors about the query as a whole. diff --git a/docs/market-share/catalog.md b/docs/market-share/catalog.md new file mode 100644 index 0000000..8e1629f --- /dev/null +++ b/docs/market-share/catalog.md @@ -0,0 +1,209 @@ +# Catalog + +## What is the catalog? + +Euromonitor keeps its own catalog of the brands, companies, categories, data types, geographies and industries that +market share is measured for. The catalog endpoints give you read-only access to these lists so that you can find the +Euromonitor IDs to pass to the [brand shares](brand-shares.md) and [company shares](company-shares.md) endpoints. + +:::note Euromonitor IDs +All IDs on these endpoints are Euromonitor's own identifiers, not BAV IDs. See +the [overview](index.md#euromonitor-ids-are-not-bav-ids) for more information. +::: + +All catalog endpoints require the `bav:market-share-data` scope. They are paginated, sorted by `id` by default and +support [filters & sorting](../customizing/filters.md), [configurable fields](../customizing/fields.md) +and [includes](../customizing/includes.md). + +Every relationship that can be included (including the `bav_` links) is returned in a slim relationship schema: + +| Key | Type | Description | +|--------|---------|--------------------------------------| +| `id` | integer | The ID of the related record. | +| `name` | string | The name of the related record. | + +A relationship that is not linked is returned as `null`. + +## Brands + +Euromonitor's own brand catalog. This is not the same list as the [BAV brands](../brands/brands.md). It covers brands +BAV has never surveyed, splits some brands that BAV holds as one, and names others differently. The `id` here is what +the `brands` filter on [brand shares](brand-shares.md) takes. + +```http request +GET /api/v2/market-share/brands +GET /api/v2/market-share/brands/123 +``` + +Where `123` is the Euromonitor ID of the brand. + +### Schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|--------------|---------|:-----------------------------------------:|:------------------:|:------------------:|------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The Euromonitor brand ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The brand name in Euromonitor. This can differ from the BAV brand name. | +| `company_id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The Euromonitor ID of the company that owns the brand. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when the record was created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when the record was last updated. | + +### Relationships & includes + +- `company` - The Euromonitor company that owns the brand. +- `bav_brand` - The [BAV brand](../brands/brands.md) this brand is linked to. `null` when there is no link, in which + case its market share cannot be compared with BAV brand data. + +## Companies + +Euromonitor's own company catalog. As with brands, this is Euromonitor's list rather than the +BAV [companies](../company-data/companies.md). The `id` here is what the `companies` filter on the share endpoints +takes. + +```http request +GET /api/v2/market-share/companies +GET /api/v2/market-share/companies/123 +``` + +Where `123` is the Euromonitor ID of the company. + +### Schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|--------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-----------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The Euromonitor company ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The company name in Euromonitor. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when the record was created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when the record was last updated. | + +### Relationships & includes + +- `brands` - The Euromonitor brands the company owns. +- `bav_company` - The [BAV company](../company-data/companies.md) this company is linked to, where there is a link. + +## Categories + +The categories that market share is measured within. Categories form a tree: `level` 1 is a top-level category within +its industry, and `parent_id` walks up from there. Filter on `level` to get one tier of the tree, or on `parent_id` to +get one category's children. + +A category's industry is not fixed for all time, as Euromonitor may reorganize its categories. Filter share rows by +category rather than treating the industry as a permanent property of a category. + +```http request +GET /api/v2/market-share/categories +GET /api/v2/market-share/categories/123 +``` + +Where `123` is the Euromonitor ID of the category. + +### Schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The Euromonitor category ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The category name. | +| `level` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The depth in the category tree, where `1` is a top-level category. | +| `industry_id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The Euromonitor ID of the industry the category is in. This can change. | +| `industry_order` | integer | :x: | :white_check_mark: | :white_check_mark: | The category's position within its industry. | +| `parent_id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The Euromonitor ID of the parent category, where there is one. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when the record was created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when the record was last updated. | + +### Relationships & includes + +- `industry` - The industry the category is in. +- `parent` - The parent category. +- `children` - The categories nested directly under this one. +- `data_types` - The data types available for this category. + +## Data Types + +What a share row measures, such as retail value or retail volume. Two rows that differ only by data type measure +different things and are not comparable. They must not be summed or averaged across. Not every data type applies to +every category, which is what the `categories` and `industries` includes describe. + +```http request +GET /api/v2/market-share/data-types +GET /api/v2/market-share/data-types/123 +``` + +Where `123` is the Euromonitor ID of the data type. + +### Schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|--------------|---------|:-----------------------------------------:|:------------------:|:------------------:|------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The Euromonitor data type ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The data type name, such as retail value or retail volume. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when the record was created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when the record was last updated. | + +### Relationships & includes + +- `categories` - The categories this data type is available for. +- `industries` - The industries this data type is available for. + +## Geographies + +The markets that market share is measured in, as a tree of regions, countries and cities. These are Euromonitor's +geographies, not the BAV [countries](../metadata/countries.md). Where a geography lines up with a BAV country, +`bav_country_id` points to it. It is `null` for regions and cities. + +```http request +GET /api/v2/market-share/geographies +GET /api/v2/market-share/geographies/123 +``` + +Where `123` is the Euromonitor ID of the geography. + +### Schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|--------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The Euromonitor geography ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The geography name. | +| `parent_id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The Euromonitor ID of the parent geography, where there is one. | +| `bav_country_id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The [BAV country](../metadata/countries.md) ID. `null` for regions and cities. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when the record was created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when the record was last updated. | + +### Additional Filters + +To take one level of the geography tree, use one of these filters. Any value turns the filter on. + +- `filter[regions]=1` - Only include regions, the top level of the tree. +- `filter[countries]=1` - Only include countries. +- `filter[cities]=1` - Only include cities. + +### Relationships & includes + +- `parent` - The parent geography. +- `children` - The geographies nested directly under this one. +- `bav_country` - The [BAV country](../metadata/countries.md) this geography is linked to. + +## Industries + +The top of the catalog. An industry holds categories and is the unit that Euromonitor data is licensed and fetched in. + +```http request +GET /api/v2/market-share/industries +GET /api/v2/market-share/industries/123 +``` + +Where `123` is the Euromonitor ID of the industry. + +### Schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|-------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|---------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The Euromonitor industry ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The industry name. | +| `code` | string | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The Euromonitor industry code. | +| `last_fetched_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when the industry's data was last fetched. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when the record was created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when the record was last updated. | + +### Relationships & includes + +- `categories` - The categories in this industry. +- `data_types` - The data types available for this industry. diff --git a/docs/market-share/company-shares.md b/docs/market-share/company-shares.md new file mode 100644 index 0000000..8a23498 --- /dev/null +++ b/docs/market-share/company-shares.md @@ -0,0 +1,92 @@ +# Company Shares + +The company shares endpoint returns Euromonitor's market share for companies. Each row is one company, in one category, +geography (market), data type and year. + +Company share is measured separately from brand share. A company's share of a category is not the sum of its brands' +shares, because brands below Euromonitor's reporting threshold are not listed individually and some share comes from +unbranded products. + +Before using this endpoint, please read the [market share overview](index.md). In particular, note +that [Euromonitor IDs are not BAV IDs](index.md#euromonitor-ids-are-not-bav-ids) and +that [null is not zero](index.md#null-is-not-zero). + +## Creating a query + +The endpoint accepts both `GET` (with query parameters) and `POST` (with a JSON body) requests. The parameters are the +same for both. + +```http request +GET /api/v2/market-share/company-shares +POST /api/v2/market-share/company-shares +``` + +This endpoint requires the `bav:market-share-data` scope. + +## Parameters + +All list parameters are arrays. In a query string, pass repeated values (`categories[]=1&categories[]=2`) rather than a +single comma-separated string. Each value can be either an ID or a name. When you pass a name, the system attempts to +find the matching record. If no record matches a name, the request fails with a validation error. An ID that does not +exist simply matches nothing. + +| Key | Required? | Type | Description | +|-----------------|:---------------------:|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `companies` | One narrowing filter* | array | Euromonitor companies, as Euromonitor company IDs or names. Use the [companies catalog](catalog.md#companies) to find them. Max 50. | +| `bav_companies` | One narrowing filter* | array | [BAV companies](../company-data/companies.md), as BAV company IDs or names. Resolved to Euromonitor companies through the link held on the company, so a company that has not been linked matches nothing. Max 50. | +| `categories` | One narrowing filter* | array | Euromonitor categories, as IDs or names. Max 50. | +| `geographies` | One narrowing filter* | array | Euromonitor geographies (markets), as IDs or names. These are not BAV countries. Use the [geographies catalog](catalog.md#geographies) to find them. Max 50. | +| `industries` | One narrowing filter* | array | Euromonitor industries, as IDs or names. Max 50. | +| `data_types` | :x: | array | What is being measured, as Euromonitor data type IDs or names. Rows that differ only by data type are not comparable, so filtering to one is usually what you want. Max 50. | +| `years` | :x: | array | The [years](../metadata/years.md), as year IDs or year numbers. A year does not narrow a query on its own and has to be combined with a narrowing filter. Max 50. | +| `score_type` | :x: | string | Which measure the `value` of each row carries. One of `actual_usd` (default), `actual_local`, `percentage` or `rank`. See [score types](brand-shares.md#score-types). | +| `format` | :x: | string | The response format: `json` (default), `llm` (the data as CSV with instructions for use in AI prompts, see [response formats](../brandscape-models/index.md#response-formats)) or `mcp` (the response shape used by our MCP servers). | + +\* At least one of `companies`, `bav_companies`, `categories`, `geographies` or `industries` is required. A request +without any of these is rejected with a validation error. + +## Example + +```json +{ + "bav_companies": [12], + "geographies": ["United Kingdom"], + "years": [2024], + "score_type": "actual_usd" +} +``` + +## Schema + +The response is not paginated. It contains a `meta` object and a `data` array with one object per row. The `meta` +object is the same as for [brand shares](brand-shares.md#meta). + +:::note Row limit +A query matching more than 25,000 rows is rejected with a validation error rather than truncated. Narrow the query with +a geography, category or year filter if this happens. +::: + +### Data + +Each entity in a row is a nested object with an `id` and a `name` (the year has an `id` and a `year`). An entity is +`null` where there is nothing to point at, such as an unlinked company or a dimension that Euromonitor left blank. + +| Key | Type | Description | +|---------------|--------------|---------------------------------------------------------------------------------------------------------------------| +| `company` | object | The Euromonitor company. | +| `bav_company` | object\|null | The [BAV company](../company-data/companies.md) the Euromonitor company is linked to, or `null` where no link exists. | +| `category` | object | The Euromonitor category. | +| `geography` | object | The Euromonitor geography (market). | +| `industry` | object | The Euromonitor industry. | +| `data_type` | object | The Euromonitor data type, i.e. what the row measures. | +| `year` | object | The [year](../metadata/years.md), with `id` and `year`. | +| `value` | number\|null | The measure requested in `score_type`. `null` means the figure was not supplied for this row. It never means zero. | +| `unit` | string\|null | What `value` is measured in: `USD`, the local currency code, or `%`. `null` for ranks. | +| `score_type` | string | The score type that `value` holds. | + +## Errors + +- `403` - Your account does not have access to Euromonitor market share data. +- `422` - A validation error. This is returned when no narrowing filter is provided, when a name could not be matched + to a record, or when the query matches more than 25,000 rows. The `errors` object is keyed by the filter you sent, + or `filters` for errors about the query as a whole. diff --git a/docs/market-share/index.md b/docs/market-share/index.md new file mode 100644 index 0000000..f65ef82 --- /dev/null +++ b/docs/market-share/index.md @@ -0,0 +1,88 @@ +--- +sidebar_label: Overview +--- + +# Market Share + +The market share endpoints give you access to Euromonitor's market share data for brands and companies, sliced by +category, geography (market), data type and year. Alongside the share data you also get Euromonitor's catalogs of +brands, companies, categories, data types, geographies and industries that the data is sliced by. + +All market share endpoints live under the `/api/v2/market-share` prefix: + +| Method | Endpoint | Description | +|--------------|--------------------------------------|-----------------------------------------------------| +| `GET` | `/api/v2/market-share/brands` | Euromonitor's brand catalog. | +| `GET` | `/api/v2/market-share/companies` | Euromonitor's company catalog. | +| `GET` | `/api/v2/market-share/categories` | Euromonitor's category tree. | +| `GET` | `/api/v2/market-share/data-types` | What a share row measures. | +| `GET` | `/api/v2/market-share/geographies` | Euromonitor's markets. | +| `GET` | `/api/v2/market-share/industries` | Euromonitor's industries. | +| `GET`/`POST` | `/api/v2/market-share/brand-shares` | Market share for brands. | +| `GET`/`POST` | `/api/v2/market-share/company-shares`| Market share for companies. | + +The catalog endpoints are documented on the [catalog](catalog.md) page, and the share data on +the [brand shares](brand-shares.md) and [company shares](company-shares.md) pages. + +## Access + +The market share endpoints require the **Market Share Data** (`bav:market-share-data`) scope on your API key or +application. See [authentication](../authentication.md#scopes) for more information on scopes. + +The scope can only be assigned by users who have access to Euromonitor data in The Fount. Access is also checked +against the user on every request, so if the user behind a token loses access to Euromonitor data, the token will +receive a `403` response even though it still holds the scope. + +## Important concepts + +Euromonitor data works differently from the BAV data in a few important ways. Please read through these before you +start building on top of the market share endpoints. + +### Euromonitor IDs are not BAV IDs + +Euromonitor keeps its own list of everything: brands, companies, categories, geographies, industries and data types. +None of these are the same as the BAV resources with similar names. The Euromonitor brand catalog covers brands that +BAV has never surveyed, splits some brands that BAV holds as one, and names others differently. Likewise, Euromonitor +geographies are not the same as the BAV [countries](../metadata/countries.md). + +Everything on the market share endpoints is Euromonitor's unless it is prefixed with `bav_`. This means that: + +- `brands`, `companies`, `categories`, `geographies`, `industries` and `data_types` always take Euromonitor IDs. +- `bav_brands` and `bav_companies` take BAV [brand](../brands/brands.md) and [company](../company-data/companies.md) + IDs. +- `bav_brand`, `bav_company` and `bav_country` in responses are the BAV records that a Euromonitor record is linked to. + +:::warning Do not mix up the IDs +A BAV ID sent where a Euromonitor ID is expected does not fail. It silently reads as another, unrelated Euromonitor +entity (or matches nothing). Always look up Euromonitor IDs using the [catalog endpoints](catalog.md) first, or use the +`bav_brands` and `bav_companies` filters when you only know the BAV ID. +::: + +### Linking to BAV + +Where a Euromonitor brand or company has been linked to a BAV brand or company, the catalog and share endpoints tell +you so through the `bav_brand` and `bav_company` fields. Only linked records can be read alongside BAV brand equity +data. Where no link exists, these fields are `null`. + +### Null is not zero + +The different measures (USD value, local currency value, percentage share and rank) arrive from Euromonitor in separate +extracts and are merged into one row. A row carrying one measure but not another is normal. + +A `null` value means that the figure was not supplied for that slice. It never means zero, and it should never be read +as the brand or company holding none of the category. + +### Data types are not comparable + +Each share row is measured as a specific [data type](catalog.md#data-types), such as retail value or retail volume. +Rows that differ only by data type measure different things. They must not be summed or averaged across. Filtering your +share queries to a single data type is usually what you want. + +### At least one narrowing filter is required + +Every share query has to name at least one entity, category, geography or industry. Without one the query would be the +whole of Euromonitor. A year on its own does not count, since every brand in every market is measured each year. See +the [brand shares](brand-shares.md) and [company shares](company-shares.md) pages for the exact filters that qualify. + +The share responses are not paginated. A query matching more than 25,000 rows is rejected with a validation error +rather than truncated. Narrow the query with a geography, category or year filter if this happens. diff --git a/docs/measures/bav-question-groups.md b/docs/measures/bav-question-groups.md new file mode 100644 index 0000000..9c2d581 --- /dev/null +++ b/docs/measures/bav-question-groups.md @@ -0,0 +1,67 @@ +# BAV Question Groups + +## What are BAV question groups? + +[BAV questions](bav-questions.md) are organized in groups, such as demographics. The groups can be used to create a +better selection experience in an interface, for example when building an [audience](../audiences/audiences.md). + +## List all BAV question groups + +To list all of the BAV question groups and browse them via the API, use the list endpoint: + +```http request +GET /api/v2/bav-question-groups +``` + +## Get a BAV question group + +You may also directly retrieve a BAV question group's details if you already have its system ID. + +```http request +GET /api/v2/bav-question-groups/123 +``` + +Where `123` is the system ID of the BAV question group. + +## Schema + +### Full response schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|---------------|---------|:-----------------------------------------:|:------------------:|:------------------:|---------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the group, for example "Demographics". | +| `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The key of the group, for example `demographics`. | +| `description` | string | :white_check_mark: | :x: | :white_check_mark: | A description of the group. | +| `created_at` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A datetime string when this group was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this group was last updated. | + +### Relationship Response Schema + +The slim relationship schema is used when the BAV question group is used as part of an include in another resource. + +| Key | Type | Description | +|---------------|---------|----------------------------------------------------------------| +| `id` | integer | The system ID for the group. | +| `name` | string | The name of the group. | +| `key` | string | The key of the group. | +| `description` | string | A description of the group. | +| `parent_id` | integer | The ID of the parent group, or null for a top-level group. | +| `created_at` | string | A datetime string when this group was first created. | +| `updated_at` | string | A datetime string when this group was last updated. | + +## Additional Filters + +For convenience, we have a set of additional filters that are not available in +the [default filters](../customizing/filters.md) or are part of the columns. These are: + +- `questions` - A comma-separated list of BAV question IDs. Only groups containing these questions are returned. + +## Relationships & includes + +By default, relationships are not included. See +the [includes section](../customizing/includes) for more information on how this works. The following relationships +are available: + +- `questions` - The [BAV questions](bav-questions.md) in the group, with their `id`, `label`, `key`, `type`, + `created_at` and `updated_at`. diff --git a/docs/measures/bav-questions.md b/docs/measures/bav-questions.md new file mode 100644 index 0000000..c9b9551 --- /dev/null +++ b/docs/measures/bav-questions.md @@ -0,0 +1,93 @@ +# BAV Questions + +## What are BAV questions? + +BAV questions are the respondent-level questions that BAV asks, such as demographics, opinions and behaviors. Unlike +[brand measures](brand-measures.md), they are asked about the respondent rather than about a brand. + +[Audiences](../audiences/audiences.md) are defined from these questions. Use these endpoints to find the questions that +you can [build an audience](../audiences/managing-audiences.md) from, and the studies that asked them. + +Questions are organized in [BAV question groups](bav-question-groups.md). + +## List all BAV questions + +To list all of the BAV questions and browse them via the API, use the list endpoint: + +```http request +GET /api/v2/bav-questions +``` + +## Get a BAV question + +You may also directly retrieve a BAV question's details if you already have its system ID. + +```http request +GET /api/v2/bav-questions/123 +``` + +Where `123` is the system ID of the BAV question. + +## Schema + +### Full response schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|--------------|---------|:-----------------------------------------:|:------------------:|:------------------:|------------------------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `label` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The label of the question, for example "Gender". The filter matches partial labels in any language. | +| `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The unique key of the question, for example `gender`. The filter matches partial keys. | +| `type` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The type of the question, which tells you how to read its answers, such as `dictionary`, `boolean` or `integer`. | +| `crt_id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The CRT ID of the question. | +| `created_at` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A datetime string when this question was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this question was last updated. | + +### Relationship Response Schema + +The slim relationship schema is used when the BAV question is used as part of another resource. + +| Key | Type | Description | +|---------|---------|------------------------------------------| +| `id` | integer | The system ID for the question. | +| `label` | string | The label of the question. | +| `key` | string | The unique key of the question. | + +## Relationships & includes + +By default, relationships are not included. See +the [includes section](../customizing/includes) for more information on how this works. The following relationships +are available: + +- `group` - The [BAV question group](bav-question-groups.md) that the question belongs to. +- `studies` - The [studies](../studies/studies.md) that asked the question. Only studies you have access to are + included. + +## Studies that asked a BAV question + +To list every study that asked a BAV question, use the studies endpoint. This is useful to check where a question has +answers before you build an audience definition with it. + +```http request +GET /api/v2/bav-questions/123/studies +``` + +Where `123` is the system ID of the BAV question. + +Only studies you have access to are listed. Fused studies take their questions from the studies they were fused from, +so they are listed under those source studies rather than on their own. + +The results are sorted by `study_id` by default. You may also sort by `id`, `created_at` and `updated_at`. + +| Key | Type | Description | +|--------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| `study` | object | The [study](../studies/studies.md) that asked the question, with its `id`, `name`, `period`, `type`, `study_type`, `study_type_label`, `country` and `year`. | +| `question` | object | The BAV question, using the relationship schema above. | +| `created_at` | string | A datetime string when this record was first created. | +| `updated_at` | string | A datetime string when this record was last updated. | + +The following filters are available: + +- `studies` - A comma-separated list of study IDs to filter by. +- `updated_since` - Only return records changed on or after this date. See [filters](../customizing/filters.md). + +To go the other way and list the questions a specific study asked, see the [study catalog](study-catalog.md). diff --git a/docs/measures/brand-measure-groups.md b/docs/measures/brand-measure-groups.md new file mode 100644 index 0000000..1141825 --- /dev/null +++ b/docs/measures/brand-measure-groups.md @@ -0,0 +1,65 @@ +# Brand Measure Groups + +## What are brand measure groups? + +[Brand measures](brand-measures.md) are organized in groups. Each group collects measures that belong together. + +## List all brand measure groups + +To list all of the brand measure groups and browse them via the API, use the list endpoint: + +```http request +GET /api/v2/brand-measure-groups +``` + +## Get a brand measure group + +You may also directly retrieve a brand measure group's details if you already have its system ID. + +```http request +GET /api/v2/brand-measure-groups/123 +``` + +Where `123` is the system ID of the brand measure group. + +## Schema + +### Full response schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|---------------|---------|:-----------------------------------------:|:------------------:|:------------------:|---------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the group. | +| `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The key of the group. | +| `description` | string | :white_check_mark: | :x: | :white_check_mark: | A description of the group. | +| `created_at` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A datetime string when this group was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this group was last updated. | + +### Relationship Response Schema + +The slim relationship schema is used when the brand measure group is used as part of an include in another resource. + +| Key | Type | Description | +|---------------|---------|--------------------------------------------------------------| +| `id` | integer | The system ID for the group. | +| `name` | string | The name of the group. | +| `key` | string | The key of the group. | +| `description` | string | A description of the group. | +| `created_at` | string | A datetime string when this group was first created. | +| `updated_at` | string | A datetime string when this group was last updated. | + +## Additional Filters + +For convenience, we have a set of additional filters that are not available in +the [default filters](../customizing/filters.md) or are part of the columns. These are: + +- `measures` - A comma-separated list of brand measure IDs. Only groups containing these measures are returned. + +## Relationships & includes + +By default, relationships are not included. See +the [includes section](../customizing/includes) for more information on how this works. The following relationships +are available: + +- `measures` - The [brand measures](brand-measures.md) in the group, with their `id`, `label`, `type`, `created_at` + and `updated_at`. diff --git a/docs/measures/brand-measures.md b/docs/measures/brand-measures.md new file mode 100644 index 0000000..fde5e9f --- /dev/null +++ b/docs/measures/brand-measures.md @@ -0,0 +1,98 @@ +# Brand Measures + +## What are brand measures? + +Brand measures are the brand-level measures in BAV studies. Most are asked about each brand directly in the survey, +while some are calculated afterwards. Each measure belongs to a [brand measure group](brand-measure-groups.md). + +Brand measures differ from [brand metrics](../metrics/metrics.md). Brand metrics are the calculated scores in +the [brandscape data](../brand-data/brandscape-data.md), while brand measures describe what is asked about a brand and +how its answers are stored. + +A measure is not asked in every study. Use the [studies endpoint](#studies-a-brand-measure-was-asked-in) to see where a +measure has data, or the [study catalog](study-catalog.md) to see which measures a specific study contains. + +## List all brand measures + +To list all of the brand measures and browse them via the API, use the list endpoint: + +```http request +GET /api/v2/brand-measures +``` + +## Get a brand measure + +You may also directly retrieve a brand measure's details if you already have its system ID. + +```http request +GET /api/v2/brand-measures/123 +``` + +Where `123` is the system ID of the brand measure. + +## Schema + +### Full response schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|------------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|--------------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `label` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The label of the measure. | +| `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The key of the measure. | +| `type` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The type of the measure, such as `boolean`, `seven_scalar` or `dictionary`. | +| `is_category_agnostic` | boolean | :x: | :x: | :white_check_mark: | Whether the measure is independent of the category the brand is measured in. | +| `crt_id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The CRT ID of the measure. | +| `in_survey` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the measure is asked directly in the survey rather than calculated afterwards. | +| `created_at` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A datetime string when this measure was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this measure was last updated. | + +### Relationship Response Schema + +The slim relationship schema is used when the brand measure is used as part of another resource. + +| Key | Type | Description | +|---------|---------|---------------------------------------------------------------------| +| `id` | integer | The system ID for the brand measure. | +| `label` | string | The label of the brand measure. | +| `key` | string | The key of the brand measure, which the data columns are named after. | + +## Relationships & includes + +By default, relationships are not included. See +the [includes section](../customizing/includes) for more information on how this works. The following relationships +are available: + +- `group` - The [brand measure group](brand-measure-groups.md) that the measure belongs to. +- `studies` - The [studies](../studies/studies.md) that the measure has been asked in. +- `options` - The answer options for the measure across all studies, each with an `id`, `value`, `label` and + `study_id`. Use the [study catalog](study-catalog.md#brand-measures-in-a-study) for the options used in one study. + +## Studies a brand measure was asked in + +To list every study that asked a brand measure, use the studies endpoint: + +```http request +GET /api/v2/brand-measures/123/studies +``` + +Where `123` is the system ID of the brand measure. + +Only studies you have access to are listed, so the same measure can return a different set of studies for a different +API key. A fused study borrows the measures of the studies it was fused from, so it is only listed here for the few +computed measures that are stored on the fused study itself. + +The results are sorted by `study_id` by default. You may also sort by `id`, `created_at` and `updated_at`. + +| Key | Type | Description | +|--------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `study` | object | The [study](../studies/studies.md) the measure was asked in, with its `id`, `name`, `period`, `type`, `study_type`, `study_type_label`, `country` and `year`. | +| `measure` | object | The brand measure, using the relationship schema above. | +| `scaling_stretch_factor` | float | The factor this study's values for the measure are multiplied by before they are compared with another study's. Null when no rescaling is applied. | +| `scaling_shift_factor` | float | The amount this study's values for the measure are shifted by before they are compared with another study's. Null when no rescaling is applied. | +| `created_at` | string | A datetime string when this record was first created. | +| `updated_at` | string | A datetime string when this record was last updated. | + +The following filters are available: + +- `studies` - A comma-separated list of study IDs to filter by. +- `updated_since` - Only return records changed on or after this date. See [filters](../customizing/filters.md). diff --git a/docs/measures/index.md b/docs/measures/index.md new file mode 100644 index 0000000..2448324 --- /dev/null +++ b/docs/measures/index.md @@ -0,0 +1,29 @@ +--- +sidebar_label: Overview +--- + +# Measures & Questions + +When BAV studies brands it asks respondents a set of questions. The API exposes these in a few different ways depending +on what you need: + +- **[Brand metrics](../metrics/metrics.md).** The calculated metrics that make up the BAV data, such as + Differentiation and Esteem. These are the columns in the [brandscape data](../brand-data/brandscape-data.md). +- **[Brand measures](brand-measures.md).** The brand-level measures in a study. These are asked for each brand in the + survey, or calculated afterwards. Brand measures are organized in [brand measure groups](brand-measure-groups.md). +- **[BAV questions](bav-questions.md).** The respondent-level questions, such as demographics, opinions and behaviors. + [Audiences](../audiences/audiences.md) are defined from these questions. BAV questions are organized + in [BAV question groups](bav-question-groups.md). + +Not every measure or question is asked in every study, and the answer options can differ between studies. Use +the [study catalog](study-catalog.md) endpoints to see what a specific study contains. + +## Access + +All of the endpoints in this section require the `bav:brand-data` scope. + +## Building audiences + +Brand measures and BAV questions can both be used as conditions when +[building your own audiences](../audiences/managing-audiences.md). Use the `bav-study-measure` metric type for a brand +measure and `bav-study-question` for a BAV question. diff --git a/docs/measures/study-catalog.md b/docs/measures/study-catalog.md new file mode 100644 index 0000000..d478067 --- /dev/null +++ b/docs/measures/study-catalog.md @@ -0,0 +1,161 @@ +--- +sidebar_label: Study Catalog +--- + +# Study Catalog + +Not every metric, measure or question is available in every study, and the answer options can differ between studies. +The study catalog endpoints tell you what a specific [study](../studies/studies.md) contains: + +- [Brand metrics](#brand-metrics-in-a-study) - The [brand metrics](../metrics/metrics.md) available in the study, with + the brandscape data columns for each. +- [Brand measures](#brand-measures-in-a-study) - The [brand measures](brand-measures.md) in the study, with the answer + options used in that study. +- [Audience questions](#audience-questions-in-a-study) - The [BAV questions](bav-questions.md) in a question group + that the study asked, with the answer options used in that study. +- [BAV questions](#bav-questions-in-a-study) - All [BAV questions](bav-questions.md) the study asked, and which study + asked each one. + +All of these endpoints require the `bav:brand-data` scope and are paginated. + +## Brand metrics in a study + +To list the brand metrics available in a study, such as Differentiation and Esteem, use: + +```http request +GET /api/v2/studies/123/brand-metrics +``` + +Where `123` is the system ID of the study. + +Only active metrics that you have access to are returned. The results are sorted by `sort_order` and `name` by +default. + +| Key | Type | Filterable | Sortable | Description | +|------------------------|---------|:--------------------------:|:------------------:|----------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | The system ID of the metric. | +| `key` | string | :white_check_mark: | :white_check_mark: | The key of the metric, for example `differentiation`. | +| `name` | string | :white_check_mark: | :white_check_mark: | The name of the metric, for example "Differentiation". | +| `description` | string | :x: | :x: | What the metric measures. | +| `group` | string | :x: | :x: | The name of the [metric group](../metrics/metric-groups.md) the metric belongs to. | +| `sort_order` | integer | :x: | :white_check_mark: | The display order of the metric within its group. | +| `is_core` | boolean | :white_check_mark: | :x: | Whether the metric is a core BAV metric measured in the survey. | +| `is_legacy` | boolean | :white_check_mark: | :x: | Whether the metric is a legacy metric kept for historical comparison. | +| `is_category_agnostic` | boolean | :x: | :x: | Whether the metric is independent of the category the brand is measured in. | +| `data_columns` | array | :x: | :x: | The brandscape data columns for the metric, one per score type. See below. | + +Each item in `data_columns` contains: + +- `score_type` - The score type: `value`, `percentile_rank`, `percentage`, `brandscape_index`, `category_index`, + `construct` or `by_study`. +- `name` - The name of the score type, for example "Rank". +- `data_column` - The name of the column in the [brandscape data](../brand-data/brandscape-data.md), for example + `differentiation_rank`. +- `description` - What the score type means. + +The following additional filters are available: + +- `group` - A comma-separated list of [metric group](../metrics/metric-groups.md) IDs to filter by. +- `updated_since` - Only return metrics updated on or after this date. See [filters](../customizing/filters.md). + +## Brand measures in a study + +To list the [brand measures](brand-measures.md) in a study, with the answer options used in that study, use: + +```http request +GET /api/v2/studies/123/brand-measures +``` + +Where `123` is the system ID of the study. + +| Key | Type | Filterable | Sortable | Description | +|------------------------|---------|:--------------------------:|:------------------:|----------------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | The system ID of the measure. | +| `key` | string | :white_check_mark: | :white_check_mark: | The key of the measure. | +| `label` | string | :white_check_mark: | :white_check_mark: | The label of the measure. | +| `survey_display_label` | string | :x: | :x: | The label shown to respondents in the survey, where it differs from `label`. | +| `group` | string | :x: | :x: | The name of the [brand measure group](brand-measure-groups.md) the measure belongs to. | +| `type` | string | :white_check_mark: | :white_check_mark: | The type of the measure, such as `boolean`, `seven_scalar` or `dictionary`. | +| `is_category_agnostic` | boolean | :x: | :x: | Whether the measure is independent of the category the brand is measured in. | +| `in_survey` | boolean | :white_check_mark: | :white_check_mark: | Whether the measure is asked directly in the survey rather than calculated afterwards. | +| `values` | array | :x: | :x: | The answer options used in this study. See [answer options](#answer-options). | + +The `updated_since` filter is also available. See [filters](../customizing/filters.md). + +## Audience questions in a study + +To list the respondent-level questions asked in a study, such as demographics and attitudes, with the answer options +used in that study, use: + +```http request +GET /api/v2/studies/123/audience-questions +``` + +Where `123` is the system ID of the study. + +Only [BAV questions](bav-questions.md) that belong to a [question group](bav-question-groups.md) are listed. Use +the [BAV questions in a study](#bav-questions-in-a-study) endpoint to list all questions. + +| Key | Type | Filterable | Sortable | Description | +|---------------------------|---------|:--------------------------:|:------------------:|-------------------------------------------------------------------------------------| +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | The system ID of the question. | +| `key` | string | :white_check_mark: | :white_check_mark: | The key of the question. | +| `label` | string | :white_check_mark: | :white_check_mark: | The label of the question. | +| `reporting_display_label` | string | :x: | :x: | The label used for this question in reports, where it differs from `label`. | +| `group` | string | :x: | :x: | The name of the [question group](bav-question-groups.md) the question belongs to. | +| `type` | string | :white_check_mark: | :white_check_mark: | The type of the question. | +| `values` | array | :x: | :x: | The answer options used in this study. See [answer options](#answer-options). | + +The `updated_since` filter is also available. See [filters](../customizing/filters.md). + +### Answer options + +The `values` field on the brand measures and audience questions endpoints lists the answer options used in the study. +Each option has a `value` (what appears in the data) and a `label` (what the value means): + +```json +[ + { + "value": 1, + "label": "Male" + }, + { + "value": 2, + "label": "Female" + } +] +``` + +The same measure or question can have different answer options in different studies, so always read the options for +the study you are working with. Boolean measures and questions without stored options use `1` (Yes) and `0` (No). + +## BAV questions in a study + +To list all of the [BAV questions](bav-questions.md) a study asked, use: + +```http request +GET /api/v2/studies/123/bav-questions +``` + +Where `123` is the system ID of the study. + +Unlike the [audience questions](#audience-questions-in-a-study) endpoint, this also lists questions that are not in a +question group, and leaves out each question's group and answer options. + +For a fused study, the questions come from the studies it was fused from. Each row names the study that asked the +question, and only studies you have access to are listed. + +The results are sorted by `measurable_id` (the question ID) by default. You may also sort by `id`, `created_at` and +`updated_at`. + +| Key | Type | Description | +|--------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| `study` | object | The [study](../studies/studies.md) that asked the question, with its `id`, `name`, `period`, `type`, `study_type`, `study_type_label`, `country` and `year`. | +| `question` | object | The BAV question, with its `id`, `label` and `key`. | +| `created_at` | string | A datetime string when this record was first created. | +| `updated_at` | string | A datetime string when this record was last updated. | + +The following filters are available: + +- `questions` - A comma-separated list of BAV question IDs to filter by. +- `updated_since` - Only return records changed on or after this date. See [filters](../customizing/filters.md). diff --git a/docs/metadata/country-indicators.md b/docs/metadata/country-indicators.md new file mode 100644 index 0000000..36c76f9 --- /dev/null +++ b/docs/metadata/country-indicators.md @@ -0,0 +1,110 @@ +# Country Indicators + +## What are country indicators? + +Country indicators are yearly macroeconomic and demographic figures for each [country](countries.md), such as +population, GDP and inflation. There is one set of indicators per country and [year](years.md). + +## List the indicators for a country + +To list all years of indicators for a country, use the list endpoint: + +```http request +GET /api/v2/countries/123/indicators +``` + +Where `123` is the system ID of the country. You may also use the country's two-letter (ISO 3166-1 alpha-2) or +three-letter (ISO 3166-1 alpha-3) code instead of the ID: + +```http request +GET /api/v2/countries/GB/indicators +``` + +## Get the indicators for a year + +You may also directly retrieve a country's indicators for a single year if you already have the system ID of +the [year](years.md). + +```http request +GET /api/v2/countries/123/indicators/45 +``` + +Where `123` is the system ID or ISO code of the country and `45` is the system ID of the year. + +## Schema + +| Key | Type | Description | +|--------------|---------|-----------------------------------------------------------------------------| +| `id` | integer | The system ID of the country indicator record. | +| `year` | object | The [year](years.md) the indicators are for, with its `id` and `year`. | +| `indicators` | array | The indicators for the year, sorted by key. See below. | +| `created_at` | string | A datetime string when this record was first created. | +| `updated_at` | string | A datetime string when this record was last updated. | + +Each item in `indicators` contains: + +- `key` - The key of the indicator. See the list below. +- `value` - The value of the indicator. Null if the figure is not available. +- `detailed_description` - A detailed description of the indicator, including its unit. +- `simple_description` - A short description of the indicator. +- `axis_label` - A label to use for the indicator on a chart axis. + +```json +{ + "key": "gdp_capita", + "value": 46125.26, + "detailed_description": "GDP per capita (Current US$)", + "simple_description": "GDP per capita", + "axis_label": "Current US$" +} +``` + +### Available indicators + +| Key | Description | +|---------------------------------------------|-----------------------------------------------------------------------------| +| `agriculture_value_added_percent_gdp` | Agriculture, forestry, and fishing, value added (% of GDP) | +| `co2_emissions_tons_per_capita` | CO2 emissions (metric tons per capita) | +| `debt_percent_gdp` | Debt in percent of GDP (annual %) | +| `exports_of_goods_services_percent_gdp` | Exports of goods and services (% of GDP) | +| `fertility_rate` | Fertility rate, total (births per woman) | +| `gdp` | GDP (Current US$) | +| `gdp_capita` | GDP per capita (Current US$) | +| `gdp_growth_annual` | GDP growth (annual %) | +| `gini` | Gini index | +| `gni` | GNI, Atlas method (current US$) | +| `gni_capita` | GNI per capita, Atlas method (current US$) | +| `high_technology_exports_percent_total` | High-technology exports (% of manufactured exports) | +| `imports_of_goods_services_percent_gdp` | Imports of goods and services (% of GDP) | +| `income_share_highest_twenty` | Income share held by highest 20% | +| `income_share_lowest_twenty` | Income share held by lowest 20% | +| `industry_value_added_percent_gdp` | Industry (including construction), value added (% of GDP) | +| `inflation_consumer_prices_annual` | Inflation, consumer prices (annual %) | +| `internet_users_pct` | Individuals using the Internet (% of population) | +| `life_expectancy` | Life expectancy at birth, total (years) | +| `market_cap_domestic_companies_percent_gdp` | Market capitalization of listed domestic companies (% of GDP) | +| `mobile_subscriptions_per_hundred` | Mobile cellular subscriptions (per 100 people) | +| `net_migration` | Net migration | +| `net_trades_goods_services` | Net trade in goods and services (BoP, current US$) | +| `population` | Population, total | +| `population_growth_annual` | Population growth (annual %) | +| `poverty_poverty_lines_percent_population` | Poverty headcount ratio at national poverty lines (% of population) | +| `prevalence_hiv_total` | Prevalence of HIV, total (% of population ages 15-49) | +| `real_interest_rate` | Real interest rate (%) | +| `revenue_excluding_grants_percent_gdp` | Revenue, excluding grants (% of GDP) | +| `services_value_added_percent_gdp` | Services, value added (% of GDP) | + +## Filtering & sorting + +The list endpoint supports the following filters: + +- `year_id` - A comma-separated list of [year](years.md) IDs. +- `updated_since` - Only return records updated on or after this date. + See [filters](../customizing/filters.md). + +You may sort by `id`, `created_at`, `updated_at`, any of the indicator keys, or by the year with `year.year`. For +example, to get the most recent year first: + +```http request +GET /api/v2/countries/GB/indicators?sort=-year.year +``` diff --git a/sidebars.js b/sidebars.js index 2f427b0..e428f2e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -42,6 +42,8 @@ const sidebars = { items: [ 'brands/brands', 'brands/collections', + 'brands/brand-tags', + 'brands/brand-variations', ], }, { @@ -72,15 +74,46 @@ const sidebars = { 'brand-data/cee-opinions', ], }, + { + type: 'category', + label: 'Brandscape Models', + items: [ + 'brandscape-models/index', + 'brandscape-models/powergrid', + 'brandscape-models/pillars', + 'brandscape-models/imagery', + 'brandscape-models/personality', + 'brandscape-models/influence', + 'brandscape-models/brand-worth', + 'brandscape-models/preferences', + 'brandscape-models/usage', + 'brandscape-models/recommendation', + 'brandscape-models/super-cx', + 'brandscape-models/agency-change-predictor', + ], + }, { type: 'category', label: 'Audiences', items: [ 'audiences/audiences', 'audiences/audience-groups', + 'audiences/managing-audiences', 'audiences/export', ], }, + { + type: 'category', + label: 'Audience Origin', + items: [ + 'audience-origin/index', + 'audience-origin/metrics', + 'audience-origin/metric-groups', + 'audience-origin/touchpoints', + 'audience-origin/frequencies', + 'audience-origin/query', + ], + }, { type: 'category', label: 'Best Countries', @@ -90,6 +123,8 @@ const sidebars = { 'best-countries/metric-groups', 'best-countries/factors', 'best-countries/country-data', + 'best-countries/models', + 'best-countries/raw-data', ], }, { @@ -100,6 +135,16 @@ const sidebars = { 'company-data/stock-prices', ], }, + { + type: 'category', + label: 'Market Share', + items: [ + 'market-share/index', + 'market-share/catalog', + 'market-share/brand-shares', + 'market-share/company-shares', + ], + }, { type: 'category', label: 'Metric Glossaries', @@ -108,6 +153,18 @@ const sidebars = { 'metrics/metric-groups', ], }, + { + type: 'category', + label: 'Measures & Questions', + items: [ + 'measures/index', + 'measures/brand-measure-groups', + 'measures/brand-measures', + 'measures/bav-question-groups', + 'measures/bav-questions', + 'measures/study-catalog', + ], + }, { type: 'category', label: 'Other Metadata', @@ -119,6 +176,7 @@ const sidebars = { 'metadata/gics-sectors', 'metadata/stock-exchanges', 'metadata/countries', + 'metadata/country-indicators', 'metadata/cities', ], }, @@ -135,13 +193,17 @@ const sidebars = { 'ai/agents', { type: 'category', - label: 'MCP Servers', + label: 'MCP Connectors', items: [ 'ai/mcp/intro', + 'ai/mcp/concepts', 'ai/mcp/access-authorization', + 'ai/mcp/connecting-clients', + 'ai/mcp/mcp-apps', 'ai/mcp/bav', 'ai/mcp/best-countries', 'ai/mcp/financial-data', + 'ai/mcp/market-share', 'ai/mcp/social' ], } From 06b7d0ce7f6137b051499974c8116f6155281201 Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Fri, 23 Oct 2026 23:18:55 +0200 Subject: [PATCH 04/23] Remove Embed from the navigation and homepage The embed pages stay published so existing links keep working. Co-Authored-By: Claude Opus 5.5 --- docusaurus.config.js | 6 ------ src/pages/index.js | 14 ++------------ 2 files changed, 2 insertions(+), 18 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 7239a19..d366399 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -80,12 +80,6 @@ const config = { position: 'left', label: 'AI', }, - { - type: 'doc', - docId: 'embed/intro', - position: 'left', - label: 'Embed', - }, { type: 'doc', docId: 'developer-tools/index', diff --git a/src/pages/index.js b/src/pages/index.js index d2fe3da..6a980b8 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -12,7 +12,7 @@ function HomepageHeader() {

BAV@WPP Developer

Integrate BAV into your workflows and applications through our API and - embed products.

+ MCP connectors.

); @@ -31,16 +31,6 @@ const features = [ ), link: '/docs/2.x/intro', }, - { - title: 'Embed', - description: ( - <> - Integrate BAV reports into your application without having to recreate everything by using our - customizable embed integrations. - - ), - link: '/docs/2.x/embed/intro', - }, { title: 'AI Agents', description: ( @@ -49,7 +39,7 @@ const features = [ applications, enabling them provide insights based on BAV data. ), - link: '/docs/2.x/embed/intro', + link: '/docs/2.x/ai/intro', } ]; From 27e05739ac292921277736547013d177d28836f6 Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Fri, 23 Oct 2026 23:27:14 +0200 Subject: [PATCH 05/23] Move the data models under Brand Data Keep brandscape data, data models and tools in one section, and explain the difference on the Brand Data overview. Co-Authored-By: Claude Opus 5.5 --- docs/best-countries/models.md | 4 +-- .../agency-change-predictor.md | 4 +-- .../brand-worth.md | 4 +-- .../index.md => brand-data/data-models.md} | 10 +++--- .../imagery.md | 4 +-- docs/brand-data/index.md | 29 +++++++++-------- .../influence.md | 4 +-- .../personality.md | 4 +-- .../pillars.md | 4 +-- .../powergrid.md | 4 +-- .../preferences.md | 4 +-- .../recommendation.md | 4 +-- .../super-cx.md | 12 +++---- .../usage.md | 4 +-- docs/market-share/brand-shares.md | 2 +- docs/market-share/company-shares.md | 2 +- sidebars.js | 32 ++++++++----------- 17 files changed, 64 insertions(+), 67 deletions(-) rename docs/{brandscape-models => brand-data}/agency-change-predictor.md (99%) rename docs/{brandscape-models => brand-data}/brand-worth.md (86%) rename docs/{brandscape-models/index.md => brand-data/data-models.md} (98%) rename docs/{brandscape-models => brand-data}/imagery.md (87%) rename docs/{brandscape-models => brand-data}/influence.md (82%) rename docs/{brandscape-models => brand-data}/personality.md (85%) rename docs/{brandscape-models => brand-data}/pillars.md (88%) rename docs/{brandscape-models => brand-data}/powergrid.md (92%) rename docs/{brandscape-models => brand-data}/preferences.md (87%) rename docs/{brandscape-models => brand-data}/recommendation.md (85%) rename docs/{brandscape-models => brand-data}/super-cx.md (87%) rename docs/{brandscape-models => brand-data}/usage.md (86%) diff --git a/docs/best-countries/models.md b/docs/best-countries/models.md index a6ed547..9c2a029 100644 --- a/docs/best-countries/models.md +++ b/docs/best-countries/models.md @@ -35,7 +35,7 @@ The parameters are sent as a JSON body. List parameters are arrays, and each val | `countries` | :x: (defaults to all) | array | The [countries](../metadata/countries.md) to read, by country ID, two- or three-letter ISO code, or name. Returns every country measured in the year when left out. | | `audiences` | :x: (defaults to All Adults) | array | The [audiences](../audiences/audiences.md) to read, by audience ID or name. | | `scoreType` | :x: (depends on the model) | string | The score type. See [score types](#score-types). | -| `format` | :x: (defaults to `json`) | string | The response format: `json`, `llm` or `mcp`. See [response formats](../brandscape-models/index.md#response-formats). | +| `format` | :x: (defaults to `json`) | string | The response format: `json`, `llm` or `mcp`. See [response formats](../brand-data/data-models.md#response-formats). | ### City models @@ -47,7 +47,7 @@ The city models take the same parameters as the country models, but with `cities | `cities` | :x: (defaults to all) | array | The [cities](../metadata/cities.md) to read, by city ID or name. Returns every city measured in the year when left out. | | `audiences` | :x: (defaults to All Adults) | array | The [audiences](../audiences/audiences.md) to read, by audience ID or name. | | `scoreType` | :x: (depends on the model) | string | The score type. See [score types](#score-types). | -| `format` | :x: (defaults to `json`) | string | The response format: `json`, `llm` or `mcp`. See [response formats](../brandscape-models/index.md#response-formats). | +| `format` | :x: (defaults to `json`) | string | The response format: `json`, `llm` or `mcp`. See [response formats](../brand-data/data-models.md#response-formats). | ### Score types diff --git a/docs/brandscape-models/agency-change-predictor.md b/docs/brand-data/agency-change-predictor.md similarity index 99% rename from docs/brandscape-models/agency-change-predictor.md rename to docs/brand-data/agency-change-predictor.md index 336f1f3..22b3c77 100644 --- a/docs/brandscape-models/agency-change-predictor.md +++ b/docs/brand-data/agency-change-predictor.md @@ -18,7 +18,7 @@ The Fount. ## Parameters -The ACP takes the same filters as the [brandscape models](index.md#parameters), apart from `benchmarks` and `format`. +The ACP takes the same filters as the [data models](data-models.md#parameters), apart from `benchmarks` and `format`. The filters can be passed as arrays (`brands[]=148&brands[]=149`) or, for backwards compatibility, as comma-separated lists (`brands=148,149`). @@ -29,7 +29,7 @@ lists (`brands=148,149`). | `countries` | At least one* | array | [Country](../metadata/countries.md) IDs, codes or names. | | `years` | At least one* | array | [Year](../metadata/years.md) IDs or year numbers. | | `audiences` | :x: (defaults to All Adults) | array | [Audience](../audiences/audiences.md) IDs or names. | -| `study_types` | :x: (defaults to `syndicated`) | array | The kinds of study that a `countries` and `years` filter may resolve to. See [brandscape models](index.md#parameters). | +| `study_types` | :x: (defaults to `syndicated`) | array | The kinds of study that a `countries` and `years` filter may resolve to. See [data models](data-models.md#parameters). | | `category` | :x: | integer | Only include brands in this [category](../studies/categories.md) ID. | | `search` | :x: | string | Search brands by name. | | `customWeights` | :x: | object | Custom weights for the checks, keyed by check name. See [custom weights](#custom-weights). | diff --git a/docs/brandscape-models/brand-worth.md b/docs/brand-data/brand-worth.md similarity index 86% rename from docs/brandscape-models/brand-worth.md rename to docs/brand-data/brand-worth.md index 90bb8ac..c2b0043 100644 --- a/docs/brandscape-models/brand-worth.md +++ b/docs/brand-data/brand-worth.md @@ -21,13 +21,13 @@ This endpoint requires the `bav:brand-data` scope. ## Parameters -This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +This endpoint takes the [shared data model parameters](data-models.md#parameters): `brands`, `studies`, `countries`, `years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or `years` is required. ## Response -The response follows the [standard brandscape model schema](index.md#schema). +The response follows the [standard data model schema](data-models.md#schema). ### Metrics diff --git a/docs/brandscape-models/index.md b/docs/brand-data/data-models.md similarity index 98% rename from docs/brandscape-models/index.md rename to docs/brand-data/data-models.md index 0514996..f362606 100644 --- a/docs/brandscape-models/index.md +++ b/docs/brand-data/data-models.md @@ -1,10 +1,10 @@ --- -sidebar_label: Overview +sidebar_label: Data Models --- -# Brandscape Models +# Data Models -The brandscape model endpoints return the data behind the core BAV data models, such as the Powergrid, Pillars and +The data model endpoints return the data behind the core BAV data models, such as the Powergrid, Pillars and Imagery. Rather than having to know which [brand metrics](../metrics/metrics.md) make up each model, you ask for the model and get back the relevant metrics for each brand, together with the brand, study, audience and category they belong to. @@ -29,7 +29,7 @@ the [Super CX](super-cx.md) page. The [Agency Change Predictor](agency-change-predictor.md) is built on the same filters, but returns its own response. -All brandscape model endpoints require the **BAV Brand Data** (`bav:brand-data`) scope. +All data model endpoints require the **BAV Brand Data** (`bav:brand-data`) scope. ## Category specific and category agnostic models @@ -53,7 +53,7 @@ GET /api/v2/tools/pillars?brands[]=148&countries[]=US&years[]=2025 ## Parameters -All brandscape model endpoints share the same set of parameters. +All data model endpoints share the same set of parameters. List parameters are arrays. In a query string, pass repeated values (`brands[]=148&brands[]=149`). Each value can be either an ID or a name. When you pass a name, the system will attempt to find the right record based on the similarity diff --git a/docs/brandscape-models/imagery.md b/docs/brand-data/imagery.md similarity index 87% rename from docs/brandscape-models/imagery.md rename to docs/brand-data/imagery.md index 49abf5e..53695d3 100644 --- a/docs/brandscape-models/imagery.md +++ b/docs/brand-data/imagery.md @@ -23,13 +23,13 @@ This endpoint requires the `bav:brand-data` scope. ## Parameters -This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +This endpoint takes the [shared data model parameters](data-models.md#parameters): `brands`, `studies`, `countries`, `years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or `years` is required. ## Response -The response follows the [standard brandscape model schema](index.md#schema). +The response follows the [standard data model schema](data-models.md#schema). ### Metrics diff --git a/docs/brand-data/index.md b/docs/brand-data/index.md index a25e1df..b05176e 100644 --- a/docs/brand-data/index.md +++ b/docs/brand-data/index.md @@ -1,17 +1,20 @@ # Overview -While the core of BAV is the [brandscape data](brandscape-data.md) and the metrics within, the metrics are -often used in specific ways. Either by combining a set of metrics together to tell a specific story, or to do some -further mathematical work on the data to arrive at new insights. This is what each tool within BAV and its TurboPitch -suite does. - -The other endpoints in the API correspond to each "data model" in BAV. Each response is -slightly different, based on the data. The data returned includes, where applicable, brandscape data, calculated data -and all relevant wording. - -Each endpoint documentation will show you which parameters each endpoint takes and what the response will look like. -However, we suggest that you also try each tool in the graphical interface on The Fount to get a better understanding of -the results. +The brand data endpoints give you access to BAV's research data on brands. They come in three kinds: + +- **[Brandscape data](brandscape-data.md)** is the raw data: every metric for each brand, study and audience. Use it when + you want full control over which metrics you use and how you combine them. +- **[Data models](data-models.md)** return the metrics behind one of the core BAV models, such as the + [Powergrid](powergrid.md), [Pillars](pillars.md) or [Imagery](imagery.md). You ask for the model, and get back the + relevant metrics for each brand, without needing to know which metrics make it up. All data models share the same + parameters and response. +- **Tools** do further work on the data, such as combining metrics to tell a specific story or running calculations to + arrive at new insights. They correspond to the tools in The Fount and its TurboPitch suite, such as the + [Commitment Funnel](commitment-funnel.md), [SWOT](swot.md) or [Agency Change Predictor](agency-change-predictor.md). + Each tool has its own parameters and response. + +Each endpoint page shows which parameters it takes and what the response looks like. We also suggest that you try each +tool in The Fount to get a better understanding of the results. ## Access @@ -22,7 +25,7 @@ access to that tool in The Fount; otherwise a `403` response is returned. Most tool endpoints take comma-separated lists of IDs, for example `brands=148,149`. Where a page lists a parameter as taking a single ID, only one value is accepted. The [Commitment Funnel](commitment-funnel.md) instead follows the -[brandscape data models](brandscape-data.md) and takes array parameters (`brands[]=148&brands[]=149`), which also accept +[data models](data-models.md) and takes array parameters (`brands[]=148&brands[]=149`), which also accept names, and can select studies by `countries` and `years`. Unless stated otherwise, the `audiences` parameter defaults to All Adults (audience ID `1`), and responses are returned diff --git a/docs/brandscape-models/influence.md b/docs/brand-data/influence.md similarity index 82% rename from docs/brandscape-models/influence.md rename to docs/brand-data/influence.md index 0d4ea98..1028eb0 100644 --- a/docs/brandscape-models/influence.md +++ b/docs/brand-data/influence.md @@ -17,13 +17,13 @@ This endpoint requires the `bav:brand-data` scope. ## Parameters -This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +This endpoint takes the [shared data model parameters](data-models.md#parameters): `brands`, `studies`, `countries`, `years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or `years` is required. ## Response -The response follows the [standard brandscape model schema](index.md#schema). +The response follows the [standard data model schema](data-models.md#schema). ### Metrics diff --git a/docs/brandscape-models/personality.md b/docs/brand-data/personality.md similarity index 85% rename from docs/brandscape-models/personality.md rename to docs/brand-data/personality.md index c20d4cf..a5a6704 100644 --- a/docs/brandscape-models/personality.md +++ b/docs/brand-data/personality.md @@ -20,13 +20,13 @@ This endpoint requires the `bav:brand-data` scope. ## Parameters -This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +This endpoint takes the [shared data model parameters](data-models.md#parameters): `brands`, `studies`, `countries`, `years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or `years` is required. ## Response -The response follows the [standard brandscape model schema](index.md#schema). +The response follows the [standard data model schema](data-models.md#schema). ### Metrics diff --git a/docs/brandscape-models/pillars.md b/docs/brand-data/pillars.md similarity index 88% rename from docs/brandscape-models/pillars.md rename to docs/brand-data/pillars.md index 58a1802..b4a83a3 100644 --- a/docs/brandscape-models/pillars.md +++ b/docs/brand-data/pillars.md @@ -26,13 +26,13 @@ This endpoint requires the `bav:brand-data` scope. ## Parameters -This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +This endpoint takes the [shared data model parameters](data-models.md#parameters): `brands`, `studies`, `countries`, `years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or `years` is required. ## Response -The response follows the [standard brandscape model schema](index.md#schema). +The response follows the [standard data model schema](data-models.md#schema). ### Metrics diff --git a/docs/brandscape-models/powergrid.md b/docs/brand-data/powergrid.md similarity index 92% rename from docs/brandscape-models/powergrid.md rename to docs/brand-data/powergrid.md index ccb9be7..47a3a19 100644 --- a/docs/brandscape-models/powergrid.md +++ b/docs/brand-data/powergrid.md @@ -36,13 +36,13 @@ This endpoint requires the `bav:brand-data` scope. ## Parameters -This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +This endpoint takes the [shared data model parameters](data-models.md#parameters): `brands`, `studies`, `countries`, `years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or `years` is required. ## Response -The response follows the [standard brandscape model schema](index.md#schema). +The response follows the [standard data model schema](data-models.md#schema). ### Metrics diff --git a/docs/brandscape-models/preferences.md b/docs/brand-data/preferences.md similarity index 87% rename from docs/brandscape-models/preferences.md rename to docs/brand-data/preferences.md index 02119c0..9ff09f0 100644 --- a/docs/brandscape-models/preferences.md +++ b/docs/brand-data/preferences.md @@ -27,13 +27,13 @@ This endpoint requires the `bav:brand-data` scope. ## Parameters -This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +This endpoint takes the [shared data model parameters](data-models.md#parameters): `brands`, `studies`, `countries`, `years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or `years` is required. ## Response -The response follows the [standard brandscape model schema](index.md#schema). +The response follows the [standard data model schema](data-models.md#schema). ### Metrics diff --git a/docs/brandscape-models/recommendation.md b/docs/brand-data/recommendation.md similarity index 85% rename from docs/brandscape-models/recommendation.md rename to docs/brand-data/recommendation.md index a8ab646..241f767 100644 --- a/docs/brandscape-models/recommendation.md +++ b/docs/brand-data/recommendation.md @@ -20,13 +20,13 @@ This endpoint requires the `bav:brand-data` scope. ## Parameters -This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +This endpoint takes the [shared data model parameters](data-models.md#parameters): `brands`, `studies`, `countries`, `years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or `years` is required. ## Response -The response follows the [standard brandscape model schema](index.md#schema). +The response follows the [standard data model schema](data-models.md#schema). ### Metrics diff --git a/docs/brandscape-models/super-cx.md b/docs/brand-data/super-cx.md similarity index 87% rename from docs/brandscape-models/super-cx.md rename to docs/brand-data/super-cx.md index 635776c..0db49ec 100644 --- a/docs/brandscape-models/super-cx.md +++ b/docs/brand-data/super-cx.md @@ -6,11 +6,11 @@ Heart and X Factor components, which in turn are built from a set of underlying Super CX is category specific. The category should always be shown together with the brand, as it can significantly change the interpretation of the results. -There are two ways to get Super CX data: the brandscape model endpoint and the Super CX tool endpoint. We recommend the -brandscape model endpoint for new integrations, as it shares its parameters and response with the -other [brandscape models](index.md). +There are two ways to get Super CX data: the data model endpoint and the Super CX tool endpoint. We recommend the +data model endpoint for new integrations, as it shares its parameters and response with the +other [data models](data-models.md). -## Brandscape model +## Data model ### Creating a query @@ -22,13 +22,13 @@ This endpoint requires the `bav:brand-data` scope. ### Parameters -This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +This endpoint takes the [shared data model parameters](data-models.md#parameters): `brands`, `studies`, `countries`, `years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or `years` is required. ### Response -The response follows the [standard brandscape model schema](index.md#schema). The data points include the metrics in +The response follows the [standard data model schema](data-models.md#schema). The data points include the metrics in the `super-cx` [metric group](../metrics/metric-groups.md). ## Super CX tool diff --git a/docs/brandscape-models/usage.md b/docs/brand-data/usage.md similarity index 86% rename from docs/brandscape-models/usage.md rename to docs/brand-data/usage.md index dab7653..3b38425 100644 --- a/docs/brandscape-models/usage.md +++ b/docs/brand-data/usage.md @@ -27,13 +27,13 @@ This endpoint requires the `bav:brand-data` scope. ## Parameters -This endpoint takes the [shared brandscape model parameters](index.md#parameters): `brands`, `studies`, `countries`, +This endpoint takes the [shared data model parameters](data-models.md#parameters): `brands`, `studies`, `countries`, `years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or `years` is required. ## Response -The response follows the [standard brandscape model schema](index.md#schema). +The response follows the [standard data model schema](data-models.md#schema). ### Metrics diff --git a/docs/market-share/brand-shares.md b/docs/market-share/brand-shares.md index 8d69f34..95fce35 100644 --- a/docs/market-share/brand-shares.md +++ b/docs/market-share/brand-shares.md @@ -38,7 +38,7 @@ exist simply matches nothing. | `data_types` | :x: | array | What is being measured, as Euromonitor data type IDs or names. Rows that differ only by data type are not comparable, so filtering to one is usually what you want. Max 50. | | `years` | :x: | array | The [years](../metadata/years.md), as year IDs or year numbers. A year does not narrow a query on its own and has to be combined with a narrowing filter. Max 50. | | `score_type` | :x: | string | Which measure the `value` of each row carries. One of `actual_usd` (default), `actual_local`, `percentage` or `rank`. See [score types](#score-types). | -| `format` | :x: | string | The response format: `json` (default), `llm` (the data as CSV with instructions for use in AI prompts, see [response formats](../brandscape-models/index.md#response-formats)) or `mcp` (the response shape used by our MCP servers). | +| `format` | :x: | string | The response format: `json` (default), `llm` (the data as CSV with instructions for use in AI prompts, see [response formats](../brand-data/data-models.md#response-formats)) or `mcp` (the response shape used by our MCP servers). | \* At least one of `brands`, `companies`, `bav_brands`, `bav_companies`, `categories`, `geographies` or `industries` is required. A request without any of these is rejected with a validation error. diff --git a/docs/market-share/company-shares.md b/docs/market-share/company-shares.md index 8a23498..3c13fc6 100644 --- a/docs/market-share/company-shares.md +++ b/docs/market-share/company-shares.md @@ -40,7 +40,7 @@ exist simply matches nothing. | `data_types` | :x: | array | What is being measured, as Euromonitor data type IDs or names. Rows that differ only by data type are not comparable, so filtering to one is usually what you want. Max 50. | | `years` | :x: | array | The [years](../metadata/years.md), as year IDs or year numbers. A year does not narrow a query on its own and has to be combined with a narrowing filter. Max 50. | | `score_type` | :x: | string | Which measure the `value` of each row carries. One of `actual_usd` (default), `actual_local`, `percentage` or `rank`. See [score types](brand-shares.md#score-types). | -| `format` | :x: | string | The response format: `json` (default), `llm` (the data as CSV with instructions for use in AI prompts, see [response formats](../brandscape-models/index.md#response-formats)) or `mcp` (the response shape used by our MCP servers). | +| `format` | :x: | string | The response format: `json` (default), `llm` (the data as CSV with instructions for use in AI prompts, see [response formats](../brand-data/data-models.md#response-formats)) or `mcp` (the response shape used by our MCP servers). | \* At least one of `companies`, `bav_companies`, `categories`, `geographies` or `industries` is required. A request without any of these is rejected with a validation error. diff --git a/sidebars.js b/sidebars.js index e428f2e..34dfb94 100644 --- a/sidebars.js +++ b/sidebars.js @@ -60,36 +60,30 @@ const sidebars = { items: [ 'brand-data/index', 'brand-data/brandscape-data', + 'brand-data/data-models', + 'brand-data/agency-change-predictor', 'brand-data/archetypes', 'brand-data/brand-personality-match', 'brand-data/brand-vulnerability-map', + 'brand-data/brand-worth', 'brand-data/brand-worth-map', 'brand-data/category-worth-map', + 'brand-data/cee-opinions', 'brand-data/commitment-funnel', 'brand-data/cost-of-entry', + 'brand-data/imagery', + 'brand-data/influence', 'brand-data/love-plus', 'brand-data/partnership-exchange-map', + 'brand-data/personality', + 'brand-data/pillars', + 'brand-data/powergrid', + 'brand-data/preferences', + 'brand-data/recommendation', + 'brand-data/super-cx', 'brand-data/swot', 'brand-data/toplist-market', - 'brand-data/cee-opinions', - ], - }, - { - type: 'category', - label: 'Brandscape Models', - items: [ - 'brandscape-models/index', - 'brandscape-models/powergrid', - 'brandscape-models/pillars', - 'brandscape-models/imagery', - 'brandscape-models/personality', - 'brandscape-models/influence', - 'brandscape-models/brand-worth', - 'brandscape-models/preferences', - 'brandscape-models/usage', - 'brandscape-models/recommendation', - 'brandscape-models/super-cx', - 'brandscape-models/agency-change-predictor', + 'brand-data/usage', ], }, { From 75f218b9b275577fda0d6044b70e39fd591afbff Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Fri, 23 Oct 2026 23:27:14 +0200 Subject: [PATCH 06/23] Document authentication with applications, API keys and OAuth 2 Co-Authored-By: Claude Opus 5.5 --- docs/ai/mcp/access-authorization.md | 41 +-- docs/authentication.md | 457 +++++++++++++++++++++++++--- 2 files changed, 437 insertions(+), 61 deletions(-) diff --git a/docs/ai/mcp/access-authorization.md b/docs/ai/mcp/access-authorization.md index e363845..b436dc7 100644 --- a/docs/ai/mcp/access-authorization.md +++ b/docs/ai/mcp/access-authorization.md @@ -47,7 +47,9 @@ The servers support the discovery and registration mechanisms in the MCP specifi - **Dynamic client registration:** Clients can register themselves using the registration endpoint, so you do not need to create an OAuth client up front. -The authorization code grant is used with PKCE (`S256`), and refresh tokens are supported. +MCP clients use the authorization code grant with PKCE (`S256`), and refresh tokens are supported. Dynamic client +registration is only available to MCP clients. OAuth clients that you create for an application in The Fount are +confidential clients with a client secret, see [OAuth 2](../../authentication.md#oauth-2). ### Personal Access Tokens @@ -64,19 +66,20 @@ Authorization: Bearer YOUR_API_KEY ### Applications -If you are building an application for the group, we can set you up with an application. Applications can -authenticate in a few different ways: +If you are building an application, you can create one yourself under **Applications** in the +[API section in The Fount](https://fount.wppbav.com/api). Applications can authenticate in a few different ways: - **OAuth on behalf of a user:** Users authorize your application through the OAuth flow, and your application acts on their behalf with their permissions. -- **Application tokens:** An access token belonging to the application itself. Requests are made as the application. -- **Client credentials:** Applications approved for it can request a token using the OAuth client credentials grant. - This works like an application token. +- **Application API keys:** An API key belonging to the application itself. Requests are made as the application's own + user, with the access an administrator has set up for it. +- **Client credentials:** A token requested with the OAuth client credentials grant. It works like an application API + key, is limited to the client's scopes and lasts one hour. -Applications that have been approved to act on behalf of users can pass the e-mail address of the user in the -`X-Act-As-User` header together with an application token or a client credentials token. The token must explicitly -include the `act-as-user` scope. The request is then made as that user, with their permissions. The legacy -`X-User-Email` header is still accepted but we recommend moving to `X-Act-As-User`. +Applications that we have marked as trusted and approved to act on behalf of users can pass the e-mail address of a +user in the `X-Act-As-User` header, together with an application API key or a client credentials token. The token must +explicitly include the `act-as-user` scope. The request is then made as that user, with their permissions. The legacy +`X-User-Email` header is still accepted, but we recommend moving to `X-Act-As-User`. ``` Authorization: Bearer YOUR_APPLICATION_TOKEN @@ -84,17 +87,17 @@ X-Act-As-User: jane.doe@wpp.com ``` :::note -Tokens issued to a user through OAuth cannot act as another user. The `X-Act-As-User` header is only accepted with -application tokens. +Tokens issued to a user, whether through OAuth or as a personal access token, can't act as another user. The only +exception is legacy tokens with the `bav:auto-login` system scope. ::: -Applications can be restricted to only accept requests from a set of allow-listed IP addresses. When an application -has an IP allow-list, every request it makes, whether for itself or on behalf of a user, must come from one of those -addresses. This also applies when requesting a token with the client credentials grant. +Applications can use two separate IP lists: -For internal applications it is possible to skip the consent screen by having your application specifically -allow-listed as a trusted application. Consent is only skipped when the request comes from one of the application's -allow-listed IP addresses. We recommend this approach for internal tools as it provides a smoother user experience. -Please reach out if you would like to have your application set up. +- **Allowed API IP addresses** restrict where API and MCP calls can come from. When set, every request the application + makes, whether as itself or on behalf of a user, must come from one of those addresses. This also applies when + requesting a token with the client credentials grant. +- **Trusted IP addresses** are used for trusted internal applications to skip the consent screen. Consent is only + skipped when the user's browser is on one of these addresses. We recommend this for internal tools as it gives a + smoother experience. Please reach out if you would like your application to be trusted. See the [authentication documentation](../../authentication.md) for more information on applications and tokens. diff --git a/docs/authentication.md b/docs/authentication.md index c92b73f..015f775 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -1,61 +1,432 @@ # Authentication -The API has two means of access, depending on your use-case: Personal Access Tokens and Application Access. Personal -Access Tokens are the easiest way to get started with the API. +Every API request, except the [health check](health-check.md), needs an access token. You send it in the +`Authorization` header using the `Bearer` scheme: + +```bash +curl https://fount.wppbav.com/api/v2/brands \ + -H "Accept: application/json" \ + -H "Authorization: Bearer YOUR_TOKEN" +``` + +There are a few ways to get a token, depending on who the request should be made as. :::caution -Please take care not to share your API keys with anyone. All API keys should -be treated as sensitive. Make sure it is not visible in any code you share publicly, committed to any repositories or -otherwise exposed. +Please take care not to share your API keys, client secrets or access tokens with anyone. They should all be treated as +sensitive. Make sure they are not visible in any code you share publicly, committed to any repositories or otherwise +exposed. ::: -## Personal Access Tokens +## Choosing a method + +| Method | The request is made as | How you get it | Typical use | +|-----------------------------------------------------------|------------------------------------------------|------------------------------------------------------------------------|-----------------------------------------------------------------------------| +| [Personal access token](#personal-access-tokens) | You | Create it in the [API section in The Fount](https://fount.wppbav.com/api) | Scripts, notebooks and data pipelines that you run yourself. | +| [Application API key](#application-api-keys) | The application | Create it on the application's page | Back-end integrations that use the application's own access. | +| [OAuth client credentials](#client-credentials-flow) | The application | Exchange a client ID and secret for a short-lived token | Machine-to-machine integrations that prefer OAuth over a long-lived key. | +| [OAuth authorization code](#authorization-code-flow) | A user who has authorized your application | The user signs in and approves your application | Applications where people sign in and see the data they have access to. | +| [Acting on behalf of users](#acting-on-behalf-of-users) | Any user, named in the `X-Act-As-User` header | An application key or client credentials token, approved by us | Trusted internal platforms that have already signed the user in. | + +Personal access tokens are the easiest way to get started. When you build something that other people will use, create +an [application](#applications) instead. + +Whichever method you use, the request has the permissions and data access of the account it is made as, and the token +must have the [scope](#scopes) the endpoint requires. -Personal Access Tokens are the easiest way to get started with the API. They allow you to make API requests on your own -account without requiring you to build a full OAuth flow. Personal Access Tokens can be created and managed from -the [API section in The Fount](https://fount.wppbav.com/api). +## Personal access tokens -When using a personal access token to authenticate to the API, you should use the `Bearer` authentication scheme. For -example: +A personal access token lets you call the API as yourself, without building an OAuth flow. Anything you can see in +The Fount, you can see through the API. + +You create and manage your tokens under **Personal API Keys** in the +[API section in The Fount](https://fount.wppbav.com/api). When you create a key, you: + +- **Give it a name** so you can recognize it later. +- **Choose an expiration** of 7, 30, 60 or 90 days. We strongly recommend that your keys expire. +- **Choose its scopes.** You can only pick the scopes for datasets you have access to. See [scopes](#scopes). + +The key is only shown once, right after you create it, so store it somewhere safe. + +From the list of keys, you can: + +- **Regenerate** a key. This replaces it with a new key that has the same name, scopes and expiry date. The old key + stops working immediately. +- **Revoke** a key. This deletes it and it stops working immediately. + +We e-mail you seven days before one of your keys expires, and again on the day it expires. ```bash -curl https://fount.wppbav.com/api/v2/brands -H "Authorization: Bearer TOKEN" +curl https://fount.wppbav.com/api/v2/brands \ + -H "Accept: application/json" \ + -H "Authorization: Bearer 1|AbCdEfGhIjKlMnOpQrStUvWxYz0123456789" ``` -## Application Access +## Applications + +An application represents an integration, such as an internal tool, a data platform or an AI agent. You create it in +the [API section in The Fount](https://fount.wppbav.com/api) under **Applications**. Once you have an application, it +can: -When you want to integrate BAV into your own application, you will want to use our application access flow. This is a -full OAuth 2 compatible authentication flow that allows you to act on behalf of a given user who needs to authorize your -application. +- call the API as itself, with [API keys](#application-api-keys) or the [client credentials flow](#client-credentials-flow); +- let users sign in and authorize it through the [authorization code flow](#authorization-code-flow), and then call the + API on their behalf; +- [act on behalf of users](#acting-on-behalf-of-users) without a sign-in, once it has been approved for it. -This flow is currently in beta. [Contact us](mailto:support@bernskiold.com) for more information. +### Members and roles -:::note Embedding The Fount into your application -If you want to be able to use our The Fount tools from within your application we allow a special embed integration that -lets you: +Whoever creates an application becomes its owner. Owners and admins can add other existing users to the application +by their e-mail address, and give each of them a role: -- Embed the The Fount tools into your application without our application frame. -- Pass filtered parameters straight to the tool from your application to skip the query flow. -- Pre-authorize a user to bypass the need to login twice. +| Role | Can | +|-----------|-----------------------------------------------------------------------------------------------------------| +| Owner | Everything, including deleting the application and giving or removing the Owner role. | +| Admin | Edit the application's settings, manage its members, create and delete OAuth clients, and manage API keys. | +| Developer | Edit existing OAuth clients and manage the application's API keys. | +| Viewer | View the application's details. | -The embed integration offers you an easy way to integrate The Fount tools into your application without having to build -out integrations for each tool using the API. +An application always keeps at least one owner. Only an owner can give, change or take away the Owner role. + +### The application's own user + +Every application has its own user, which you can see as **Acts as** on the application's page. When the application +calls the API as itself, the request is made as this user. Its roles, agency and data access decide what the +application can see, in the same way as for a person. + +A new application's user starts with only basic access. An administrator sets up the access it needs. +[Contact us](mailto:support@bernskiold.com) to have access added to your application. + +This user can't be used to sign in to The Fount. + +### Application API keys + +An application API key works like a personal access token, but the request is made as the application. Owners, admins +and developers manage the keys under **API Keys** on the application's page, in the same way as +[personal access tokens](#personal-access-tokens). The scopes you can pick follow the access the application has been +given, not your own. + +Expiry e-mails for an application's keys go to its owners, admins and developers. + +```bash +curl https://fount.wppbav.com/api/v2/brands \ + -H "Accept: application/json" \ + -H "Authorization: Bearer 2|ZyXwVuTsRqPoNmLkJiHgFeDcBa9876543210" +``` + +:::note Service accounts +Applications replace service accounts. Every service account has been converted to an application, with the +account as the application's own user. Tokens issued to a service account keep working, with the same access, and are +now managed as the application's API keys. ::: +### OAuth clients + +To use OAuth, an application needs a client. Owners and admins create clients under **Clients** on the application's +page. There are two kinds: + +- **Authorization code clients** let users authorize your application. You give the client one or more **Redirect + URLs**, one per line, and users are only sent back to those URLs. +- **Client credentials clients** let the application request tokens for itself. You choose the scopes the client may be + issued. This kind of client is only available once we have enabled the client credentials flow for your application. + +When you create a client, you get a **Client ID** and a **Client Secret**. The secret is only shown once. You can +**Rotate Secret** on a client at any time, and the old secret stops working immediately. Deleting a client revokes +every token it has issued. + +Clients created in The Fount are confidential clients. They have a secret, which must be kept on your server. + +### Restricting where API calls come from + +You can limit the IP addresses an application calls the API from, under **Allowed API IP Addresses** when you edit the +application. Enter one IP address or CIDR range per line, such as `203.0.113.10` or `198.51.100.0/24`. + +The allow-list covers every request the application makes: + +- requests with its API keys; +- requests with client credentials tokens, and the token request itself; +- requests with OAuth tokens that users have issued to it; +- requests where it acts on behalf of users. + +A request from any other address gets a `403` error. If the list is empty, the application can call the API from +anywhere. + +## OAuth 2 + +The Fount is an OAuth 2 authorization server. Use these endpoints: + +| Endpoint | Method | Used for | +|-----------------------------------------------|--------|--------------------------------------------------------------| +| `https://fount.wppbav.com/oauth/authorize` | `GET` | Sending the user to sign in and authorize your application. | +| `https://fount.wppbav.com/oauth/token` | `POST` | Getting an access token, refreshing it, or client credentials. | +| `https://fount.wppbav.com/oauth/userinfo` | `GET` | Getting the profile of the user who authorized the token. | + +Request scopes as a space-separated list in the `scope` parameter, for example +`scope=bav:shared-resources bav:brand-data`. See [scopes](#scopes) for what is available. The `*` scope is ignored in +the authorization code flow. + +### Authorization code flow + +Use this flow when people sign in to your application with their WPP account and you want to call the API as them. The +request then has their permissions and data access. + +**1. Send the user to the authorization endpoint.** + +``` +https://fount.wppbav.com/oauth/authorize + ?client_id=9f1c2e4a-1234-4b5c-8d6e-0123456789ab + &redirect_uri=https://app.example.com/oauth/callback + &response_type=code + &scope=bav:shared-resources bav:brand-data profile + &state=RANDOM_STATE + &code_challenge=CODE_CHALLENGE + &code_challenge_method=S256 +``` + +The `redirect_uri` must match one of the client's redirect URLs exactly. Use `state` to protect against cross-site +request forgery and check it when the user comes back. + +PKCE (`code_challenge` and `code_challenge_method`) is optional for confidential clients, but we recommend it. Use the +`S256` method. + +**2. The user signs in and approves your application.** The consent screen lists the scopes you asked for, and the user +can authorize or deny the request. The user isn't asked again if they have already authorized the same scopes for your +client and that token is still valid. Add `prompt=consent` to always show the consent screen. + +**3. The user is sent back to your redirect URL** with a `code` and your `state`: + +``` +https://app.example.com/oauth/callback?code=def50200a1b2c3...&state=RANDOM_STATE +``` + +The code is valid for 10 minutes and can only be used once. + +**4. Exchange the code for tokens** from your server: + +```bash +curl -X POST https://fount.wppbav.com/oauth/token \ + -H "Accept: application/json" \ + -d grant_type=authorization_code \ + -d client_id=9f1c2e4a-1234-4b5c-8d6e-0123456789ab \ + -d client_secret=YOUR_CLIENT_SECRET \ + -d redirect_uri=https://app.example.com/oauth/callback \ + -d code=def50200a1b2c3... \ + -d code_verifier=CODE_VERIFIER +``` + +```json +{ + "token_type": "Bearer", + "expires_in": 31536000, + "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...", + "refresh_token": "def50200d4e5f6..." +} +``` + +**5. Call the API** with the access token: + +```bash +curl https://fount.wppbav.com/api/v2/brands \ + -H "Accept: application/json" \ + -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." +``` + +#### Refreshing tokens + +Access tokens and refresh tokens are each valid for one year. Use the refresh token to get a new access token before +the old one expires: + +```bash +curl -X POST https://fount.wppbav.com/oauth/token \ + -H "Accept: application/json" \ + -d grant_type=refresh_token \ + -d client_id=9f1c2e4a-1234-4b5c-8d6e-0123456789ab \ + -d client_secret=YOUR_CLIENT_SECRET \ + -d refresh_token=def50200d4e5f6... +``` + +The response has a new access token and a new refresh token. The old refresh token can't be used again. + +#### Getting the user's profile + +With the `profile` scope, you can get the profile of the user who authorized the token from the `userinfo` endpoint. +This only works with tokens from the authorization code flow. + +```bash +curl https://fount.wppbav.com/oauth/userinfo \ + -H "Accept: application/json" \ + -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." +``` + +```json +{ + "sub": "0b7e6a1c-5d3f-4e2a-9c8b-7a6f5e4d3c2b", + "name": "Jane Doe", + "given_name": "Jane", + "family_name": "Doe", + "email": "jane.doe@example.com", + "email_verified": true, + "locale": "en", + "updated_at": 1761206400, + "operating_company": { + "id": 12, + "name": "Example Agency" + }, + "country": { + "id": 45, + "name": "United Kingdom", + "code": "GB", + "code_alpha3": "GBR", + "code_numeric": "826", + "region": "Europe" + }, + "roles": [ + "User", + "BAV User" + ], + "is_active": true +} +``` + +`operating_company` and `country` are left out when they aren't set for the user. + +#### Trusted applications + +For internal applications, we can mark the application as trusted and skip the consent screen. Consent is only skipped +when the authorization request comes from one of the trusted IP addresses we set up for the application, for example +your office or VPN network. From anywhere else, the user sees the consent screen as usual. + +These trusted IP addresses are separate from the [allowed API IP addresses](#restricting-where-api-calls-come-from). +[Contact us](mailto:support@bernskiold.com) if you'd like your application set up as trusted. + +### Client credentials flow + +Use this flow when the application calls the API as itself and you'd rather use OAuth than a long-lived +[API key](#application-api-keys). The request is made as the application, just as with an API key. The client +credentials flow needs to be enabled for your application by us, and you need a client credentials client. + +```bash +curl -X POST https://fount.wppbav.com/oauth/token \ + -H "Accept: application/json" \ + -d grant_type=client_credentials \ + -d client_id=9f1c2e4a-5678-4b5c-8d6e-0123456789ab \ + -d client_secret=YOUR_CLIENT_SECRET \ + -d "scope=bav:shared-resources bav:brand-data" +``` + +```json +{ + "token_type": "Bearer", + "expires_in": 3600, + "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." +} +``` + +- The token is valid for **one hour**, and there is no refresh token. Request a new token when it expires. +- The token can only have the scopes set on the client, which you choose when you create or edit the client. Asking for + any other scope, including `*`, returns an `invalid_scope` error. +- If you leave out `scope`, the token gets every scope on the client except `act-as-user`, which you have to ask for by + name. +- The token request is refused if the client has no scopes, if the client credentials flow isn't enabled for the + application, or if the request comes from an address outside the + [allowed API IP addresses](#restricting-where-api-calls-come-from). + +Scope changes on a client apply to new tokens. Tokens already issued keep their scopes until they expire. + +## Acting on behalf of users + +A trusted application can make a request as any user by sending the user's e-mail address in the `X-Act-As-User` +header. The request is then made as that user, with their permissions and data access. Use this for internal platforms +that have already signed the user in and can't send them through the OAuth flow. + +```bash +curl https://fount.wppbav.com/api/v2/brands \ + -H "Accept: application/json" \ + -H "Authorization: Bearer 2|ZyXwVuTsRqPoNmLkJiHgFeDcBa9876543210" \ + -H "X-Act-As-User: jane.doe@example.com" +``` + +All of these are required: + +- **The application is trusted and approved to act on behalf of users.** This is set by us. + [Contact us](mailto:support@bernskiold.com) if your application needs it. +- **The token belongs to the application.** Use an [application API key](#application-api-keys) or a + [client credentials token](#client-credentials-flow). A token that a user issued to your application through the + authorization code flow can't act as another user, and neither can a personal access token (apart from legacy + tokens with the [`bav:auto-login`](#system-scopes) scope). +- **The token has the `act-as-user` scope by name.** The scope is only offered once the application is approved. The + `*` scope doesn't include it, and a client credentials token only gets it when you ask for it in `scope`. +- **The request comes from an allowed address**, if the application has + [allowed API IP addresses](#restricting-where-api-calls-come-from). + +The user must be an active user. If no user has the e-mail address, a `422` error is returned. For BAV applications, +we can instead have unknown users created as BAV users on their first request. + +Activity performed this way is recorded against the user, and notes that it was made through your application. + +The legacy `X-User-Email` header is still accepted in place of `X-Act-As-User`, but we recommend moving to +`X-Act-As-User`. + +## IP restrictions + +There are two separate IP lists on an application: + +| Setting | What it does | Set by | +|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|-----------------| +| Allowed API IP Addresses | Limits where the application can call the API from. Other addresses get a `403`. Empty means any address. See [above](#restricting-where-api-calls-come-from). | Owners and admins | +| Trusted IP addresses | Where users can authorize a [trusted application](#trusted-applications) without the consent screen. Doesn't block any requests. | Us | + +## Errors + +Authentication errors are always returned as JSON with a `message`, even if you don't send an `Accept` header. + +```json +{ + "message": "This application does not allow requests from this IP address." +} +``` + +| Code | Message | Cause | +|-------|-------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| +| `401` | `Unauthenticated.` | The token is missing, invalid, revoked or expired, or it's a client credentials token for an application that no longer allows the flow. | +| `401` | `Your API key does not have the required permissions to perform the requested action: …` | The token doesn't have the [scope](#scopes) the endpoint requires. The message names the scope. | +| `403` | `This application does not allow requests from this IP address.` | The request comes from outside the application's [allowed API IP addresses](#restricting-where-api-calls-come-from). | +| `403` | `This application has been deactivated.` | The application has been deactivated. | +| `403` | `A token issued to a user cannot act as another user.` | `X-Act-As-User` was sent with an OAuth token issued to a user. | +| `403` | `This token is not allowed to act as another user.` | `X-Act-As-User` was sent with a personal access token without the legacy `bav:auto-login` scope. | +| `403` | `This application is not allowed to act on behalf of users.` | The application isn't trusted and approved to act on behalf of users. | +| `403` | `The token does not have the act-as-user scope.` | The application's token doesn't name the `act-as-user` scope. | +| `403` | `The user to act as is not active.` | The user in `X-Act-As-User` has been deactivated. | +| `403` | `An application cannot act as another application.` | The e-mail address in `X-Act-As-User` belongs to an application. | +| `422` | `The user to act as must be given as an e-mail address.` | `X-Act-As-User` isn't a valid e-mail address. | +| `422` | `No user exists with this e-mail address.` | No user has the e-mail address in `X-Act-As-User`. | + +A `403` can also mean that the account the request is made as doesn't have access to the resource or action. See +[errors](errors.md). + +The token endpoint returns errors in the OAuth 2 format, for example: + +```json +{ + "error": "invalid_scope", + "error_description": "The requested scope is invalid, unknown, or malformed", + "hint": "Check the `bav:market-share-data` scope", + "message": "The requested scope is invalid, unknown, or malformed" +} +``` + ## Scopes We allow you to create integrations and API keys that have different levels of access to your account. This is done through scopes. Scopes are broad and each one covers a group of endpoints, typically a dataset. For example, to list brands using the -`/brands` endpoint, your API key needs the `bav:shared-resources` scope, and to get data from the `/brandscape-data` +`/brands` endpoint, your token needs the `bav:shared-resources` scope, and to get data from the `/brandscape-data` endpoint, it needs the `bav:brand-data` scope. -If your API key doesn't have the scope that an endpoint requires, a `401` error is returned with a message telling you +If your token doesn't have the scope that an endpoint requires, a `401` error is returned with a message telling you which scope is missing. -Scopes for your API keys and applications are managed from -the [API section in The Fount](https://fount.wppbav.com/api). +You choose the scopes when you create a personal access token, an application API key or a client credentials client. +With the authorization code flow, you ask for them in the `scope` parameter. ### Available scopes @@ -68,29 +439,31 @@ the [API section in The Fount](https://fount.wppbav.com/api). | `bav:market-share-data` | Market Share Data | Euromonitor market share data: the `/market-share/...` endpoints, including the brand and company shares and the catalogs of brands, companies, categories, geographies, industries and data types. | | `bav:audiences:write` | Build Audiences | Creating, updating and deleting audiences, audience segments and segment metrics, and deploying audiences (`/audiences/{id}/deploy`). Reading audiences only requires `bav:shared-resources`. | | `bav:collections:write` | Create Collections | Creating and managing brand collections. The collection endpoints in the REST API are currently read-only and only require `bav:shared-resources`. | -| `profile` | User Profile | The authenticated user's profile information from the `/oauth/userinfo` endpoint. | +| `profile` | User Profile | The authenticated user's profile information from the [`/oauth/userinfo`](#getting-the-users-profile) endpoint. | The [health check](health-check.md) endpoint doesn't require authentication or any scope. ### Scopes and permissions -Most of the dataset scopes are tied to a permission in The Fount. You can only give a scope to an API key when your -account has access to the dataset it covers. For example, the `bav:best-countries-data` scope is only available if -you have access to Best Countries. For an application, the scopes available depend on the access of the account that -owns the application. +Most of the dataset scopes are tied to a permission in The Fount. You can only give a scope to a key when the account +it belongs to has access to the dataset it covers. For example, the `bav:best-countries-data` scope is only available +on a personal access token if you have access to Best Countries. For an application's API keys and client credentials +clients, the scopes on offer depend on the access of the [application's own user](#the-applications-own-user), not on +yours. -Scopes control which endpoints an API key can use. Within those endpoints, you can still only see the data that the -account you're acting as has access to. If the account doesn't have permission to perform an action or see a resource, -a `403` error is returned. +Scopes control which endpoints a token can use. Within those endpoints, you can still only see the data that the +account the request is made as has access to. If that account doesn't have permission to perform an action or see a +resource, a `403` error is returned. ### System scopes A few scopes are not for general use and can't be self-assigned: -- `act-as-user` lets an approved application act on behalf of its users by sending the user's e-mail address in the - `X-Act-As-User` header. It is only offered on an application's own API keys once the application has been approved - to act on behalf of users. -- `bav:auto-login` is a legacy system scope for trusted integrations. It requires a special permission and can't be - given to applications. +- `act-as-user` lets an approved application [act on behalf of users](#acting-on-behalf-of-users). It is only offered + on an application's own API keys and client credentials clients once the application has been approved to act on + behalf of users. +- `bav:auto-login` is a legacy system scope for older trusted integrations. A personal access token that names it + explicitly can still send `X-Act-As-User`. It requires a special permission and can't be given to applications. New + integrations should use an application approved to act on behalf of users instead. [Contact us](mailto:support@bernskiold.com) if you think your integration needs one of these. From 66e5ea132b16aae104e092097a38fe3606d86f08 Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Fri, 23 Oct 2026 23:27:14 +0200 Subject: [PATCH 07/23] Backfill blog posts for API and MCP releases since November 2025 Co-Authored-By: Claude Opus 5.5 --- blog/2023-08-15-new-cities-endpoint.md | 2 +- blog/2024-01-19-python-sdk-1-0.md | 6 ++-- blog/2025-05-28-mcp-server.md | 2 +- blog/2026-02-14-new-bav-mcp-data-tools.md | 24 +++++++++++++ blog/2026-02-27-search-result-limit.md | 16 +++++++++ blog/2026-03-15-mcp-apps-and-audiences.md | 30 ++++++++++++++++ ...rrespondence-maps-and-media-performance.md | 23 +++++++++++++ blog/2026-05-11-brandscape-data-on-demand.md | 18 ++++++++++ .../2026-05-21-agency-change-predictor-api.md | 18 ++++++++++ blog/2026-06-17-mcp-metrics-and-sharing.md | 21 ++++++++++++ blog/2026-07-31-rank-or-percentage-in-mcp.md | 15 ++++++++ blog/2026-08-10-aura-in-mcp.md | 20 +++++++++++ blog/2026-08-20-explicit-study-types.md | 34 +++++++++++++++++++ ...2026-09-08-health-check-and-acp-updates.md | 22 ++++++++++++ blog/2026-09-12-market-share.md | 29 ++++++++++++++++ blog/2026-09-28-brand-tags-and-hierarchy.md | 24 +++++++++++++ blog/2026-10-17-measures-and-questions.md | 18 ++++++++++ blog/2026-10-17-stock-prices.md | 24 +++++++++++++ blog/2026-10-22-study-methodologies.md | 16 +++++++++ blog/2026-10-23-application-access.md | 22 ++++++++++++ 20 files changed, 379 insertions(+), 5 deletions(-) create mode 100644 blog/2026-02-14-new-bav-mcp-data-tools.md create mode 100644 blog/2026-02-27-search-result-limit.md create mode 100644 blog/2026-03-15-mcp-apps-and-audiences.md create mode 100644 blog/2026-04-13-correspondence-maps-and-media-performance.md create mode 100644 blog/2026-05-11-brandscape-data-on-demand.md create mode 100644 blog/2026-05-21-agency-change-predictor-api.md create mode 100644 blog/2026-06-17-mcp-metrics-and-sharing.md create mode 100644 blog/2026-07-31-rank-or-percentage-in-mcp.md create mode 100644 blog/2026-08-10-aura-in-mcp.md create mode 100644 blog/2026-08-20-explicit-study-types.md create mode 100644 blog/2026-09-08-health-check-and-acp-updates.md create mode 100644 blog/2026-09-12-market-share.md create mode 100644 blog/2026-09-28-brand-tags-and-hierarchy.md create mode 100644 blog/2026-10-17-measures-and-questions.md create mode 100644 blog/2026-10-17-stock-prices.md create mode 100644 blog/2026-10-22-study-methodologies.md create mode 100644 blog/2026-10-23-application-access.md diff --git a/blog/2023-08-15-new-cities-endpoint.md b/blog/2023-08-15-new-cities-endpoint.md index 623a87f..183870b 100644 --- a/blog/2023-08-15-new-cities-endpoint.md +++ b/blog/2023-08-15-new-cities-endpoint.md @@ -8,7 +8,7 @@ For some of the data that we track, we need to map it to a city. For this reason world with a population over 500 people, based on the [GeoNames](https://www.geonames.org/) database. We have now made this database available through the API. You can find the documentation for the new endpoint in the -[API reference](/docs/2.x/core-resources/cities). +[API reference](/docs/2.x/metadata/cities). The cities endpoint comes with a few filters that you can use to narrow down the results. For example, you can filter by country or region, or for example retrieve capitals only. \ No newline at end of file diff --git a/blog/2024-01-19-python-sdk-1-0.md b/blog/2024-01-19-python-sdk-1-0.md index 20b72e6..6125ee3 100644 --- a/blog/2024-01-19-python-sdk-1-0.md +++ b/blog/2024-01-19-python-sdk-1-0.md @@ -20,10 +20,10 @@ If you encounter any bugs while using the SDK, or if you have any suggestions/re Some highlights since our last announcement: -- :tada: Full support for many more [endpoints](../docs/2.x/developer-tools/python/endpoints), and more [versatility](../docs/2.x/developer-tools/python/basic-usage#using-query-objects) for performing endpoint requests. +- :tada: Full support for many more [endpoints](/docs/2.x/developer-tools/python/endpoints), and more [versatility](/docs/2.x/developer-tools/python/basic-usage#using-query-objects) for performing endpoint requests. - :rocket: `bavapi` queries should now be faster and more reliable, thanks to various improvements in the requests and response parsing logic. -- :sparkles: New [error handling](../docs/2.x/developer-tools/python/basic-usage#error-handling) behavior. If a page fails to download, `bavapi` will now warn the user about the missing pages instead of raising an exception. You can change this by using `on_errors="raise"` in endpoint calls. -- :notebook: Improved [SDK documentation](../docs/2.x/developer-tools/python) and updated with the latest features and functionality. +- :sparkles: New [error handling](/docs/2.x/developer-tools/python/basic-usage#error-handling) behavior. If a page fails to download, `bavapi` will now warn the user about the missing pages instead of raising an exception. You can change this by using `on_errors="raise"` in endpoint calls. +- :notebook: Improved [SDK documentation](/docs/2.x/developer-tools/python) and updated with the latest features and functionality. - :bug: Fixed various issues with validation, data parsing and pagination. Read the detailed changelog on [GitHub](https://github.com/wppbav/bavapi-sdk-python/releases). diff --git a/blog/2025-05-28-mcp-server.md b/blog/2025-05-28-mcp-server.md index b325987..bfd9474 100644 --- a/blog/2025-05-28-mcp-server.md +++ b/blog/2025-05-28-mcp-server.md @@ -13,4 +13,4 @@ Our new remote MCP server uses the latest MCP (Model Control Protocol) standard. We're excited to see how you and your agents use BAV data to power your workflows. If you have questions, feedback, or requests for new MCP tools, please let us know. -[Read more about the MCP Server](/docs/2.x/ai/mcp-server) \ No newline at end of file +[Read more about the MCP Server](/docs/2.x/ai/mcp/intro) \ No newline at end of file diff --git a/blog/2026-02-14-new-bav-mcp-data-tools.md b/blog/2026-02-14-new-bav-mcp-data-tools.md new file mode 100644 index 0000000..cd10426 --- /dev/null +++ b/blog/2026-02-14-new-bav-mcp-data-tools.md @@ -0,0 +1,24 @@ +--- +slug: new-bav-mcp-data-tools +title: Six new data tools on the BAV MCP server +authors: erikbernskiold +--- + +The BAV MCP server can now answer a much wider range of brand questions. We've added six new data tools, bringing +more of the analyses you know from the platform to your agents. + + + +- **Commitment Funnel** (`get-commitment-funnel-data`) shows how consumers move from awareness to preference and + loyalty. +- **Perception SWOT** (`get-perception-swot-data`) highlights a brand's strengths, weaknesses, opportunities and + threats. +- **Category Drivers** (`get-category-drivers-data`) shows which attributes drive preference in a category. +- **Archetypes** (`get-archetypes-data`) maps brands to their archetypes. +- **Partnership Exchange** (`get-partnership-exchange-data`) finds brands with complementary imagery for partnerships. +- **Toplist** (`get-toplist-data`) ranks the top brands in a market on a given metric. + +Agents can also create brand collections with the new `create-collection` tool, making it easy to save a set of +brands for later analysis. + +See the [BAV MCP Server](/docs/2.x/ai/mcp/bav) documentation for the full list of tools and their parameters. diff --git a/blog/2026-02-27-search-result-limit.md b/blog/2026-02-27-search-result-limit.md new file mode 100644 index 0000000..93fd3ac --- /dev/null +++ b/blog/2026-02-27-search-result-limit.md @@ -0,0 +1,16 @@ +--- +slug: search-result-limit +title: Search results are now limited to 1,000 records +authors: erikbernskiold +--- + +To keep searches fast and reliable, a search now returns at most the 1,000 best-matching records. This applies to +every API endpoint that supports the `search` parameter. + + + +Most searches return far fewer results than this, so you are unlikely to notice a difference. If you need to go through +a very large set of records, combine filters rather than a broad search term, or leave out the search and paginate +through the full list. + +See [Searching](/docs/2.x/customizing/searching) for more details. diff --git a/blog/2026-03-15-mcp-apps-and-audiences.md b/blog/2026-03-15-mcp-apps-and-audiences.md new file mode 100644 index 0000000..88d45d8 --- /dev/null +++ b/blog/2026-03-15-mcp-apps-and-audiences.md @@ -0,0 +1,30 @@ +--- +slug: mcp-apps-and-audiences +title: Interactive charts and audience building in MCP +authors: erikbernskiold +--- + +Agents connected to the BAV MCP server can now show interactive charts and build custom audiences, right in the +conversation. + + + +## Interactive charts with MCP Apps + +MCP Apps let a server return interactive interfaces alongside its data. In clients that support MCP Apps, the new +display tools render BAV charts directly in the chat: + +- `display-powergrid-chart` for the PowerGrid +- `display-pillar-chart` for the brand pillars +- `display-imagery-chart` for imagery attributes +- `display-brand-relationship-chart` for brand relationships + +Read more in [MCP Apps](/docs/2.x/ai/mcp/mcp-apps). + +## Audience building + +Agents can now create and manage custom audiences, add definitions and deploy them, using tools such as +`create-audience`, `add-audience-definition` and `deploy-audience`. Once deployed, an audience can be used across the +BAV data tools like any other. + +See the [BAV MCP Server](/docs/2.x/ai/mcp/bav#audience-tools) documentation for the full list of audience tools. diff --git a/blog/2026-04-13-correspondence-maps-and-media-performance.md b/blog/2026-04-13-correspondence-maps-and-media-performance.md new file mode 100644 index 0000000..d7db3f1 --- /dev/null +++ b/blog/2026-04-13-correspondence-maps-and-media-performance.md @@ -0,0 +1,23 @@ +--- +slug: correspondence-maps-and-media-performance +title: Correspondence maps and media performance in MCP +authors: erikbernskiold +--- + +Two new capabilities have arrived on the BAV MCP server: correspondence maps and media performance benchmarks. + + + +## Correspondence maps + +The new `get-correspondence-map-data` tool runs a correspondence analysis over imagery attributes and returns the +coordinates of brands and attributes on a shared map. It's the same analysis that powers the Correspondence Map in the +platform, and is great for finding whitespace, ownership of attributes and clusters of similar brands. + +## Media performance + +For brands that use media performance benchmarking, a new set of tools gives agents access to campaign performance +data and benchmarks, such as `get-campaign-performance-data` and `get-campaign-performance-benchmarks`. Access is +granted per brand, so the tools only appear for users who have access to at least one brand. + +See the [BAV MCP Server](/docs/2.x/ai/mcp/bav) documentation for details. diff --git a/blog/2026-05-11-brandscape-data-on-demand.md b/blog/2026-05-11-brandscape-data-on-demand.md new file mode 100644 index 0000000..2f31633 --- /dev/null +++ b/blog/2026-05-11-brandscape-data-on-demand.md @@ -0,0 +1,18 @@ +--- +slug: brandscape-data-on-demand +title: Brandscape data is now generated on request +authors: erikbernskiold +--- + +The [Brandscape Data](/docs/2.x/brand-data/brandscape-data) endpoint now makes sure the data you ask for exists. If +a combination of study and audience hasn't been generated yet, requesting it starts the generation for you. + + + +While data is being generated the endpoint responds with **202 Accepted** instead of 200 OK, and includes a +`meta.generation` block. Its `status` is `pending` when nothing is ready yet, or `partial` when some of the requested +data is available and the rest is on its way. Retry the request after a short while to get the complete data. Once +everything is available, you'll get a 200 OK as usual. + +We've also added a safeguard for very wide requests. If you don't filter by study, country or year, the endpoint +now returns data for the latest available study rather than scanning all of BAV. diff --git a/blog/2026-05-21-agency-change-predictor-api.md b/blog/2026-05-21-agency-change-predictor-api.md new file mode 100644 index 0000000..986c976 --- /dev/null +++ b/blog/2026-05-21-agency-change-predictor-api.md @@ -0,0 +1,18 @@ +--- +slug: agency-change-predictor-api +title: Agency Change Predictor in the API +authors: erikbernskiold +--- + +The Agency Change Predictor is now available in the API. It runs ten weighted checks +on a brand's equity, compared with its category, to assess how likely the brand is to change agency. + + + +Send a request to `/api/v2/tools/agency-change-predictor` with the brands and studies (or countries and years) you're +interested in, and you'll get a prediction for each brand. + +Since launch, the endpoint has been brought in line with the other data model endpoints. It accepts arrays of IDs +or names, supports study types, and returns the standard `meta` and `data` response. + +See [Agency Change Predictor](/docs/2.x/brand-data/agency-change-predictor) for the full documentation. diff --git a/blog/2026-06-17-mcp-metrics-and-sharing.md b/blog/2026-06-17-mcp-metrics-and-sharing.md new file mode 100644 index 0000000..6cb2f8c --- /dev/null +++ b/blog/2026-06-17-mcp-metrics-and-sharing.md @@ -0,0 +1,21 @@ +--- +slug: mcp-metrics-and-sharing +title: Focused data and sharing collections in MCP +authors: erikbernskiold +--- + +We've made several improvements to the BAV MCP server to help agents get exactly the data they need, and share their +work. + + + +- **Metric subsets**: The imagery, personality, PowerGrid, preferences, usage, recommendation, influence and pillar + tools accept a new `metrics` parameter. Agents can ask for just the metrics they need, which keeps responses smaller + and more focused. +- **Clearer metric keys**: Metric keys now say what type of data they hold, so models are less likely to mix up ranks + and percentages. +- **Sharing collections**: The new `share-collection` tool shares a brand collection with up to 10 people by email, with + view or edit access. +- **Creative Premium**: The new `get-creative-premium-data` tool is available to users with access to Creative Premium. + +See the [BAV MCP Server](/docs/2.x/ai/mcp/bav) documentation for details. diff --git a/blog/2026-07-31-rank-or-percentage-in-mcp.md b/blog/2026-07-31-rank-or-percentage-in-mcp.md new file mode 100644 index 0000000..90482d6 --- /dev/null +++ b/blog/2026-07-31-rank-or-percentage-in-mcp.md @@ -0,0 +1,15 @@ +--- +slug: rank-or-percentage-in-mcp +title: Choose between ranks and percentages in MCP +authors: erikbernskiold +--- + +The imagery, personality, preferences, recommendation and usage tools on the BAV MCP server now take an optional +`score_type` parameter. Set it to `rank` or `percentage` to choose how the data is returned. + + + +If you leave it out, each tool keeps its existing default, so nothing changes for current agents. Imagery and +personality default to percentile ranks, while preferences, recommendation and usage default to percentages. + +Not sure which to use? Our new [Concepts for Agents](/docs/2.x/ai/mcp/concepts) page explains the difference. diff --git a/blog/2026-08-10-aura-in-mcp.md b/blog/2026-08-10-aura-in-mcp.md new file mode 100644 index 0000000..3e3f3b1 --- /dev/null +++ b/blog/2026-08-10-aura-in-mcp.md @@ -0,0 +1,20 @@ +--- +slug: aura-in-mcp +title: AURA AI brand research in MCP +authors: erikbernskiold +--- + +AURA, our AI brand research, is now available on the BAV MCP server. AURA studies measure how AI models perceive brands, +using the same models as our consumer research. + + + +Seven new tools give agents access to AURA data: + +- `get-aura-studies` and `get-aura-audiences` to find the available studies and audiences. +- `get-aura-pillar-data`, `get-aura-powergrid-data`, `get-aura-personality-data` and `get-aura-imagery-data` for the + core brand models. +- `get-aura-drift-data` to compare how AI sees a brand against how consumers see it. + +The tools are available to users with access to AURA. See the +[BAV MCP Server](/docs/2.x/ai/mcp/bav#aura-tools) documentation for details. diff --git a/blog/2026-08-20-explicit-study-types.md b/blog/2026-08-20-explicit-study-types.md new file mode 100644 index 0000000..9a771df --- /dev/null +++ b/blog/2026-08-20-explicit-study-types.md @@ -0,0 +1,34 @@ +--- +slug: explicit-study-types +title: Explicit study types across the API and MCP +authors: erikbernskiold +--- + +BAV data comes from different types of studies: our standard studies, SnapBAV, AO+BAV Fused and custom studies. They +aren't interchangeable, so you now always choose which type of study your data comes from. + + + +## In the API + +The brandscape endpoints accept a new `filter[study_types]` parameter, with the values `syndicated`, `snap`, `fused` +and `custom`. It defaults to `syndicated`. If a market is only covered by another study type, you get no rows and a +`meta.available_alternatives` block that tells you what exists and how to ask for it. Each row now also includes its +study type. + +## In MCP + +The brandscape tools now work from studies. If an agent asks for a country and year, it gets a list of matching studies +with their type, caveats and a recommendation, and is asked to pick one. Models handle this well, but it is a change in +behaviour worth knowing about. The `get-markets` tool now returns each study's ID as `study_id`. + +## Other changes + +- The "BAV (Syndicated)" study type is now called **BAV (Standard)**. The `syndicated` value in the API and MCP stays + the same. +- Audiences now include population projections. `GET /api/v2/audiences/{id}/studies` returns a `population` per study, + and the new `get-audience-studies` MCP tool does the same. +- The audience tools on the BAV MCP server are now available to all users. + +Read more in [Brandscape Data](/docs/2.x/brand-data/brandscape-data) and +[Concepts for Agents](/docs/2.x/ai/mcp/concepts). diff --git a/blog/2026-09-08-health-check-and-acp-updates.md b/blog/2026-09-08-health-check-and-acp-updates.md new file mode 100644 index 0000000..0de9ccf --- /dev/null +++ b/blog/2026-09-08-health-check-and-acp-updates.md @@ -0,0 +1,22 @@ +--- +slug: health-check-and-acp-updates +title: Health check without a token, and Agency Change Predictor updates +authors: erikbernskiold +--- + +A couple of smaller improvements to the API. + + + +## Health check without a token + +The [health check](/docs/2.x/health-check) endpoint at `/api/v2/health` no longer needs an API token. That means you +can tell the difference between the API being down and your token having expired, and uptime monitors no longer need +credentials. + +## Agency Change Predictor + +The [Agency Change Predictor](/docs/2.x/brand-data/agency-change-predictor) now works like the other brandscape +model endpoints. It accepts arrays of IDs or names, honours study types and years, returns the standard `meta` and +`data` envelope, and includes each brand's classification. The comma-separated format still works, so existing +integrations keep running. diff --git a/blog/2026-09-12-market-share.md b/blog/2026-09-12-market-share.md new file mode 100644 index 0000000..441d03a --- /dev/null +++ b/blog/2026-09-12-market-share.md @@ -0,0 +1,29 @@ +--- +slug: market-share +title: Euromonitor market share in the API and MCP +authors: erikbernskiold +--- + +Market share data from Euromonitor is now available in both the API and through a new MCP server, alongside BAV +brand equity data. + + + +## In the API + +New endpoints give you Euromonitor's catalogs of brands, companies, categories, data types, geographies and industries, +and the brand and company share data itself. They need the `bav:market-share-data` scope, and access to Euromonitor +data on your account. + +A few things to keep in mind: + +- Euromonitor has its own IDs for everything. Fields that link to BAV are prefixed with `bav_`. +- A `null` value means the figure wasn't supplied, never zero. +- Share queries must be narrowed by at least one brand, company, category, geography or industry. + +See [Market Share](/docs/2.x/market-share/) for the full documentation. + +## In MCP + +The new Market Share MCP server at `/v1/market-share` gives agents the same data. See the +[Market Share Server](/docs/2.x/ai/mcp/market-share) documentation for details. diff --git a/blog/2026-09-28-brand-tags-and-hierarchy.md b/blog/2026-09-28-brand-tags-and-hierarchy.md new file mode 100644 index 0000000..6bb14a3 --- /dev/null +++ b/blog/2026-09-28-brand-tags-and-hierarchy.md @@ -0,0 +1,24 @@ +--- +slug: brand-tags-and-hierarchy +title: Brand tags and brand hierarchy +authors: erikbernskiold +--- + +The brands endpoint can now tell you more about what a brand is, and how it relates to other brands and companies. + + + +## Brand tags + +Brand tags describe what a brand is, rather than how it performs. The new [Brand Tags](/docs/2.x/brands/brand-tags) +endpoint lists every tag, and you can filter brands with `filter[tags]` and include their tags with `include=tags`. +Tags can be named by their ID or their key. + +In MCP, the `get-brands` tool has a new `tags` filter, and the new `list-brand-tags` tool lists the tags available. + +## Brand hierarchy and companies + +You can now filter brands by the company that owns them with `filter[companies]`. Each brand also includes its +`parent_brand_id`, and you can include its `parent` and `children` brands. + +See [Brands](/docs/2.x/brands) for the full documentation. diff --git a/blog/2026-10-17-measures-and-questions.md b/blog/2026-10-17-measures-and-questions.md new file mode 100644 index 0000000..3684cf2 --- /dev/null +++ b/blog/2026-10-17-measures-and-questions.md @@ -0,0 +1,18 @@ +--- +slug: measures-and-questions +title: Find which studies ask a measure or question +authors: erikbernskiold +--- + +New endpoints make it easier to find out what a study measures, and where a measure or question was asked, before you +query for data. + + + +- `/bav-questions` lists the BAV audience questions, alongside the existing `/bav-question-groups`. +- `/brand-measures/{id}/studies` and `/bav-questions/{id}/studies` list the studies a measure or question was asked + in. +- `/studies/{id}/brand-measures`, `/studies/{id}/brand-metrics`, `/studies/{id}/audience-questions` and + `/studies/{id}/bav-questions` list what a study asked. + +See [Measures & Questions](/docs/2.x/measures/) for the full documentation. diff --git a/blog/2026-10-17-stock-prices.md b/blog/2026-10-17-stock-prices.md new file mode 100644 index 0000000..fabbf01 --- /dev/null +++ b/blog/2026-10-17-stock-prices.md @@ -0,0 +1,24 @@ +--- +slug: stock-prices +title: Changes to the stock prices endpoint +authors: erikbernskiold +--- + +Stock prices are now read directly from our market data provider, rather than from a copy stored in BAV. This gives +you a more complete and up-to-date price history, but it does change how the endpoint works. + + + +**This is a breaking change.** `GET /api/v2/stock-prices` now: + +- requires `companies[]` or `tickers[]`, with at most 25 in total; +- accepts `from`, `to` and `interval` (`daily`, `weekly` or `monthly`); +- returns rows ordered oldest first, with `ticker`, `date`, `company_id`, `currency`, `open`, `high`, `low`, `close`, + `adjusted_close` and `volume`; +- is no longer paginated, and no longer supports `include`, `updated_since` or fetching a single price by ID. + +There is also a new `GET /api/v2/companies/{id}/stock-prices` endpoint for a single company. + +The Financial Data MCP server has a new `get-stock-prices` tool with the same data. + +See [Stock Prices](/docs/2.x/company-data/stock-prices) for the full documentation. diff --git a/blog/2026-10-22-study-methodologies.md b/blog/2026-10-22-study-methodologies.md new file mode 100644 index 0000000..e1bbd60 --- /dev/null +++ b/blog/2026-10-22-study-methodologies.md @@ -0,0 +1,16 @@ +--- +slug: study-methodologies +title: New names for study methodologies +authors: erikbernskiold +--- + +Study methodologies have new names and descriptions: BAV 1, BAV 1 (Known Brands), Triads V1 and V2, and the BAV 3 +variants. + + + +The studies endpoint now supports `include=methodology` to return each study's methodology with its name and +description, and the `get-markets` MCP tool names the methodology of each study. The underlying keys are unchanged, so +existing integrations keep working. + +See [Studies](/docs/2.x/studies) for the full list of methodologies. diff --git a/blog/2026-10-23-application-access.md b/blog/2026-10-23-application-access.md new file mode 100644 index 0000000..1107a98 --- /dev/null +++ b/blog/2026-10-23-application-access.md @@ -0,0 +1,22 @@ +--- +slug: application-access +title: Applications can now call the API as themselves +authors: erikbernskiold +--- + +Applications can now call the API as themselves, using their own API keys or OAuth client credentials. Trusted +applications can also act on behalf of users. This replaces service accounts. + + + +- **Application API keys** are managed on the application's page by its owners, admins and developers. The scopes on + offer follow the application's own permissions. +- **Client credentials** tokens now work for calling the API as the application. +- **Acting on behalf of users** uses the `X-Act-As-User` header. It needs a trusted application approved by an + administrator, and a token with the `act-as-user` scope. +- **IP allow-lists** let an application limit the addresses it may call the API from. + +Existing service accounts have been moved over to applications, and their tokens keep working with the same access. + +See [Authentication](/docs/2.x/authentication) and +[MCP Access & Authorization](/docs/2.x/ai/mcp/access-authorization) for details. From c476a283945eb25598c0d268604f67f97d33c40f Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sat, 24 Oct 2026 13:56:49 +0200 Subject: [PATCH 08/23] Recommend OAuth over long-lived API keys Co-Authored-By: Claude Opus 5.5 --- docs/authentication.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/authentication.md b/docs/authentication.md index 015f775..956027c 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -30,6 +30,14 @@ exposed. Personal access tokens are the easiest way to get started. When you build something that other people will use, create an [application](#applications) instead. +:::tip We recommend OAuth +Where you can, use [OAuth 2](#oauth-2) rather than a long-lived personal access token or application API key. With +OAuth, users approve what your application can do and can revoke that access at any time, each request is made with the +permissions of the person using your application. Use the [authorization code flow](#authorization-code-flow) +when people sign in to your application, and the [client credentials flow](#client-credentials-flow) for +machine-to-machine integrations. +::: + Whichever method you use, the request has the permissions and data access of the account it is made as, and the token must have the [scope](#scopes) the endpoint requires. @@ -106,6 +114,9 @@ given, not your own. Expiry e-mails for an application's keys go to its owners, admins and developers. +For machine-to-machine integrations, we recommend the [client credentials flow](#client-credentials-flow) over an API +key. It gives the same access as the application, but with tokens that last an hour instead of a long-lived key. + ```bash curl https://fount.wppbav.com/api/v2/brands \ -H "Accept: application/json" \ From cc801dee94d1e962851cf23401351f5fcecbcb67 Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sat, 24 Oct 2026 13:57:13 +0200 Subject: [PATCH 09/23] Remove references to the legacy auto-login scope Co-Authored-By: Claude Opus 5.5 --- docs/ai/mcp/access-authorization.md | 3 +-- docs/authentication.md | 18 ++++++------------ 2 files changed, 7 insertions(+), 14 deletions(-) diff --git a/docs/ai/mcp/access-authorization.md b/docs/ai/mcp/access-authorization.md index b436dc7..4e3eebe 100644 --- a/docs/ai/mcp/access-authorization.md +++ b/docs/ai/mcp/access-authorization.md @@ -87,8 +87,7 @@ X-Act-As-User: jane.doe@wpp.com ``` :::note -Tokens issued to a user, whether through OAuth or as a personal access token, can't act as another user. The only -exception is legacy tokens with the `bav:auto-login` system scope. +Tokens issued to a user, whether through OAuth or as a personal access token, can't act as another user. ::: Applications can use two separate IP lists: diff --git a/docs/authentication.md b/docs/authentication.md index 956027c..39e2c55 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -361,8 +361,7 @@ All of these are required: [Contact us](mailto:support@bernskiold.com) if your application needs it. - **The token belongs to the application.** Use an [application API key](#application-api-keys) or a [client credentials token](#client-credentials-flow). A token that a user issued to your application through the - authorization code flow can't act as another user, and neither can a personal access token (apart from legacy - tokens with the [`bav:auto-login`](#system-scopes) scope). + authorization code flow can't act as another user, and neither can a personal access token. - **The token has the `act-as-user` scope by name.** The scope is only offered once the application is approved. The `*` scope doesn't include it, and a client credentials token only gets it when you ask for it in `scope`. - **The request comes from an allowed address**, if the application has @@ -402,7 +401,7 @@ Authentication errors are always returned as JSON with a `message`, even if you | `403` | `This application does not allow requests from this IP address.` | The request comes from outside the application's [allowed API IP addresses](#restricting-where-api-calls-come-from). | | `403` | `This application has been deactivated.` | The application has been deactivated. | | `403` | `A token issued to a user cannot act as another user.` | `X-Act-As-User` was sent with an OAuth token issued to a user. | -| `403` | `This token is not allowed to act as another user.` | `X-Act-As-User` was sent with a personal access token without the legacy `bav:auto-login` scope. | +| `403` | `This token is not allowed to act as another user.` | `X-Act-As-User` was sent with a personal access token. | | `403` | `This application is not allowed to act on behalf of users.` | The application isn't trusted and approved to act on behalf of users. | | `403` | `The token does not have the act-as-user scope.` | The application's token doesn't name the `act-as-user` scope. | | `403` | `The user to act as is not active.` | The user in `X-Act-As-User` has been deactivated. | @@ -468,13 +467,8 @@ resource, a `403` error is returned. ### System scopes -A few scopes are not for general use and can't be self-assigned: +Some scopes are not for general use and can't be self-assigned. The `act-as-user` scope lets an approved application +[act on behalf of users](#acting-on-behalf-of-users). It is only offered on an application's own API keys and client +credentials clients once the application has been approved to act on behalf of users. -- `act-as-user` lets an approved application [act on behalf of users](#acting-on-behalf-of-users). It is only offered - on an application's own API keys and client credentials clients once the application has been approved to act on - behalf of users. -- `bav:auto-login` is a legacy system scope for older trusted integrations. A personal access token that names it - explicitly can still send `X-Act-As-User`. It requires a special permission and can't be given to applications. New - integrations should use an application approved to act on behalf of users instead. - -[Contact us](mailto:support@bernskiold.com) if you think your integration needs one of these. +[Contact us](mailto:support@bernskiold.com) if you think your integration needs it. From 2517c13c54087d9bb7dd0eb565e78149156dfa8a Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sat, 24 Oct 2026 13:57:38 +0200 Subject: [PATCH 10/23] Describe application access without the underlying user Co-Authored-By: Claude Opus 5.5 --- docs/ai/mcp/access-authorization.md | 4 ++-- docs/authentication.md | 21 +++++++-------------- 2 files changed, 9 insertions(+), 16 deletions(-) diff --git a/docs/ai/mcp/access-authorization.md b/docs/ai/mcp/access-authorization.md index 4e3eebe..be6d29e 100644 --- a/docs/ai/mcp/access-authorization.md +++ b/docs/ai/mcp/access-authorization.md @@ -71,8 +71,8 @@ If you are building an application, you can create one yourself under **Applicat - **OAuth on behalf of a user:** Users authorize your application through the OAuth flow, and your application acts on their behalf with their permissions. -- **Application API keys:** An API key belonging to the application itself. Requests are made as the application's own - user, with the access an administrator has set up for it. +- **Application API keys:** An API key belonging to the application itself. Requests are made as the application, with + the access that has been set up for it. - **Client credentials:** A token requested with the OAuth client credentials grant. It works like an application API key, is limited to the client's scopes and lasts one hour. diff --git a/docs/authentication.md b/docs/authentication.md index 39e2c55..8d1c185 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -94,16 +94,11 @@ by their e-mail address, and give each of them a role: An application always keeps at least one owner. Only an owner can give, change or take away the Owner role. -### The application's own user +### Application access -Every application has its own user, which you can see as **Acts as** on the application's page. When the application -calls the API as itself, the request is made as this user. Its roles, agency and data access decide what the -application can see, in the same way as for a person. - -A new application's user starts with only basic access. An administrator sets up the access it needs. -[Contact us](mailto:support@bernskiold.com) to have access added to your application. - -This user can't be used to sign in to The Fount. +When the application calls the API as itself, it has its own access to data, separate from that of its members. A new +application starts with only basic access. [Contact us](mailto:support@bernskiold.com) to have the access it needs +added. ### Application API keys @@ -124,9 +119,8 @@ curl https://fount.wppbav.com/api/v2/brands \ ``` :::note Service accounts -Applications replace service accounts. Every service account has been converted to an application, with the -account as the application's own user. Tokens issued to a service account keep working, with the same access, and are -now managed as the application's API keys. +Applications replace service accounts. Every service account has been converted to an application. Tokens issued to a +service account keep working, with the same access, and are now managed as the application's API keys. ::: ### OAuth clients @@ -458,8 +452,7 @@ The [health check](health-check.md) endpoint doesn't require authentication or a Most of the dataset scopes are tied to a permission in The Fount. You can only give a scope to a key when the account it belongs to has access to the dataset it covers. For example, the `bav:best-countries-data` scope is only available on a personal access token if you have access to Best Countries. For an application's API keys and client credentials -clients, the scopes on offer depend on the access of the [application's own user](#the-applications-own-user), not on -yours. +clients, the scopes on offer depend on the [application's access](#application-access), not on yours. Scopes control which endpoints a token can use. Within those endpoints, you can still only see the data that the account the request is made as has access to. If that account doesn't have permission to perform an action or see a From 4ec99d84e77cfde9be69331b35225d13aa94beed Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sat, 24 Oct 2026 13:57:52 +0200 Subject: [PATCH 11/23] Remove the legacy X-User-Email header from the docs Co-Authored-By: Claude Opus 5.5 --- docs/ai/mcp/access-authorization.md | 3 +-- docs/authentication.md | 3 --- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/ai/mcp/access-authorization.md b/docs/ai/mcp/access-authorization.md index be6d29e..86dc27b 100644 --- a/docs/ai/mcp/access-authorization.md +++ b/docs/ai/mcp/access-authorization.md @@ -78,8 +78,7 @@ If you are building an application, you can create one yourself under **Applicat Applications that we have marked as trusted and approved to act on behalf of users can pass the e-mail address of a user in the `X-Act-As-User` header, together with an application API key or a client credentials token. The token must -explicitly include the `act-as-user` scope. The request is then made as that user, with their permissions. The legacy -`X-User-Email` header is still accepted, but we recommend moving to `X-Act-As-User`. +explicitly include the `act-as-user` scope. The request is then made as that user, with their permissions. ``` Authorization: Bearer YOUR_APPLICATION_TOKEN diff --git a/docs/authentication.md b/docs/authentication.md index 8d1c185..86cbe9a 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -366,9 +366,6 @@ we can instead have unknown users created as BAV users on their first request. Activity performed this way is recorded against the user, and notes that it was made through your application. -The legacy `X-User-Email` header is still accepted in place of `X-Act-As-User`, but we recommend moving to -`X-Act-As-User`. - ## IP restrictions There are two separate IP lists on an application: From befc79d2e3076dee21d3117da590ba3e16ea8520 Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sat, 24 Oct 2026 13:58:30 +0200 Subject: [PATCH 12/23] Remove the note about creating unknown users Co-Authored-By: Claude Opus 5.5 --- docs/authentication.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/authentication.md b/docs/authentication.md index 86cbe9a..7bce806 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -361,8 +361,7 @@ All of these are required: - **The request comes from an allowed address**, if the application has [allowed API IP addresses](#restricting-where-api-calls-come-from). -The user must be an active user. If no user has the e-mail address, a `422` error is returned. For BAV applications, -we can instead have unknown users created as BAV users on their first request. +The user must be an active user. If no user has the e-mail address, a `422` error is returned. Activity performed this way is recorded against the user, and notes that it was made through your application. From e3da7ce95f6a005aae6878e688bfec324197ec44 Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sat, 24 Oct 2026 14:01:59 +0200 Subject: [PATCH 13/23] Split the tools out of Brand Data into their own section Co-Authored-By: Claude Opus 5.5 --- docs/brand-data/brand-worth.md | 3 +- docs/brand-data/data-models.md | 35 +++++++-------- docs/brand-data/imagery.md | 4 +- docs/brand-data/index.md | 30 +++---------- docs/brand-data/influence.md | 2 - docs/brand-data/personality.md | 4 +- docs/brand-data/pillars.md | 4 +- docs/brand-data/powergrid.md | 4 +- docs/brand-data/preferences.md | 4 +- docs/brand-data/recommendation.md | 4 +- docs/brand-data/super-cx-tool.md | 71 +++++++++++++++++++++++++++++ docs/brand-data/super-cx.md | 74 +++---------------------------- docs/brand-data/tools.md | 53 ++++++++++++++++++++++ docs/brand-data/usage.md | 4 +- sidebars.js | 30 ++++++++----- 15 files changed, 177 insertions(+), 149 deletions(-) create mode 100644 docs/brand-data/super-cx-tool.md create mode 100644 docs/brand-data/tools.md diff --git a/docs/brand-data/brand-worth.md b/docs/brand-data/brand-worth.md index c2b0043..76c4bf2 100644 --- a/docs/brand-data/brand-worth.md +++ b/docs/brand-data/brand-worth.md @@ -8,8 +8,7 @@ Brand Worth returns the data behind the Brand Worth Map: each brand's percentile - **Emotional Choice** - `worth_more` rank below 50 and `good_value` rank below 50. - **Value Champion** - `worth_more` rank below 50 and `good_value` rank above 50. -Brand Worth is only available as a `POST` request. For the Brand Worth Map tool, see -the [Brand Worth Map](../brand-data/brand-worth-map.md) endpoint. +For the Brand Worth Map tool, see the [Brand Worth Map](brand-worth-map.md) endpoint. ## Creating a query diff --git a/docs/brand-data/data-models.md b/docs/brand-data/data-models.md index f362606..3ffbe2e 100644 --- a/docs/brand-data/data-models.md +++ b/docs/brand-data/data-models.md @@ -11,23 +11,18 @@ belong to. The following models are available: -| Model | Endpoint | Category specific? | Also available as | -|-------------------------------------------|-----------------------------------|:------------------:|----------------------------| -| [Powergrid](powergrid.md) | `POST /api/v2/brandscape/powergrid` | :x: | `GET /api/v2/tools/powergrid` | -| [Pillars](pillars.md) | `POST /api/v2/brandscape/pillars` | :x: | `GET /api/v2/tools/pillars` | -| [Imagery](imagery.md) | `POST /api/v2/brandscape/imagery` | :x: | `GET /api/v2/tools/imagery` | -| [Personality](personality.md) | `POST /api/v2/brandscape/personality` | :x: | `GET /api/v2/tools/personality` | -| [Influence](influence.md) | `POST /api/v2/brandscape/influence` | :x: | - | -| [Brand Worth](brand-worth.md) | `POST /api/v2/brandscape/brand-worth` | :x: | - | -| [Preferences](preferences.md) | `POST /api/v2/brandscape/preferences` | :white_check_mark: | `GET /api/v2/tools/preferences` | -| [Usage](usage.md) | `POST /api/v2/brandscape/usage` | :white_check_mark: | `GET /api/v2/tools/usage` | -| [Recommendation](recommendation.md) | `POST /api/v2/brandscape/recommendation` | :white_check_mark: | `GET /api/v2/tools/recommendation` | -| [Super CX](super-cx.md) | `POST /api/v2/brandscape/super-cx` | :white_check_mark: | `GET /api/v2/tools/super-cx`* | - -\* `GET /api/v2/tools/super-cx` is a separate tool endpoint with its own parameters and response. See -the [Super CX](super-cx.md) page. - -The [Agency Change Predictor](agency-change-predictor.md) is built on the same filters, but returns its own response. +| Model | Endpoint | Category specific? | +|-------------------------------------|------------------------------------------|:------------------:| +| [Brand Worth](brand-worth.md) | `POST /api/v2/brandscape/brand-worth` | :x: | +| [Imagery](imagery.md) | `POST /api/v2/brandscape/imagery` | :x: | +| [Influence](influence.md) | `POST /api/v2/brandscape/influence` | :x: | +| [Personality](personality.md) | `POST /api/v2/brandscape/personality` | :x: | +| [Pillars](pillars.md) | `POST /api/v2/brandscape/pillars` | :x: | +| [Powergrid](powergrid.md) | `POST /api/v2/brandscape/powergrid` | :x: | +| [Preferences](preferences.md) | `POST /api/v2/brandscape/preferences` | :white_check_mark: | +| [Recommendation](recommendation.md) | `POST /api/v2/brandscape/recommendation` | :white_check_mark: | +| [Super CX](super-cx.md) | `POST /api/v2/brandscape/super-cx` | :white_check_mark: | +| [Usage](usage.md) | `POST /api/v2/brandscape/usage` | :white_check_mark: | All data model endpoints require the **BAV Brand Data** (`bav:brand-data`) scope. @@ -43,14 +38,14 @@ it can significantly change the interpretation of the results. ## Creating a query Each model is available as a `POST` request to `/api/v2/brandscape/{model}` where the parameters are sent as a JSON -body. Most models are also available as a `GET` request to `/api/v2/tools/{model}` where the same parameters are sent -as query parameters. The two return the same response. +body. ```http request POST /api/v2/brandscape/pillars -GET /api/v2/tools/pillars?brands[]=148&countries[]=US&years[]=2025 ``` +Most models can also be requested with `GET` and query parameters, as part of the [tools](tools.md#data-model-tools). + ## Parameters All data model endpoints share the same set of parameters. diff --git a/docs/brand-data/imagery.md b/docs/brand-data/imagery.md index 53695d3..2c74ead 100644 --- a/docs/brand-data/imagery.md +++ b/docs/brand-data/imagery.md @@ -13,11 +13,9 @@ Imagery is category agnostic. ```http request POST /api/v2/brandscape/imagery -GET /api/v2/tools/imagery ``` -The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query -parameters. Both return the same response. +The parameters are sent as a JSON body. This endpoint requires the `bav:brand-data` scope. diff --git a/docs/brand-data/index.md b/docs/brand-data/index.md index b05176e..1c348e0 100644 --- a/docs/brand-data/index.md +++ b/docs/brand-data/index.md @@ -1,33 +1,15 @@ # Overview -The brand data endpoints give you access to BAV's research data on brands. They come in three kinds: +The brand data endpoints give you access to BAV's research data on brands. They come in two kinds: - **[Brandscape data](brandscape-data.md)** is the raw data: every metric for each brand, study and audience. Use it when you want full control over which metrics you use and how you combine them. - **[Data models](data-models.md)** return the metrics behind one of the core BAV models, such as the [Powergrid](powergrid.md), [Pillars](pillars.md) or [Imagery](imagery.md). You ask for the model, and get back the - relevant metrics for each brand, without needing to know which metrics make it up. All data models share the same - parameters and response. -- **Tools** do further work on the data, such as combining metrics to tell a specific story or running calculations to - arrive at new insights. They correspond to the tools in The Fount and its TurboPitch suite, such as the - [Commitment Funnel](commitment-funnel.md), [SWOT](swot.md) or [Agency Change Predictor](agency-change-predictor.md). - Each tool has its own parameters and response. + relevant metrics for each brand, without needing to know which metrics make up the model. All data models share the + same parameters and response. -Each endpoint page shows which parameters it takes and what the response looks like. We also suggest that you try each -tool in The Fount to get a better understanding of the results. - -## Access - -All tool endpoints require a token with the `bav:brand-data` scope. In addition, each tool requires that the user has -access to that tool in The Fount; otherwise a `403` response is returned. - -## Parameter formats - -Most tool endpoints take comma-separated lists of IDs, for example `brands=148,149`. Where a page lists a parameter as -taking a single ID, only one value is accepted. The [Commitment Funnel](commitment-funnel.md) instead follows the -[data models](data-models.md) and takes array parameters (`brands[]=148&brands[]=149`), which also accept -names, and can select studies by `countries` and `years`. - -Unless stated otherwise, the `audiences` parameter defaults to All Adults (audience ID `1`), and responses are returned -as JSON in a `data` key. +If you want BAV data with further work done on it, such as the Commitment Funnel, a SWOT or the Agency Change Predictor, +see the [tools](tools.md). +All brand data endpoints require a token with the **BAV Brand Data** (`bav:brand-data`) scope. diff --git a/docs/brand-data/influence.md b/docs/brand-data/influence.md index 1028eb0..0765b47 100644 --- a/docs/brand-data/influence.md +++ b/docs/brand-data/influence.md @@ -5,8 +5,6 @@ Innovation, Authenticity, Status, Trust, Convenience, Contemporary, Performance, Influence is category agnostic. -Influence is only available as a `POST` request. There is no `GET /api/v2/tools/influence` endpoint. - ## Creating a query ```http request diff --git a/docs/brand-data/personality.md b/docs/brand-data/personality.md index a5a6704..d38c96b 100644 --- a/docs/brand-data/personality.md +++ b/docs/brand-data/personality.md @@ -10,11 +10,9 @@ Personality is category agnostic. ```http request POST /api/v2/brandscape/personality -GET /api/v2/tools/personality ``` -The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query -parameters. Both return the same response. +The parameters are sent as a JSON body. This endpoint requires the `bav:brand-data` scope. diff --git a/docs/brand-data/pillars.md b/docs/brand-data/pillars.md index b4a83a3..a09e276 100644 --- a/docs/brand-data/pillars.md +++ b/docs/brand-data/pillars.md @@ -16,11 +16,9 @@ Pillars are category agnostic. ```http request POST /api/v2/brandscape/pillars -GET /api/v2/tools/pillars ``` -The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query -parameters. Both return the same response. +The parameters are sent as a JSON body. This endpoint requires the `bav:brand-data` scope. diff --git a/docs/brand-data/powergrid.md b/docs/brand-data/powergrid.md index 47a3a19..39f9ab9 100644 --- a/docs/brand-data/powergrid.md +++ b/docs/brand-data/powergrid.md @@ -26,11 +26,9 @@ The Powergrid is category agnostic. ```http request POST /api/v2/brandscape/powergrid -GET /api/v2/tools/powergrid ``` -The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query -parameters. Both return the same response. +The parameters are sent as a JSON body. This endpoint requires the `bav:brand-data` scope. diff --git a/docs/brand-data/preferences.md b/docs/brand-data/preferences.md index 9ff09f0..410d875 100644 --- a/docs/brand-data/preferences.md +++ b/docs/brand-data/preferences.md @@ -17,11 +17,9 @@ interpretation of the results. ```http request POST /api/v2/brandscape/preferences -GET /api/v2/tools/preferences ``` -The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query -parameters. Both return the same response. +The parameters are sent as a JSON body. This endpoint requires the `bav:brand-data` scope. diff --git a/docs/brand-data/recommendation.md b/docs/brand-data/recommendation.md index 241f767..ecfafb9 100644 --- a/docs/brand-data/recommendation.md +++ b/docs/brand-data/recommendation.md @@ -10,11 +10,9 @@ interpretation of the results. ```http request POST /api/v2/brandscape/recommendation -GET /api/v2/tools/recommendation ``` -The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query -parameters. Both return the same response. +The parameters are sent as a JSON body. This endpoint requires the `bav:brand-data` scope. diff --git a/docs/brand-data/super-cx-tool.md b/docs/brand-data/super-cx-tool.md new file mode 100644 index 0000000..1607994 --- /dev/null +++ b/docs/brand-data/super-cx-tool.md @@ -0,0 +1,71 @@ +--- +sidebar_label: Super CX +--- + +# Super CX Tool + +Super CX measures a brand's perceived customer experience. It is made up of the overall Super CX score and its Head, +Heart and X Factor components, which in turn are built from a set of underlying measures. + +Super CX is category specific. The category should always be shown together with the brand, as it can significantly +change the interpretation of the results. + +The Super CX tool returns the percentile ranks of the Super CX metrics for a set of brands in one study. For Super CX +data with the same parameters and response as the other data models, use the [Super CX data model](super-cx.md). + +## Creating a query + +```http request +GET /api/v2/tools/super-cx +``` + +This endpoint requires the `bav:brand-data` scope and that your account has access to the Super CX tool in The Fount. + +## Parameters + +| Key | Required? | Type | Description | +|-------------|:----------------------------:|---------------|------------------------------------------------| +| `brands` | :white_check_mark: | numeric array | A comma-separated list of Brand IDs. | +| `studies` | :white_check_mark: | numeric | A single Study ID. | +| `audiences` | :x: (defaults to All Adults) | numeric | A single Audience ID. | + +## Response + +The response contains a `data` array with one object per brand. + +| Key | Type | Description | +|------------|--------|-------------------------------------------------------------------------------------| +| `name` | string | The series name for the brand, for use as a label. | +| `study` | object | The [study](../studies/studies.md), with `id` and `name`. | +| `country` | object | The [country](../metadata/countries.md), with `id` and `name`. | +| `year` | object | The [year](../metadata/years.md), with `id` and `name`. | +| `audience` | object | The [audience](../audiences/audiences.md), with `id` and `name`. | +| `data` | object | The Super CX metrics, keyed by metric key. Each has a `label` and a `value`, where the `value` is the percentile rank (0-100). | + +The metric keys in `data` are: + +- `super_cx` - The overall Super CX score. +- `head`, `heart` and `x_factor` - The three components of Super CX. +- `value`, `simplicity`, `courtesy`, `committed`, `attracted` and `evangelical` - The underlying measures. + +```json +{ + "data": [ + { + "name": "Coca-Cola", + "study": { "id": 635, "name": "USA 2025" }, + "country": { "id": 6, "name": "United States" }, + "year": { "id": 45, "name": "2025" }, + "audience": { "id": 1, "name": "All Adults" }, + "data": { + "super_cx": { "label": "Super CX", "value": 82.4 }, + "head": { "label": "Head", "value": 75.1 }, + "heart": { "label": "Heart", "value": 88.0 }, + "x_factor": { "label": "X Factor", "value": 79.3 } + } + } + ] +} +``` + +The values in the example are illustrative, and only some of the metrics are shown. diff --git a/docs/brand-data/super-cx.md b/docs/brand-data/super-cx.md index 0db49ec..2c220e1 100644 --- a/docs/brand-data/super-cx.md +++ b/docs/brand-data/super-cx.md @@ -6,13 +6,10 @@ Heart and X Factor components, which in turn are built from a set of underlying Super CX is category specific. The category should always be shown together with the brand, as it can significantly change the interpretation of the results. -There are two ways to get Super CX data: the data model endpoint and the Super CX tool endpoint. We recommend the -data model endpoint for new integrations, as it shares its parameters and response with the -other [data models](data-models.md). +There is also a [Super CX tool](super-cx-tool.md) with its own parameters and response. We recommend this data model +endpoint for new integrations, as it shares its parameters and response with the other [data models](data-models.md). -## Data model - -### Creating a query +## Creating a query ```http request POST /api/v2/brandscape/super-cx @@ -20,74 +17,13 @@ POST /api/v2/brandscape/super-cx This endpoint requires the `bav:brand-data` scope. -### Parameters +## Parameters This endpoint takes the [shared data model parameters](data-models.md#parameters): `brands`, `studies`, `countries`, `years`, `audiences`, `study_types`, `benchmarks` and `format`. At least one of `brands`, `studies`, `countries` or `years` is required. -### Response +## Response The response follows the [standard data model schema](data-models.md#schema). The data points include the metrics in the `super-cx` [metric group](../metrics/metric-groups.md). - -## Super CX tool - -The Super CX tool endpoint returns the percentile ranks of the Super CX metrics for a set of brands in one study. - -### Creating a query - -```http request -GET /api/v2/tools/super-cx -``` - -This endpoint requires the `bav:brand-data` scope and that your account has access to the Super CX tool in The Fount. - -### Parameters - -| Key | Required? | Type | Description | -|-------------|:----------------------------:|---------------|------------------------------------------------| -| `brands` | :white_check_mark: | numeric array | A comma-separated list of Brand IDs. | -| `studies` | :white_check_mark: | numeric | A single Study ID. | -| `audiences` | :x: (defaults to All Adults) | numeric | A single Audience ID. | - -### Response - -The response contains a `data` array with one object per brand. - -| Key | Type | Description | -|------------|--------|-------------------------------------------------------------------------------------| -| `name` | string | The series name for the brand, for use as a label. | -| `study` | object | The [study](../studies/studies.md), with `id` and `name`. | -| `country` | object | The [country](../metadata/countries.md), with `id` and `name`. | -| `year` | object | The [year](../metadata/years.md), with `id` and `name`. | -| `audience` | object | The [audience](../audiences/audiences.md), with `id` and `name`. | -| `data` | object | The Super CX metrics, keyed by metric key. Each has a `label` and a `value`, where the `value` is the percentile rank (0-100). | - -The metric keys in `data` are: - -- `super_cx` - The overall Super CX score. -- `head`, `heart` and `x_factor` - The three components of Super CX. -- `value`, `simplicity`, `courtesy`, `committed`, `attracted` and `evangelical` - The underlying measures. - -```json -{ - "data": [ - { - "name": "Coca-Cola", - "study": { "id": 635, "name": "USA 2025" }, - "country": { "id": 6, "name": "United States" }, - "year": { "id": 45, "name": "2025" }, - "audience": { "id": 1, "name": "All Adults" }, - "data": { - "super_cx": { "label": "Super CX", "value": 82.4 }, - "head": { "label": "Head", "value": 75.1 }, - "heart": { "label": "Heart", "value": 88.0 }, - "x_factor": { "label": "X Factor", "value": 79.3 } - } - } - ] -} -``` - -The values in the example are illustrative, and only some of the metrics are shown. diff --git a/docs/brand-data/tools.md b/docs/brand-data/tools.md new file mode 100644 index 0000000..683fa04 --- /dev/null +++ b/docs/brand-data/tools.md @@ -0,0 +1,53 @@ +--- +sidebar_label: Overview +--- + +# Tools + +The tools do further work on BAV data, such as combining metrics to tell a specific story or running calculations to +arrive at new insights. They correspond to the tools in The Fount and its TurboPitch suite, such as the +[Commitment Funnel](commitment-funnel.md), [SWOT](swot.md) or [Agency Change Predictor](agency-change-predictor.md). + +Each tool has its own parameters and response, which are described on its page. We also suggest that you try each tool +in The Fount to get a better understanding of the results. + +If you only need the metrics behind a BAV model, such as the Powergrid or Pillars, use the +[data models](data-models.md) instead. + +## Access + +All tool endpoints require a token with the **BAV Brand Data** (`bav:brand-data`) scope. In addition, each tool +requires that the user has access to that tool in The Fount; otherwise a `403` response is returned. + +## Parameter formats + +Most tool endpoints take comma-separated lists of IDs, for example `brands=148,149`. Where a page lists a parameter as +taking a single ID, only one value is accepted. The [Commitment Funnel](commitment-funnel.md) and the +[Agency Change Predictor](agency-change-predictor.md) instead follow the [data models](data-models.md) and take array +parameters (`brands[]=148&brands[]=149`), which also accept names, and can select studies by `countries` and `years`. + +Unless stated otherwise, the `audiences` parameter defaults to All Adults (audience ID `1`), and responses are returned +as JSON in a `data` key. + +## Data model tools + +Most of the [data models](data-models.md) can also be requested as a tool, with a `GET` request and the +[data model parameters](data-models.md#parameters) sent as query parameters. The response is the same as for the data +model. + +| Tool | Endpoint | Same as | +|-------------------------------------|-----------------------------------|------------------------------------------| +| [Imagery](imagery.md) | `GET /api/v2/tools/imagery` | `POST /api/v2/brandscape/imagery` | +| [Personality](personality.md) | `GET /api/v2/tools/personality` | `POST /api/v2/brandscape/personality` | +| [Pillars](pillars.md) | `GET /api/v2/tools/pillars` | `POST /api/v2/brandscape/pillars` | +| [Powergrid](powergrid.md) | `GET /api/v2/tools/powergrid` | `POST /api/v2/brandscape/powergrid` | +| [Preferences](preferences.md) | `GET /api/v2/tools/preferences` | `POST /api/v2/brandscape/preferences` | +| [Recommendation](recommendation.md) | `GET /api/v2/tools/recommendation` | `POST /api/v2/brandscape/recommendation` | +| [Usage](usage.md) | `GET /api/v2/tools/usage` | `POST /api/v2/brandscape/usage` | + +```http request +GET /api/v2/tools/pillars?brands[]=148&countries[]=US&years[]=2025 +``` + +`GET /api/v2/tools/super-cx` is not the same as the Super CX data model. It is a separate +[Super CX tool](super-cx-tool.md) with its own parameters and response. diff --git a/docs/brand-data/usage.md b/docs/brand-data/usage.md index 3b38425..06787ce 100644 --- a/docs/brand-data/usage.md +++ b/docs/brand-data/usage.md @@ -17,11 +17,9 @@ results. ```http request POST /api/v2/brandscape/usage -GET /api/v2/tools/usage ``` -The `POST` endpoint takes its parameters as a JSON body, and the `GET` endpoint takes the same parameters as query -parameters. Both return the same response. +The parameters are sent as a JSON body. This endpoint requires the `bav:brand-data` scope. diff --git a/sidebars.js b/sidebars.js index 34dfb94..c4d244c 100644 --- a/sidebars.js +++ b/sidebars.js @@ -61,29 +61,37 @@ const sidebars = { 'brand-data/index', 'brand-data/brandscape-data', 'brand-data/data-models', - 'brand-data/agency-change-predictor', - 'brand-data/archetypes', - 'brand-data/brand-personality-match', - 'brand-data/brand-vulnerability-map', 'brand-data/brand-worth', - 'brand-data/brand-worth-map', - 'brand-data/category-worth-map', 'brand-data/cee-opinions', - 'brand-data/commitment-funnel', - 'brand-data/cost-of-entry', 'brand-data/imagery', 'brand-data/influence', - 'brand-data/love-plus', - 'brand-data/partnership-exchange-map', 'brand-data/personality', 'brand-data/pillars', 'brand-data/powergrid', 'brand-data/preferences', 'brand-data/recommendation', 'brand-data/super-cx', + 'brand-data/usage', + ], + }, + { + type: 'category', + label: 'Tools', + items: [ + 'brand-data/tools', + 'brand-data/agency-change-predictor', + 'brand-data/archetypes', + 'brand-data/brand-personality-match', + 'brand-data/brand-vulnerability-map', + 'brand-data/brand-worth-map', + 'brand-data/category-worth-map', + 'brand-data/commitment-funnel', + 'brand-data/cost-of-entry', + 'brand-data/love-plus', + 'brand-data/partnership-exchange-map', + 'brand-data/super-cx-tool', 'brand-data/swot', 'brand-data/toplist-market', - 'brand-data/usage', ], }, { From 9f4411a3b49f113afa95167f6085822dc3059b1d Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sun, 25 Oct 2026 10:33:29 +0100 Subject: [PATCH 14/23] Rewrite getting started, customizing and embed docs in Simplified Technical English Co-Authored-By: Claude Opus 5.5 --- docs/authentication.md | 270 +++++++++++++++++----------------- docs/customizing/fields.md | 30 ++-- docs/customizing/filters.md | 43 +++--- docs/customizing/includes.md | 26 ++-- docs/customizing/searching.md | 13 +- docs/embed/display-options.md | 10 +- docs/embed/implementation.md | 26 ++-- docs/embed/intro.md | 13 +- docs/errors.md | 22 +-- docs/health-check.md | 19 ++- docs/intro.md | 37 +++-- docs/pagination.md | 12 +- docs/rate-limiting.md | 20 +-- docs/versioning.md | 19 ++- docs/webhooks.md | 118 ++++++++------- 15 files changed, 341 insertions(+), 337 deletions(-) diff --git a/docs/authentication.md b/docs/authentication.md index 7bce806..d17f604 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -1,7 +1,7 @@ # Authentication -Every API request, except the [health check](health-check.md), needs an access token. You send it in the -`Authorization` header using the `Bearer` scheme: +Every API request, except the [health check](health-check.md), needs an access token. Send the token in the +`Authorization` header with the `Bearer` scheme: ```bash curl https://fount.wppbav.com/api/v2/brands \ @@ -9,12 +9,13 @@ curl https://fount.wppbav.com/api/v2/brands \ -H "Authorization: Bearer YOUR_TOKEN" ``` -There are a few ways to get a token, depending on who the request should be made as. +There are several methods to get a token. The correct method depends on the account that you want to make the request +as. :::caution -Please take care not to share your API keys, client secrets or access tokens with anyone. They should all be treated as -sensitive. Make sure they are not visible in any code you share publicly, committed to any repositories or otherwise -exposed. +Do not share your API keys, client secrets or access tokens with anyone. Treat all of them as sensitive data. Make sure +that they are not visible in code that you share publicly. Do not commit them to a repository or expose them in other +ways. ::: ## Choosing a method @@ -23,45 +24,45 @@ exposed. |-----------------------------------------------------------|------------------------------------------------|------------------------------------------------------------------------|-----------------------------------------------------------------------------| | [Personal access token](#personal-access-tokens) | You | Create it in the [API section in The Fount](https://fount.wppbav.com/api) | Scripts, notebooks and data pipelines that you run yourself. | | [Application API key](#application-api-keys) | The application | Create it on the application's page | Back-end integrations that use the application's own access. | -| [OAuth client credentials](#client-credentials-flow) | The application | Exchange a client ID and secret for a short-lived token | Machine-to-machine integrations that prefer OAuth over a long-lived key. | +| [OAuth client credentials](#client-credentials-flow) | The application | Exchange a client ID and secret for a short-lived token | Machine-to-machine integrations that prefer OAuth to a long-lived key. | | [OAuth authorization code](#authorization-code-flow) | A user who has authorized your application | The user signs in and approves your application | Applications where people sign in and see the data they have access to. | | [Acting on behalf of users](#acting-on-behalf-of-users) | Any user, named in the `X-Act-As-User` header | An application key or client credentials token, approved by us | Trusted internal platforms that have already signed the user in. | -Personal access tokens are the easiest way to get started. When you build something that other people will use, create +Personal access tokens are the easiest method to start with. If you build something that other people will use, create an [application](#applications) instead. :::tip We recommend OAuth -Where you can, use [OAuth 2](#oauth-2) rather than a long-lived personal access token or application API key. With -OAuth, users approve what your application can do and can revoke that access at any time, each request is made with the -permissions of the person using your application. Use the [authorization code flow](#authorization-code-flow) -when people sign in to your application, and the [client credentials flow](#client-credentials-flow) for -machine-to-machine integrations. +If possible, use [OAuth 2](#oauth-2) instead of a long-lived personal access token or application API key. With OAuth, +users approve what your application can do. They can revoke that access at any time. Each request has the permissions +of the person who uses your application. Use the [authorization code flow](#authorization-code-flow) when people sign +in to your application. Use the [client credentials flow](#client-credentials-flow) for machine-to-machine +integrations. ::: -Whichever method you use, the request has the permissions and data access of the account it is made as, and the token -must have the [scope](#scopes) the endpoint requires. +For all methods, the request has the permissions and data access of the account that it is made as. The token must +also have the [scope](#scopes) that the endpoint requires. ## Personal access tokens -A personal access token lets you call the API as yourself, without building an OAuth flow. Anything you can see in -The Fount, you can see through the API. +A personal access token lets you call the API as yourself. You do not need to build an OAuth flow. Through the API, you +can see all the data that you can see in The Fount. -You create and manage your tokens under **Personal API Keys** in the +Create and manage your tokens under **Personal API Keys** in the [API section in The Fount](https://fount.wppbav.com/api). When you create a key, you: - **Give it a name** so you can recognize it later. - **Choose an expiration** of 7, 30, 60 or 90 days. We strongly recommend that your keys expire. -- **Choose its scopes.** You can only pick the scopes for datasets you have access to. See [scopes](#scopes). +- **Choose its scopes.** You can only pick the scopes for datasets that you have access to. See [scopes](#scopes). -The key is only shown once, right after you create it, so store it somewhere safe. +The Fount shows the key only one time, immediately after you create it. Keep the key in a safe location. From the list of keys, you can: -- **Regenerate** a key. This replaces it with a new key that has the same name, scopes and expiry date. The old key - stops working immediately. -- **Revoke** a key. This deletes it and it stops working immediately. +- **Regenerate** a key. This replaces the key with a new key that has the same name, scopes and expiry date. The old + key becomes invalid immediately. +- **Revoke** a key. This deletes the key, and the key becomes invalid immediately. -We e-mail you seven days before one of your keys expires, and again on the day it expires. +We send you an e-mail seven days before one of your keys expires. We send another e-mail on the day that it expires. ```bash curl https://fount.wppbav.com/api/v2/brands \ @@ -71,19 +72,19 @@ curl https://fount.wppbav.com/api/v2/brands \ ## Applications -An application represents an integration, such as an internal tool, a data platform or an AI agent. You create it in -the [API section in The Fount](https://fount.wppbav.com/api) under **Applications**. Once you have an application, it -can: +An application represents an integration, for example an internal tool, a data platform or an AI agent. Create the +application under **Applications** in the [API section in The Fount](https://fount.wppbav.com/api). When you have an +application, it can: - call the API as itself, with [API keys](#application-api-keys) or the [client credentials flow](#client-credentials-flow); - let users sign in and authorize it through the [authorization code flow](#authorization-code-flow), and then call the API on their behalf; -- [act on behalf of users](#acting-on-behalf-of-users) without a sign-in, once it has been approved for it. +- [act on behalf of users](#acting-on-behalf-of-users) without a sign-in, after we approve it for this. ### Members and roles -Whoever creates an application becomes its owner. Owners and admins can add other existing users to the application -by their e-mail address, and give each of them a role: +The user who creates an application becomes its owner. Owners and admins can add other existing users to the +application by their e-mail address. They can give each of these users a role: | Role | Can | |-----------|-----------------------------------------------------------------------------------------------------------| @@ -92,25 +93,26 @@ by their e-mail address, and give each of them a role: | Developer | Edit existing OAuth clients and manage the application's API keys. | | Viewer | View the application's details. | -An application always keeps at least one owner. Only an owner can give, change or take away the Owner role. +An application always has at least one owner. Only an owner can give, change or remove the Owner role. ### Application access -When the application calls the API as itself, it has its own access to data, separate from that of its members. A new -application starts with only basic access. [Contact us](mailto:support@bernskiold.com) to have the access it needs -added. +When the application calls the API as itself, it has its own access to data. This access is separate from the access +of its members. A new application starts with only basic access. [Contact us](mailto:support@bernskiold.com) to get the +access that it needs. ### Application API keys An application API key works like a personal access token, but the request is made as the application. Owners, admins -and developers manage the keys under **API Keys** on the application's page, in the same way as -[personal access tokens](#personal-access-tokens). The scopes you can pick follow the access the application has been -given, not your own. +and developers manage the keys under **API Keys** on the application's page. They manage the keys in the same way as +[personal access tokens](#personal-access-tokens). The scopes that you can pick depend on the access of the +application, not on your access. -Expiry e-mails for an application's keys go to its owners, admins and developers. +Expiry e-mails for the keys of an application go to its owners, admins and developers. -For machine-to-machine integrations, we recommend the [client credentials flow](#client-credentials-flow) over an API -key. It gives the same access as the application, but with tokens that last an hour instead of a long-lived key. +For machine-to-machine integrations, we recommend the [client credentials flow](#client-credentials-flow) instead of an +API key. The flow gives the same access as the application, but its tokens are valid for one hour. An API key is +long-lived. ```bash curl https://fount.wppbav.com/api/v2/brands \ @@ -119,8 +121,8 @@ curl https://fount.wppbav.com/api/v2/brands \ ``` :::note Service accounts -Applications replace service accounts. Every service account has been converted to an application. Tokens issued to a -service account keep working, with the same access, and are now managed as the application's API keys. +Applications replace service accounts. We converted every service account to an application. Tokens that were issued +to a service account continue to work with the same access. You now manage them as the API keys of the application. ::: ### OAuth clients @@ -128,49 +130,52 @@ service account keep working, with the same access, and are now managed as the a To use OAuth, an application needs a client. Owners and admins create clients under **Clients** on the application's page. There are two kinds: -- **Authorization code clients** let users authorize your application. You give the client one or more **Redirect - URLs**, one per line, and users are only sent back to those URLs. -- **Client credentials clients** let the application request tokens for itself. You choose the scopes the client may be - issued. This kind of client is only available once we have enabled the client credentials flow for your application. +- **Authorization code clients** let users authorize your application. Give the client one or more **Redirect URLs**, + one on each line. The Fount redirects users only to those URLs. +- **Client credentials clients** let the application request tokens for itself. Choose the scopes that the tokens of + the client can have. This kind of client is available only after we enable the client credentials flow for your + application. -When you create a client, you get a **Client ID** and a **Client Secret**. The secret is only shown once. You can -**Rotate Secret** on a client at any time, and the old secret stops working immediately. Deleting a client revokes -every token it has issued. +When you create a client, you get a **Client ID** and a **Client Secret**. The Fount shows the secret only one time. +You can use **Rotate Secret** on a client at any time. The old secret then becomes invalid immediately. If you delete a +client, all the tokens that it issued are revoked. -Clients created in The Fount are confidential clients. They have a secret, which must be kept on your server. +Clients that you create in The Fount are confidential clients. They have a secret, and you must keep the secret on your +server. ### Restricting where API calls come from -You can limit the IP addresses an application calls the API from, under **Allowed API IP Addresses** when you edit the -application. Enter one IP address or CIDR range per line, such as `203.0.113.10` or `198.51.100.0/24`. +You can limit the IP addresses that an application can call the API from. Use **Allowed API IP Addresses** when you +edit the application. Enter one IP address or CIDR range on each line, for example `203.0.113.10` or +`198.51.100.0/24`. -The allow-list covers every request the application makes: +The allow-list applies to all the requests that the application makes: - requests with its API keys; - requests with client credentials tokens, and the token request itself; - requests with OAuth tokens that users have issued to it; - requests where it acts on behalf of users. -A request from any other address gets a `403` error. If the list is empty, the application can call the API from -anywhere. +A request from a different address gets a `403` error. If the list is empty, the application can call the API from any +address. ## OAuth 2 The Fount is an OAuth 2 authorization server. Use these endpoints: -| Endpoint | Method | Used for | -|-----------------------------------------------|--------|--------------------------------------------------------------| -| `https://fount.wppbav.com/oauth/authorize` | `GET` | Sending the user to sign in and authorize your application. | -| `https://fount.wppbav.com/oauth/token` | `POST` | Getting an access token, refreshing it, or client credentials. | -| `https://fount.wppbav.com/oauth/userinfo` | `GET` | Getting the profile of the user who authorized the token. | +| Endpoint | Method | Used for | +|-----------------------------------------------|--------|-------------------------------------------------------------------------| +| `https://fount.wppbav.com/oauth/authorize` | `GET` | To send the user to sign in and authorize your application. | +| `https://fount.wppbav.com/oauth/token` | `POST` | To get an access token, to refresh it, or to use client credentials. | +| `https://fount.wppbav.com/oauth/userinfo` | `GET` | To get the profile of the user who authorized the token. | Request scopes as a space-separated list in the `scope` parameter, for example -`scope=bav:shared-resources bav:brand-data`. See [scopes](#scopes) for what is available. The `*` scope is ignored in -the authorization code flow. +`scope=bav:shared-resources bav:brand-data`. See [scopes](#scopes) for the available scopes. The authorization code +flow ignores the `*` scope. ### Authorization code flow -Use this flow when people sign in to your application with their WPP account and you want to call the API as them. The +Use this flow if people sign in to your application with their WPP account. The flow lets you call the API as them. The request then has their permissions and data access. **1. Send the user to the authorization endpoint.** @@ -186,23 +191,23 @@ https://fount.wppbav.com/oauth/authorize &code_challenge_method=S256 ``` -The `redirect_uri` must match one of the client's redirect URLs exactly. Use `state` to protect against cross-site -request forgery and check it when the user comes back. +The `redirect_uri` must exactly match one of the redirect URLs of the client. Use `state` to protect against cross-site +request forgery. Check `state` when the user returns. PKCE (`code_challenge` and `code_challenge_method`) is optional for confidential clients, but we recommend it. Use the `S256` method. -**2. The user signs in and approves your application.** The consent screen lists the scopes you asked for, and the user -can authorize or deny the request. The user isn't asked again if they have already authorized the same scopes for your -client and that token is still valid. Add `prompt=consent` to always show the consent screen. +**2. The user signs in and approves your application.** The consent screen shows the scopes that you asked for. The +user can authorize or deny the request. The Fount does not ask the user again if they already authorized the same +scopes for your client and that token is still valid. To always show the consent screen, add `prompt=consent`. -**3. The user is sent back to your redirect URL** with a `code` and your `state`: +**3. The Fount sends the user to your redirect URL** with a `code` and your `state`: ``` https://app.example.com/oauth/callback?code=def50200a1b2c3...&state=RANDOM_STATE ``` -The code is valid for 10 minutes and can only be used once. +The code is valid for 10 minutes. You can use it only one time. **4. Exchange the code for tokens** from your server: @@ -248,12 +253,12 @@ curl -X POST https://fount.wppbav.com/oauth/token \ -d refresh_token=def50200d4e5f6... ``` -The response has a new access token and a new refresh token. The old refresh token can't be used again. +The response contains a new access token and a new refresh token. You cannot use the old refresh token again. #### Getting the user's profile With the `profile` scope, you can get the profile of the user who authorized the token from the `userinfo` endpoint. -This only works with tokens from the authorization code flow. +This works only with tokens from the authorization code flow. ```bash curl https://fount.wppbav.com/oauth/userinfo \ @@ -291,22 +296,23 @@ curl https://fount.wppbav.com/oauth/userinfo \ } ``` -`operating_company` and `country` are left out when they aren't set for the user. +If `operating_company` or `country` is not set for the user, the response does not include it. #### Trusted applications -For internal applications, we can mark the application as trusted and skip the consent screen. Consent is only skipped -when the authorization request comes from one of the trusted IP addresses we set up for the application, for example -your office or VPN network. From anywhere else, the user sees the consent screen as usual. +For internal applications, we can mark the application as trusted and skip the consent screen. The consent screen is +skipped only if the authorization request comes from a trusted IP address. We set up these addresses for the +application, for example for your office or VPN network. From all other addresses, the user sees the consent screen as +usual. These trusted IP addresses are separate from the [allowed API IP addresses](#restricting-where-api-calls-come-from). -[Contact us](mailto:support@bernskiold.com) if you'd like your application set up as trusted. +[Contact us](mailto:support@bernskiold.com) if you want us to set up your application as trusted. ### Client credentials flow -Use this flow when the application calls the API as itself and you'd rather use OAuth than a long-lived -[API key](#application-api-keys). The request is made as the application, just as with an API key. The client -credentials flow needs to be enabled for your application by us, and you need a client credentials client. +Use this flow if the application calls the API as itself and you prefer OAuth to a long-lived +[API key](#application-api-keys). The request is made as the application, the same as with an API key. We must enable +the client credentials flow for your application. You also need a client credentials client. ```bash curl -X POST https://fount.wppbav.com/oauth/token \ @@ -325,22 +331,23 @@ curl -X POST https://fount.wppbav.com/oauth/token \ } ``` -- The token is valid for **one hour**, and there is no refresh token. Request a new token when it expires. -- The token can only have the scopes set on the client, which you choose when you create or edit the client. Asking for - any other scope, including `*`, returns an `invalid_scope` error. -- If you leave out `scope`, the token gets every scope on the client except `act-as-user`, which you have to ask for by - name. -- The token request is refused if the client has no scopes, if the client credentials flow isn't enabled for the - application, or if the request comes from an address outside the - [allowed API IP addresses](#restricting-where-api-calls-come-from). +- The token is valid for **one hour**, and there is no refresh token. When the token expires, request a new token. +- The token can have only the scopes that are set on the client. You choose these scopes when you create or edit the + client. If you ask for a different scope, including `*`, you get an `invalid_scope` error. +- If you do not send `scope`, the token gets all the scopes on the client except `act-as-user`. You must ask for + `act-as-user` by name. +- The Fount refuses the token request if: + - the client has no scopes; + - the client credentials flow is not enabled for the application; + - the request comes from an address outside the [allowed API IP addresses](#restricting-where-api-calls-come-from). -Scope changes on a client apply to new tokens. Tokens already issued keep their scopes until they expire. +Scope changes on a client apply to new tokens. Tokens that were already issued keep their scopes until they expire. ## Acting on behalf of users -A trusted application can make a request as any user by sending the user's e-mail address in the `X-Act-As-User` -header. The request is then made as that user, with their permissions and data access. Use this for internal platforms -that have already signed the user in and can't send them through the OAuth flow. +A trusted application can make a request as any user. To do this, send the e-mail address of the user in the +`X-Act-As-User` header. The request is then made as that user, with their permissions and data access. Use this for +internal platforms that have already signed the user in and cannot send them through the OAuth flow. ```bash curl https://fount.wppbav.com/api/v2/brands \ @@ -349,21 +356,21 @@ curl https://fount.wppbav.com/api/v2/brands \ -H "X-Act-As-User: jane.doe@example.com" ``` -All of these are required: +All of these conditions must be true: -- **The application is trusted and approved to act on behalf of users.** This is set by us. +- **The application is trusted and approved to act on behalf of users.** We set this. [Contact us](mailto:support@bernskiold.com) if your application needs it. - **The token belongs to the application.** Use an [application API key](#application-api-keys) or a [client credentials token](#client-credentials-flow). A token that a user issued to your application through the - authorization code flow can't act as another user, and neither can a personal access token. -- **The token has the `act-as-user` scope by name.** The scope is only offered once the application is approved. The - `*` scope doesn't include it, and a client credentials token only gets it when you ask for it in `scope`. + authorization code flow cannot act as another user. A personal access token also cannot act as another user. +- **The token has the `act-as-user` scope by name.** The scope is available only after the application is approved. + The `*` scope does not include it. A client credentials token gets it only if you ask for it in `scope`. - **The request comes from an allowed address**, if the application has [allowed API IP addresses](#restricting-where-api-calls-come-from). -The user must be an active user. If no user has the e-mail address, a `422` error is returned. +The user must be an active user. If no user has the e-mail address, you get a `422` error. -Activity performed this way is recorded against the user, and notes that it was made through your application. +The Fount records this activity against the user. The record also shows that your application made the request. ## IP restrictions @@ -372,11 +379,11 @@ There are two separate IP lists on an application: | Setting | What it does | Set by | |-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|-----------------| | Allowed API IP Addresses | Limits where the application can call the API from. Other addresses get a `403`. Empty means any address. See [above](#restricting-where-api-calls-come-from). | Owners and admins | -| Trusted IP addresses | Where users can authorize a [trusted application](#trusted-applications) without the consent screen. Doesn't block any requests. | Us | +| Trusted IP addresses | Where users can authorize a [trusted application](#trusted-applications) without the consent screen. Does not block requests. | Us | ## Errors -Authentication errors are always returned as JSON with a `message`, even if you don't send an `Accept` header. +The API always returns authentication errors as JSON with a `message`, even if you do not send an `Accept` header. ```json { @@ -386,20 +393,20 @@ Authentication errors are always returned as JSON with a `message`, even if you | Code | Message | Cause | |-------|-------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| -| `401` | `Unauthenticated.` | The token is missing, invalid, revoked or expired, or it's a client credentials token for an application that no longer allows the flow. | -| `401` | `Your API key does not have the required permissions to perform the requested action: …` | The token doesn't have the [scope](#scopes) the endpoint requires. The message names the scope. | +| `401` | `Unauthenticated.` | The token is missing, invalid, revoked or expired. Or it is a client credentials token for an application that no longer allows the flow. | +| `401` | `Your API key does not have the required permissions to perform the requested action: …` | The token does not have the [scope](#scopes) that the endpoint requires. The message names the scope. | | `403` | `This application does not allow requests from this IP address.` | The request comes from outside the application's [allowed API IP addresses](#restricting-where-api-calls-come-from). | | `403` | `This application has been deactivated.` | The application has been deactivated. | | `403` | `A token issued to a user cannot act as another user.` | `X-Act-As-User` was sent with an OAuth token issued to a user. | | `403` | `This token is not allowed to act as another user.` | `X-Act-As-User` was sent with a personal access token. | -| `403` | `This application is not allowed to act on behalf of users.` | The application isn't trusted and approved to act on behalf of users. | -| `403` | `The token does not have the act-as-user scope.` | The application's token doesn't name the `act-as-user` scope. | +| `403` | `This application is not allowed to act on behalf of users.` | The application is not trusted and approved to act on behalf of users. | +| `403` | `The token does not have the act-as-user scope.` | The application's token does not name the `act-as-user` scope. | | `403` | `The user to act as is not active.` | The user in `X-Act-As-User` has been deactivated. | | `403` | `An application cannot act as another application.` | The e-mail address in `X-Act-As-User` belongs to an application. | -| `422` | `The user to act as must be given as an e-mail address.` | `X-Act-As-User` isn't a valid e-mail address. | +| `422` | `The user to act as must be given as an e-mail address.` | `X-Act-As-User` is not a valid e-mail address. | | `422` | `No user exists with this e-mail address.` | No user has the e-mail address in `X-Act-As-User`. | -A `403` can also mean that the account the request is made as doesn't have access to the resource or action. See +A `403` can also mean that the account that the request is made as does not have access to the resource or action. See [errors](errors.md). The token endpoint returns errors in the OAuth 2 format, for example: @@ -415,49 +422,50 @@ The token endpoint returns errors in the OAuth 2 format, for example: ## Scopes -We allow you to create integrations and API keys that have different levels of access to your account. This is done -through scopes. +You can create integrations and API keys that have different levels of access to your account. Scopes control this +access. -Scopes are broad and each one covers a group of endpoints, typically a dataset. For example, to list brands using the -`/brands` endpoint, your token needs the `bav:shared-resources` scope, and to get data from the `/brandscape-data` -endpoint, it needs the `bav:brand-data` scope. +Scopes are broad, and each scope covers a group of endpoints, usually a dataset. For example, to list brands with the +`/brands` endpoint, your token needs the `bav:shared-resources` scope. To get data from the `/brandscape-data` +endpoint, your token needs the `bav:brand-data` scope. -If your token doesn't have the scope that an endpoint requires, a `401` error is returned with a message telling you -which scope is missing. +If your token does not have the scope that an endpoint requires, you get a `401` error. The message tells you which +scope is missing. You choose the scopes when you create a personal access token, an application API key or a client credentials client. -With the authorization code flow, you ask for them in the `scope` parameter. +With the authorization code flow, ask for the scopes in the `scope` parameter. ### Available scopes | Scope | Name | Covers | |----------------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bav:shared-resources` | Shared Resources | Shared reference data: brands, brand tags, collections, audiences and audience groups (reading), studies and their categories (`/studies/{id}/categories`), years, countries, cities, regions, sectors, GICS sectors, companies, stock prices, stock exchanges, operating companies, tools and the stock performance slide deck (`/slide-decks/stock-performance`). | +| `bav:shared-resources` | Shared Resources | Shared reference data: brands, brand tags, collections, audiences and audience groups (read only), studies and their categories (`/studies/{id}/categories`), years, countries, cities, regions, sectors, GICS sectors, companies, stock prices, stock exchanges, operating companies, tools and the stock performance slide deck (`/slide-decks/stock-performance`). | | `bav:brand-data` | BAV Brand Data | BAV brand research data and analysis: brandscape data, the brandscape data models (`/brandscape/...`), the tool endpoints (`/tools/...`), categories, brand variations, brand metrics and brand metric groups, brand measures and brand measure groups, BAV questions and question groups, CEE opinions, and the study-level endpoints for brands, brand metrics, brand measures, BAV questions and audience questions. | | `bav:best-countries-data` | Best Countries Data | Best Countries research data: the `/best-countries/...` and `/flourish/best-countries/...` endpoints, Best Countries metrics, metric groups and factors. | | `bav:audience-origin-data` | Audience Origin Data | Audience Origin data: the `/audience-origin/...` endpoints (metrics, metric groups, touchpoints, frequencies and queries) and the audience respondent ID endpoints (`/audiences/{id}/respondents/...`). | | `bav:market-share-data` | Market Share Data | Euromonitor market share data: the `/market-share/...` endpoints, including the brand and company shares and the catalogs of brands, companies, categories, geographies, industries and data types. | -| `bav:audiences:write` | Build Audiences | Creating, updating and deleting audiences, audience segments and segment metrics, and deploying audiences (`/audiences/{id}/deploy`). Reading audiences only requires `bav:shared-resources`. | -| `bav:collections:write` | Create Collections | Creating and managing brand collections. The collection endpoints in the REST API are currently read-only and only require `bav:shared-resources`. | -| `profile` | User Profile | The authenticated user's profile information from the [`/oauth/userinfo`](#getting-the-users-profile) endpoint. | +| `bav:audiences:write` | Build Audiences | Permission to create, update and delete audiences, audience segments and segment metrics, and to deploy audiences (`/audiences/{id}/deploy`). To read audiences, a token needs only `bav:shared-resources`. | +| `bav:collections:write` | Create Collections | Permission to create and manage brand collections. The collection endpoints in the REST API are currently read-only and need only `bav:shared-resources`. | +| `profile` | User Profile | The profile information of the authenticated user from the [`/oauth/userinfo`](#getting-the-users-profile) endpoint. | -The [health check](health-check.md) endpoint doesn't require authentication or any scope. +The [health check](health-check.md) endpoint does not require authentication or a scope. ### Scopes and permissions -Most of the dataset scopes are tied to a permission in The Fount. You can only give a scope to a key when the account -it belongs to has access to the dataset it covers. For example, the `bav:best-countries-data` scope is only available -on a personal access token if you have access to Best Countries. For an application's API keys and client credentials -clients, the scopes on offer depend on the [application's access](#application-access), not on yours. +Most of the dataset scopes are linked to a permission in The Fount. You can give a scope to a key only if the account +of the key has access to the dataset that the scope covers. For example, the `bav:best-countries-data` scope is +available on a personal access token only if you have access to Best Countries. For the API keys and client credentials +clients of an application, the available scopes depend on the [application's access](#application-access), not on your +access. -Scopes control which endpoints a token can use. Within those endpoints, you can still only see the data that the -account the request is made as has access to. If that account doesn't have permission to perform an action or see a -resource, a `403` error is returned. +Scopes control which endpoints a token can use. In those endpoints, you can see only the data that the account of the +request has access to. If that account does not have permission to do an action or see a resource, you get a `403` +error. ### System scopes -Some scopes are not for general use and can't be self-assigned. The `act-as-user` scope lets an approved application -[act on behalf of users](#acting-on-behalf-of-users). It is only offered on an application's own API keys and client -credentials clients once the application has been approved to act on behalf of users. +Some scopes are not for general use, and you cannot assign them to yourself. The `act-as-user` scope lets an approved +application [act on behalf of users](#acting-on-behalf-of-users). It is available only on the API keys and client +credentials clients of an application. The application must first be approved to act on behalf of users. -[Contact us](mailto:support@bernskiold.com) if you think your integration needs it. +[Contact us](mailto:support@bernskiold.com) if you think that your integration needs it. diff --git a/docs/customizing/fields.md b/docs/customizing/fields.md index 31668ed..9dfb8f4 100644 --- a/docs/customizing/fields.md +++ b/docs/customizing/fields.md @@ -1,24 +1,24 @@ # Configurable fields -Since the BAV data and The Fount API is expansive and endpoints contain a lot of data the API responses can easily grow -in size. A downside of REST APIs in general. +The BAV data and The Fount API are expansive, and endpoints contain a lot of data. Because of this, the API responses +can become large. This is a general disadvantage of REST APIs. -To prevent forcing you to retrieve a full object with all resource data, you may configure to request only specific +You do not have to get a full object with all the resource data. You can configure the request to get only specific fields. -You may choose to configure to include any fields in the response. By default all fields are included. If choose to -include specific fields you will need to specify all fields you want to include. There is no option to exclude fields. +You can configure the response to include any fields. By default, all fields are included. If you include specific +fields, you must specify all the fields that you want to include. You cannot exclude fields. -Fields loaded via [includes](includes.md) are not configurable. The fields included via these relations are slimmed-down -relation responses. Each endpoint documentation includes the schema for the relationship response alongside the full -response. +You cannot configure the fields that you load through [includes](includes.md). The fields from these relations are +slimmed-down relation responses. The documentation for each endpoint contains the schema for the relationship response +and the full response. -Configurable fields are available on both indexes and single resource endpoints. +Configurable fields are available on index endpoints and single resource endpoints. ## Making a request -Configuring fields is done by adding the `fields` query parameter, the snake-case name of the resource, and passing a comma-separated string of field names, -like so: +To configure fields, add the `fields` query parameter with the snake-case name of the resource. Give a comma-separated +string of field names as the value, for example: ```http request GET /api/v2/brands?fields[brands]=id,name @@ -26,15 +26,15 @@ GET /api/v2/brands?fields[brands]=id,name ## Example: Getting a list of brands for a dropdown selection -Let's say you want to retrieve a list of brands to show in a dropdown for users to select. You'll want the brand ID for -the value and the name for the display label. Instead of forcing you to download the -full [Brands response](../brands/brands.md), you may configure to only retrieve the columns you need. +For example, you want to get a list of brands to show in a dropdown where users select a brand. You need the brand ID +for the value and the name for the display label. You do not have to download the +full [Brands response](../brands/brands.md). You can configure the request to get only the columns that you need. ```http request GET /api/v2/brands?fields[brands]=id,name ``` -This request would result in the following lean response: +This request gives this lean response: ```json { diff --git a/docs/customizing/filters.md b/docs/customizing/filters.md index 88bb7a0..10669a5 100644 --- a/docs/customizing/filters.md +++ b/docs/customizing/filters.md @@ -2,37 +2,38 @@ ## Filters -To allow you to retrieve only the data that you need each resource comes with a set of filters. Some filters are -globally available throughout all resources, while some are resource-specific. +Each resource has a set of filters, so you can get only the data that you need. Some filters are available for all +resources, and some filters are specific to a resource. -Each resource documentation contains a list of which fields are filterable. Below you'll find information for the -globally available filters. +The documentation for each resource contains a list of the fields that you can filter on. Below is information about +the filters that are available for all resources. -Filters are applied via query parameters to the request URL. They are built up on the format: `filter[field]=value`. +Apply filters with query parameters on the request URL. Filters use the format `filter[field]=value`. -For example, to search for brands with the name "Facebook" you would use the following request: +For example, to search for brands with the name "Facebook", use this request: ```http request GET /api/v2/brands?filter[name]=Facebook ``` :::note -In general all filters apart from ID filters are applied using a like/contains search. This means that a search for " -Facebook" will also return "Facebook Messenger". +In general, all filters except ID filters use a like/contains search. This means that a search for "Facebook" also +returns "Facebook Messenger". ::: ## Sorting Results -All index resources can be sorted to present data in a specific order. Default sorting varies by resource and can be -found in the respective resource documentation. Generally resources are sorted by their `id` field in ascending order. +You can sort all index resources to show data in a specific order. The default sort order is different for each +resource. You can find it in the documentation for the resource. Usually, resources are sorted by their `id` field in +ascending order. -Each resource also has a set number of "sortable fields". Each endpoint documentation will list which fields are +Each resource also has a set of "sortable fields". The documentation for each endpoint lists the fields that are sortable. -You define the sort order by setting the `sort` parameter and the field you want to sort on. To sort in descending order -you prefix the column with a minus `-` sign. +To set the sort order, set the `sort` parameter to the field that you want to sort on. To sort in descending order, put +a minus `-` sign before the column name. -A sorting query to show brands by name may look like this: +A query that sorts brands by name can look like this: ```http request # Sort in ascending order (A-Z). @@ -44,19 +45,19 @@ GET /api/v2/brands?sort=-name ## Updated Since -You may choose to retrieve data on an index request that has been updated after a specific date and time. This is done -via the `updated_since` filter. This takes a date time value of `YYYY-MM-DD HH:II:SS`. +On an index request, you can get only the data that was updated after a specific date and time. To do this, use the +`updated_since` filter. This filter takes a date time value in the format `YYYY-MM-DD HH:II:SS`. -A request to show brands that have been updated only after January 1, 2023 may look like this: +A request that shows only the brands that were updated after January 1, 2023 can look like this: ```http request GET /api/v2/brands?filter[updated_since]=2023-01-01 ``` -Please note that update times are generally shallow. For example, if a brand's brandscape data is updated, the updated -timestamp for the brand itself does not change. However, if the brand itself receives an update to its global brand -name, the timestamp is changed. +Update times are usually shallow. For example, if the brandscape data of a brand is updated, the updated timestamp of +the brand itself does not change. But if the brand itself gets an update to its global brand name, the timestamp +changes. ## Pagination -Please refer to the [pagination section](../pagination.md) of the documentation for more information on pagination. +For more information about pagination, see the [pagination section](../pagination.md) of the documentation. diff --git a/docs/customizing/includes.md b/docs/customizing/includes.md index f02b838..ec45679 100644 --- a/docs/customizing/includes.md +++ b/docs/customizing/includes.md @@ -1,32 +1,32 @@ # Includes -The BAV The Fount API is expansive and contains many relationships. Loading all of these for every request by default -would make the request larger than necessary. Instead, we allow you to select which relationships you want to include -using the includes feature. +The BAV The Fount API is expansive and contains many relationships. The API does not load all of these for every +request by default, because this makes the request larger than necessary. Instead, you can use the includes feature to +select the relationships that you want to include. Includes are available on both index and single resource endpoints. -Each resource documentation contains a list of relationships and names that can be included. +The documentation for each resource contains a list of relationships and names that you can include. -Included resources only contain a subset of the data that the relationship resource has to make the response leaner. If -you need the full data, please make a second query using the system ID to the respective endpoint. Both the full -response schema and the slim, relationship schema is listed on each endpoint. +To make the response leaner, included resources contain only a subset of the data of the relationship resource. If you +need the full data, make a second query to the applicable endpoint with the system ID. Each endpoint shows both the +full response schema and the slim relationship schema. :::note Relationships are excluded by default -When you make a query to an endpoint that has relationships these are not loaded by default. For example, if you want to -access the sector for a brand (a relationship), you need to explicitly request it with the `include` parameter. +When you query an endpoint that has relationships, the API does not load these relationships by default. For example, +if you want to get the sector for a brand (a relationship), you must request it explicitly with the `include` +parameter. ::: ## Making a request -Adding an expansion is done by adding the `include` query parameter, and passing a comma-separated string of -relationship names, like so: +To add an include, add the `include` query parameter with a comma-separated string of relationship names, for example: ```http request GET /api/v2/brands/369?include=sector ``` -This would result in the following response: +This request gives this response: ```json { @@ -41,4 +41,4 @@ This would result in the following response: "updated_at": "2021-03-26T10:43:02.000000Z" } } -``` +``` \ No newline at end of file diff --git a/docs/customizing/searching.md b/docs/customizing/searching.md index bbd09c1..3e920d7 100644 --- a/docs/customizing/searching.md +++ b/docs/customizing/searching.md @@ -1,10 +1,9 @@ # Searching -Many API resources have support for searching in addition to filtering on fields. The difference between filtering on -fields and searching is that searching uses our underlying search index which evaluates multiple fields at once, -interprets language better and prioritizes results. +Many API resources support search in addition to filters on fields. The difference is that search uses our search +index. The search index evaluates several fields at the same time, interprets language better and ranks the results. -Each API endpoint documentation will show if it supports searching. +The documentation for each API endpoint shows if the endpoint supports search. ## Parameters @@ -20,7 +19,7 @@ Search results are ordered by relevance, with the best matches first. If you als results are ordered by your sort instead. :::note Search is limited to 1000 results -A search returns at most the 1000 best matches, regardless of how many records actually match. Pagination works -within those results, so you can't page past the first 1000 matches. If you need more results, make your search more -specific or combine it with [filters](filters.md) instead. +A search returns a maximum of the 1000 best matches, even if more records match. Pagination works only in those +results, so you cannot page past the first 1000 matches. If you need more results, make your search more specific, or +combine it with [filters](filters.md) instead. ::: diff --git a/docs/embed/display-options.md b/docs/embed/display-options.md index 0e7390b..011588b 100644 --- a/docs/embed/display-options.md +++ b/docs/embed/display-options.md @@ -1,14 +1,14 @@ # Display Options -By default when using the embeddable products, the BAV application scaffolding is hidden. This means the top header bar -and the left sidebar navigation. +By default, the embeddable products hide the BAV application scaffolding. The scaffolding is the top header bar and the +left sidebar navigation. ## Hiding the step bar -If you want to provide the product with all the required filters and not allow the user to change them you can hide the -step navigation UI that would allow the user to change the parameters. +You can give the product all the required filters and not let the user change them. To do this, hide the step +navigation UI that lets the user change the parameters. -Provide the `showStepsUi` query parameter in the iframe request and set it to `false`. +Add the `showStepsUi` query parameter to the iframe request and set it to `false`. ```html diff --git a/docs/embed/implementation.md b/docs/embed/implementation.md index f423f4c..1cc776d 100644 --- a/docs/embed/implementation.md +++ b/docs/embed/implementation.md @@ -2,17 +2,16 @@ ## 1. Authenticate your user -To bypass the Okta login screen in the embed we allow you to pre-authenticate your user. There are a couple of -dependencies: +To bypass the Okta login screen in the embed, you can pre-authenticate your user. There are some dependencies: -- The API key you use must have a specific set of permissions (please contact support@bernskiold.com to receive - these) -- Your application should be using Okta. +- The API key that you use must have a specific set of permissions. Contact support@bernskiold.com to get these + permissions. +- Your application must use Okta. - You can pass an email address, first name and last name of your user. :::note Getting access approval -To use the embed integration through our auto-login flow and bypass a user connection approval screen you will need to -request approval. Please contact support@bernskiold.com. +To use the embed integration through our auto-login flow and bypass a user connection approval screen, you must +request approval. Contact support@bernskiold.com. ::: :::tip How to authenticate? @@ -22,8 +21,6 @@ in the API docs. To authenticate the user, make a request against the auto login endpoint: -To authenticate the user, make a request against the auto login endpoint: - ```json POST https://fount.wppbav.com/api/v1/auto-login @@ -34,7 +31,7 @@ POST https://fount.wppbav.com/api/v1/auto-login } ``` -Your request will return an access token for the user that you will need to pass to the embed iframe in the next step. +The request returns an access token for the user. Pass this token to the embed iframe in the next step. ```json { @@ -48,16 +45,15 @@ Access tokens expire every day at 00:00 UTC. ## 2. Embed the iframe -With the user authenticated, you can embed the iframe. At its simplest, you only need the embed product URL and the -access token: +After you authenticate the user, you can embed the iframe. In the simplest case, you need only the embed product URL +and the access token: ```html ``` -From the supported products endpoint you can find the required and optional filters that you may pre-populate the -request with. +The supported products endpoint gives the required and optional filters that you can pre-populate the request with. ```html @@ -65,5 +61,5 @@ request with. ``` :::caution Parameters Format -The supported parameters should always be passed in an array format, for example:`?brands[0]=998&brands[1]=999` +Always pass the supported parameters in an array format, for example:`?brands[0]=998&brands[1]=999` ::: \ No newline at end of file diff --git a/docs/embed/intro.md b/docs/embed/intro.md index c9383c9..99176ce 100644 --- a/docs/embed/intro.md +++ b/docs/embed/intro.md @@ -4,15 +4,14 @@ sidebar_label: Introduction # Embed Integration -BAV offers the option to integrate its analytical tools into your application via an embedded integration. It -allows you to embed any of the BAV products into your application via an iframe, with our application scaffolding -removed. It also allows you to pass and log in as the existing user from your application, making the experience -seamless for the user. +BAV gives you the option to integrate its analytical tools into your application through an embedded integration. You +can embed any of the BAV products into your application in an iframe, without our application scaffolding. You can +also pass the existing user from your application and log in as that user. This gives the user a seamless experience. ## How does it work? -On a high level, the integration flow consists of: +At a high level, the integration flow has these steps: -1. Authenticating a user against the BAV API and receiving an authentication token. -2. Calling the embeddable product in an iframe with the authentication token and the required parameters for the +1. Authenticate a user against the BAV API and receive an authentication token. +2. Call the embeddable product in an iframe with the authentication token and the required parameters for the product. \ No newline at end of file diff --git a/docs/errors.md b/docs/errors.md index 1ac7e13..737474e 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -1,15 +1,15 @@ # Errors -The Fount's API uses standard HTTP response codes to indicate success or failure of an API request. +The Fount's API uses standard HTTP response codes to show if an API request succeeded or failed. -In general codes in the `200` range indicate success. Codes in the `400` range indicate some sort of error in the -information provided. Codes in the `500` range indicate errors with The Fount's servers and systems. +Usually, codes in the `200` range show success. Codes in the `400` range show an error in the information that you +sent. Codes in the `500` range show errors with The Fount's servers and systems. -Along with the response code a human readable `message` attribute is generally sent explaining what went wrong. +With the response code, the API usually also sends a human-readable `message` attribute that tells you what went wrong. :::note -If you receive an HTML response when an error occurs check your accept header. The Fount's API will attempt to respond to errors based on your request. By setting the `Accept: application/json` header you can ensure that you always get a JSON response in all instances. +If you get an HTML response when an error occurs, check your accept header. The Fount's API tries to send errors in a format that matches your request. Set the `Accept: application/json` header to always get a JSON response. ::: ## Response Codes @@ -18,15 +18,15 @@ If you receive an HTML response when an error occurs check your accept header. T |--------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `200` - OK | Everything works as expected. | | `201` - Created | The resource was created. | -| `202` - Accepted | The request was accepted, but some of the data is still being generated. Retry the request shortly. See for example [brandscape data](brand-data/brandscape-data.md#data-generation). | -| `204` - No Content | The request succeeded and there is no content to return, for example after deleting a resource. | -| `400` - Bad Request | The request could not be handled, often due to a missing required parameter, an invalid filter, sort or include, or badly formatted data. | -| `401` - Unauthorized | No valid API token provided or the API token used does not have the required [scopes](authentication.md#scopes). | +| `202` - Accepted | The request was accepted, but some of the data is not ready yet. Retry the request after a short time. See for example [brandscape data](brand-data/brandscape-data.md#data-generation). | +| `204` - No Content | The request succeeded and there is no content to return, for example after you delete a resource. | +| `400` - Bad Request | The API could not handle the request, often because of a missing required parameter, an invalid filter, sort or include, or badly formatted data. | +| `401` - Unauthorized | No valid API token was sent, or the API token does not have the required [scopes](authentication.md#scopes). | | `403` - Forbidden | The user does not have permission to perform the requested action. | -| `404` - Not Found | The requested resource doesn't exist. | +| `404` - Not Found | The requested resource does not exist. | | `422` - Unprocessable Content | The request failed validation. The response includes an `errors` object with the validation errors for each parameter. | | `429` - Too Many Requests | You have exceeded the [rate limit](rate-limiting.md). | -| `500`, `502`, `504` - Server Errors | These are rare errors when something's wrong on The Fount's end. | +| `500`, `502`, `504` - Server Errors | These are rare errors that occur when there is a problem on The Fount's side. | | `503` - Service Unavailable | The Fount, or an upstream provider that the endpoint relies on (such as the market data provider for [stock prices](company-data/stock-prices.md)), is temporarily unavailable. Retry the request later. | ## Response diff --git a/docs/health-check.md b/docs/health-check.md index b1f118f..084a944 100644 --- a/docs/health-check.md +++ b/docs/health-check.md @@ -1,8 +1,7 @@ # Health Check -For some integrations and applications it can be helpful to check if the BAV API is up and running. This can be done by -sending a GET request to the health endpoint. This endpoint is designed to return a simple response indicating the -health status of the API. +For some integrations and applications, it is helpful to check if the BAV API is available. To do this, send a GET +request to the health endpoint. This endpoint returns a short response that shows the health status of the API. ## Endpoint @@ -10,17 +9,17 @@ health status of the API. GET /api/v2/health ``` -This endpoint does not require authentication, so you don't need to send an API token. It is still subject to -the [rate limit](rate-limiting.md). +This endpoint does not require authentication, so you do not need to send an API token. The +[rate limit](rate-limiting.md) also applies to this endpoint. ## Response -The endpoint will return a 200 OK HTTP status code if the API is healthy. The response will be in JSON format and will -include a status message and a timestamp of the check. The timestamp is in UTC, in the `YYYY-MM-DD HH:MM:SS` format. +If the API is healthy, the endpoint returns a 200 OK HTTP status code. The response is in JSON format and contains a +status message and a timestamp of the check. The timestamp is in UTC, in the `YYYY-MM-DD HH:MM:SS` format. -Any status code that isn't 200 OK should be considered a failure. Because this endpoint is very lightweight its response -time should be very low. When connecting to the endpoint you may set a short timeout (e.g. 1 second) to avoid long waits -in case of an issue. +Consider all status codes other than 200 OK as a failure. This endpoint is lightweight, so we expect its response time +to be low. When you connect to the endpoint, you can set a short timeout (for example 1 second). This prevents long +waits if there is a problem. ```json { diff --git a/docs/intro.md b/docs/intro.md index 7608331..5713d9d 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -1,30 +1,29 @@ # Introduction -WPP BAV has a modern REST API available for consuming data through external systems. Most of the system's data can be -accessed and we have made it a priority to make access as simple as possible. +WPP BAV has a modern REST API that external systems can use to get data. You can access most of the data in the +system. We made it a priority to make access as simple as possible. -To use the API you need to have an access token. Please see the [authentication section](authentication.md) for more -information on how to get one. +To use the API, you need an access token. See the [authentication section](authentication.md) for information about +how to get one. :::note Building a user-facing app? Please let us know... -If you are integrating BAV data into an application, reporting tool or any other system where others will also be -consuming the data, please [let us know before](/support). It's important to the credibility of BAV that the data is -used correctly and displayed in the right context. Because BAV can be complex, we want to ensure that you have the -right support and guidance to do so. +If you integrate BAV data into an application, reporting tool or other system where other people also use the data, +[tell us before you do this](/support). It is important for the credibility of BAV that the data is used correctly and +shown in the correct context. BAV can be complex, so we want to make sure that you have the correct support and +guidance. ::: ## Structure -The API is divided into several sections, each of which has its own set of resources. Endpoints include both -those that return the research data that you might primarily think of when you think of BAV, such as -how a brand is perceived. However, it also includes endpoints that return metadata about the data, such as -the studies, years, and countries that the data is available for. This metadata is important to understand the context -of the data and to be able to filter it correctly. +The API has several sections, and each section has its own set of resources. Some endpoints return the research data +that you primarily think of when you think of BAV, for example how people perceive a brand. Other endpoints return +metadata about the data, for example the studies, years and countries that the data is available for. This metadata is +important to understand the context of the data and to filter it correctly. -The brand data itself can be accessed in two ways. Either through each specific "data model", which is a set lens of -metrics that go together and give a specific view of the brand. Such as "Pillars", "Powergrid" or "Imagery". These -endpoints are perfect for getting only a specific set of data. They also include the right phrases and descriptions -needed to chart and display the data correctly. +You can access the brand data itself in two ways. The first way is through each specific "data model". A data model is +a fixed set of metrics that together give a specific view of the brand, for example "Pillars", "Powergrid" or +"Imagery". These endpoints are ideal if you need only a specific set of data. They also include the correct phrases and +descriptions that you need to chart and show the data correctly. -Alternatively you can query our flexible "brandscape data" endpoint, which gives you access to all of the -metrics for a brand in a specific study, year, country, audience, and category. +The second way is our flexible "brandscape data" endpoint. This endpoint gives you access to all of the metrics for a +brand in a specific study, year, country, audience and category. diff --git a/docs/pagination.md b/docs/pagination.md index 5f6bbb1..29828ad 100644 --- a/docs/pagination.md +++ b/docs/pagination.md @@ -1,16 +1,16 @@ # Pagination -All top-level API resources have support for fetching data in bulk via a list method. You can, for example, list brands +All top-level API resources have a list method that you can use to get data in bulk. For example, you can list brands and collections. ## Parameters -You may use the following query parameters on list resources: +You can use these query parameters on list resources: -- `page` will let you set the currently active page. -- `per_page` will let you set how many records you want to retrieve per page. Maximum of 1000. Default is 25. A `400` - error is returned if you ask for more than 1000 records per page. +- `page` sets the current page. +- `per_page` sets the number of records on each page. The maximum is 1000. The default is 25. If you ask for more than + 1000 records on each page, you get a `400` error. URL Example: @@ -20,7 +20,7 @@ GET https://fount.wppbav.com/api/v2/brands?page=2&per_page=50 ## Response -The structure of the API list response is as follows: +The API list response has this structure: ```json { diff --git a/docs/rate-limiting.md b/docs/rate-limiting.md index f1f9b60..993d6ac 100644 --- a/docs/rate-limiting.md +++ b/docs/rate-limiting.md @@ -1,17 +1,17 @@ # Rate Limiting -The API has a rate limit of 500 requests per minute based on the user. This means that the rate limit applies to all of -your personal access tokens collectively. Requests without authentication, such as to the -[health check](health-check.md), are rate limited by IP address. +The API has a rate limit of 500 requests per minute for each user. This means that the rate limit applies to all of +your personal access tokens together. For requests without authentication, for example to the +[health check](health-check.md), the rate limit applies to each IP address. :::note -When you run several requests per second you may find that the security suite in front of the API blocks you sooner than the rate limit, especially when run on public clouds. If you face this issue, please reduce the amount of requests you are making. If the resulting amount of requests per second is too low to be viable for your use-case, please get in touch with us. +If you send several requests each second, the security suite in front of the API can block you before you reach the rate limit. This occurs especially when you run the requests on public clouds. If you have this problem, decrease the number of requests that you send. If the resulting number of requests each second is too low for your use case, contact us. ::: -Each API response will return headers informing you of the rate limit and how many requests you have left. -The `X-RateLimit-Limit` header will specify the current rate limit and `X-RateLimit-Remaining` will give you how many -requests are left in the current minute. +Each API response contains headers that tell you the rate limit and how many requests you have left. +The `X-RateLimit-Limit` header gives the current rate limit. The `X-RateLimit-Remaining` header gives the number of +requests that are left in the current minute. -If you reach the limit, a `429 - Too Many Requests` error will be returned along with two additional headers. -The `X-RateLimit-Reset` header will give you a timestamp of when the rate limit will be reset and the `Retry-After` -header will give you how many seconds are left until you may retry again. +If you reach the limit, the API returns a `429 - Too Many Requests` error with two more headers. +The `X-RateLimit-Reset` header gives a timestamp of when the rate limit resets. The `Retry-After` header gives the +number of seconds until you can retry. diff --git a/docs/versioning.md b/docs/versioning.md index 3433f85..235a5e2 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -1,27 +1,26 @@ # Versioning -When new backwards-incompatible changes are made to the API, a new version is released. These docs are always versioned -to each major version. You can switch between the versions in the header. +When we make backwards-incompatible changes to the API, we release a new version. These docs always have a version for +each major version. You can switch between the versions in the header. The current API version is: `2`. The version is part of the API URL: `/api/v2/RESOURCE`. :::caution Actively supported versions -Please note that we only actively support the current major version of the API. While we don't actively break an older -version, we suggest that you update to the latest version if you are using an older version. We try and make upgrades as -easy as possible. +We actively support only the current major version of the API. We do not actively break an older version. But if you +use an older version, we recommend that you update to the latest version. We try to make upgrades as easy as possible. ::: ## Upgrading from version 1 -Version 2 contains breaking changes from version 1 of the API. We suggest that you review all calls and responses for -any changes. +Version 2 contains breaking changes from version 1 of the API. We recommend that you examine all calls and responses +for changes. -At a high-level, these are the changes that will affect you: +These are the high-level changes that will affect you: -- There are no removed resources but several new ones. -- Some fields have been given new names, a select few have been removed. +- No resources were removed, and there are several new resources. +- Some fields have new names, and a small number of fields were removed. - Filtering now has a new, consistent format (see [filtering](customizing/filters.md)). - Sorting now has a new, simplified format (see [sorting](customizing/filters.md#sorting-results)). - Expansions are now includes (see [includes](customizing/includes.md)). diff --git a/docs/webhooks.md b/docs/webhooks.md index 75b71b4..447533d 100644 --- a/docs/webhooks.md +++ b/docs/webhooks.md @@ -3,18 +3,18 @@ import TabItem from '@theme/TabItem'; # Webhooks -Webhooks allow you to receive HTTP push notifications for data changes in BAV. This allows you to build richer -integrations on top of BAV. You could, for example, use it to react in realtime to new data being available or make -audiences seamlessly available in your own systems. +With webhooks, you can receive HTTP push notifications for data changes in BAV. You can use them to build richer +integrations on top of BAV. For example, you can react in real time when new data becomes available. You can also make +audiences available in your own systems automatically. -Our webhooks belong to the global platform. You can configure webhooks to provide events based on all users and -operating companies or specific users and/or operating companies. For example, you may only want to listen to new -audiences created by users within GroupM. Filtering on users and operating companies applies to the audience and -collection events. Other events are always sent for all changes. +Our webhooks belong to the global platform. You can configure webhooks to send events for all users and operating +companies, or for specific users and/or operating companies. For example, you can listen only to new audiences that +users in GroupM create. The filter on users and operating companies applies to the audience and collection events. BAV +always sends the other events for all changes. ## Events -When a webhook is set up, it is subscribed to one or more events. The data change events are triggered when data is +When a webhook is set up, it subscribes to one or more events. BAV triggers the data change events when data is created, updated or deleted in BAV: | Event | `type` in the payload | Description | @@ -25,7 +25,7 @@ created, updated or deleted in BAV: | `collections_data_change` | `Collection` | A [collection](brands/collections.md) was created, updated or deleted. | | `studies_data_change` | `Study` | A [study](studies/studies.md) was created, updated or deleted. | -The following events can also be added to a webhook, but are not currently being sent: +You can also add these events to a webhook, but BAV does not send them at this time: | Event | Description | |---------------------------------------|------------------------------------------------| @@ -36,64 +36,68 @@ The following events can also be added to a webhook, but are not currently being ## How does a webhook work? -A webhook is simply a HTTP POST request to a URL you specify. The request is automatically triggered by BAV when data -updates or the event occurs. The request contains a [JSON payload](#the-webhook-payload) with the data that has changed -or the event that has occurred. +A webhook is an HTTP POST request to a URL that you specify. BAV triggers the request automatically when data changes +or the event occurs. The request contains a [JSON payload](#the-webhook-payload) with the data that changed or the +event that occurred. -To receive data from the webhook all you need is a simple HTTP endpoint that: +To receive data from the webhook, you need only an HTTP endpoint that: -- Is available on a publicly accessible HTTPS, non-localhost URL with a valid SSL certificate. +- Is available on a public HTTPS URL that is not localhost and has a valid SSL certificate. - Responds with a `2xx` status code (for example `HTTP 200`) to the webhook POST request within 5 seconds. -If your endpoint does not respond with a `2xx` status code within 5 seconds, the request will be retried. Each webhook -call is attempted up to 10 times in total. We use an exponential backoff delay between retries, which means that the -delay gets longer for each retry: 10 seconds after the first attempt, then 100 seconds, 1,000 seconds (about 17 -minutes), 10,000 seconds (about 2.8 hours) and then 100,000 seconds (about 28 hours) between each of the remaining -attempts. +If your endpoint does not respond with a `2xx` status code within 5 seconds, BAV retries the request. BAV tries each +webhook call up to 10 times in total. We use an exponential backoff delay between retries. This means that the delay +increases for each retry: -If all attempts fail, the webhook will be automatically disabled and the webhook's contacts will receive an email -notification. It must then be manually re-enabled when the issue has been fixed. +1. 10 seconds after the first attempt. +2. Then 100 seconds. +3. Then 1,000 seconds (about 17 minutes). +4. Then 10,000 seconds (about 2.8 hours). +5. Then 100,000 seconds (about 28 hours) between each of the remaining attempts. + +If all attempts fail, BAV disables the webhook automatically and sends an email notification to the webhook's contacts. +After the problem is fixed, the webhook must be enabled again manually. ## Getting started -Implementing webhooks is simpler than you might think. In summary, you'll need to do the following in your application: +It is not difficult to implement webhooks. In summary, do these steps in your application: -- Create a receiving endpoint for the webhook. -- Verify the authenticity of the webhook request by validating the signature in the request. -- Parse the JSON payload in the request to get the data that has changed or the event that has occurred and process it. +- Create an endpoint that receives the webhook. +- Validate the signature in the request to verify that the webhook request is authentic. +- Parse the JSON payload in the request to get the data that changed or the event that occurred. Then process it. - Respond to the request with a `2xx` status code (for example `HTTP 200`). -As some events are triggered by BAV it can be useful to use the sample payloads provided in the documentation to use as -test data. This will allow you to test your endpoint without having to wait for the event to occur in BAV. +BAV triggers some events itself. You can use the sample payloads in the documentation as test data. Then you can test +your endpoint before the event occurs in BAV. ## Creating the webhook on The Fount -Currently, you cannot create webhooks on The Fount yourself. You will need to reach out to us -at [support@bernskiold.com](mailto:support@bernskiold.com). We will then add the webhook to the system for -you and provide you with the secret key that you will need to verify the authenticity of the webhook requests. +At this time, you cannot create webhooks on The Fount yourself. Contact us +at [support@bernskiold.com](mailto:support@bernskiold.com). We will then add the webhook to the system for you. We will +also give you the secret key that you need to verify that the webhook requests are authentic. -You are more than welcome to reach out as you start to plan your integration and we can help you get started. +You are welcome to contact us when you start to plan your integration. We can help you with the first steps. -When adding a webhook we will need the following information from you: +When we add a webhook, we need this information from you: - The URL of the endpoint that will receive the webhook. - The events that you want to receive webhooks for. This can be all events or specific events. -- If you want to only receive events for specific users and/or operating companies. +- If you want to receive events only for specific users and/or operating companies. :::tip Handle webhooks asynchronously -When you receive a webhook request, it is helpful to handle it asynchronously. This will ensure that your application -can respond to the webhook request quickly and avoid timeouts. You can use a queue to handle the webhook request and -then process it in the background. +When you receive a webhook request, we recommend that you handle it asynchronously. Then your application can respond +to the webhook request quickly and prevent timeouts. You can put the webhook request in a queue, and then process it in +the background. ::: ## The Webhook Payload -The webhook HTTP payload will include information that you'll need both in its HTTP headers and in its request body. +The webhook HTTP payload contains information that you need in its HTTP headers and in its request body. -For data change events the request body will include the data that has changed in the same format as the API endpoints -for each resource. +For data change events, the request body contains the data that changed. The format is the same as the format of the +API endpoints for each resource. -The payload will be sent with the following headers: +BAV sends the payload with these headers: ``` Accept-Charset: utf-8 @@ -104,7 +108,7 @@ BAV-Signature: d0e1c26711234ca18e4c7c879d5c41a5221db7ea5349c07073573341378aa2b4 User-Agent: BAV-Webhook ``` -The custom headers sent by BAV are: +The custom headers that BAV sends are: | Name | Description | |-----------------|----------------------------------------------------| @@ -112,11 +116,11 @@ The custom headers sent by BAV are: | `BAV-Event` | The resource type that triggered this event. This is the same as the `type` field in the body. | | `BAV-Signature` | The HMAC signature of the webhook payload. | -The payload is sent with the following body: +BAV sends the payload with this body: | Field | Description | |--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| `action` | The type of action that took place. For data change events, one of: `created`, `updated`, `deleted`. | +| `action` | The type of action that occurred. For data change events, one of: `created`, `updated`, `deleted`. | | `data` | The data for the object in the same format as the object's full response schema. You can find this in the documentation for each endpoint. | | `type` | The type of resource that was targeted, for example `Brand`. See [events](#events). | | `url` | The URL to the object's page on The Fount, when it has one. Otherwise `null`. | @@ -144,23 +148,23 @@ For example: ## Security and validation -When implementing webhooks it is important to secure your endpoint to ensure that the data you receive is from BAV. We -use a HMAC signature to sign the payload with a secret key. This signature is included in the `BAV-Signature` header of -the request. You should use this signature to verify that the payload was sent by BAV. +When you implement webhooks, it is important to secure your endpoint. Make sure that the data that you receive is from +BAV. We use an HMAC signature to sign the payload with a secret key. This signature is in the `BAV-Signature` header of +the request. Use this signature to verify that BAV sent the payload. -The payload body also includes `webhookTimestamp` and `webhookDate` fields. We recommend that you use them to verify -that they are within a reasonable time frame (≈ a minute). This will help to prevent replay attacks. +The payload body also contains the `webhookTimestamp` and `webhookDate` fields. We recommend that you use them to +verify that their values are within a reasonable time frame (≈ a minute). This helps to prevent replay attacks. -To verify the webhook, calculate the signature from the request body using the webhook secret that we provide you with. -Then compare the calculated signature with the signature in the `BAV-Signature` header. We recommend using the raw -request body content for the hashing as JSON parsing may change it. +To verify the webhook, calculate the signature from the request body with the webhook secret that we give you. Then +compare the calculated signature with the signature in the `BAV-Signature` header. We recommend that you use the raw +request body content for the hash, because JSON parsing can change it. :::warning Securing the webhook secret -We strongly remind you to keep the webhook secret secure. Do not expose it in your frontend code or in any public or -private repositories. Do not hardcode it into your code. It should be considered as sensitive as a password. +Always keep the webhook secret secure. Do not expose it in your frontend code or in public or private repositories. Do +not hardcode it into your code. The secret is as sensitive as a password. -If you accidentally expose the secret, or commit it to version control, please contact us immediately so that we can -reset it for you. +If you accidentally expose the secret, or commit it to version control, contact us immediately. We will then reset it +for you. ::: @@ -216,5 +220,5 @@ if (signature != request$headers$`BAV-Signature`) { -In addition to verifying the signature we recommend that you also verify the `webhookTimestamp` and `webhookDate` fields -to within approximately a minute of the current time. This will help to prevent replay attacks. \ No newline at end of file +We recommend that you also verify the `webhookTimestamp` and `webhookDate` fields, not only the signature. Make sure +that their values are within about one minute of the current time. This helps to prevent replay attacks. \ No newline at end of file From 2ad34bdbe33531e419020cfccb27aaab81f71ae7 Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sun, 25 Oct 2026 10:33:34 +0100 Subject: [PATCH 15/23] Rewrite brand data and tools docs in Simplified Technical English Co-Authored-By: Claude Opus 5.5 --- docs/brand-data/agency-change-predictor.md | 48 +++++----- docs/brand-data/archetypes.md | 23 ++--- docs/brand-data/brand-personality-match.md | 8 +- docs/brand-data/brand-vulnerability-map.md | 4 +- docs/brand-data/brand-worth-map.md | 4 +- docs/brand-data/brand-worth.md | 6 +- docs/brand-data/brandscape-data.md | 98 ++++++++++----------- docs/brand-data/category-worth-map.md | 5 +- docs/brand-data/cee-opinions.md | 40 ++++----- docs/brand-data/commitment-funnel.md | 27 +++--- docs/brand-data/cost-of-entry.md | 4 +- docs/brand-data/data-models.md | 61 +++++++------ docs/brand-data/imagery.md | 4 +- docs/brand-data/index.md | 10 +-- docs/brand-data/influence.md | 4 +- docs/brand-data/partnership-exchange-map.md | 6 +- docs/brand-data/personality.md | 6 +- docs/brand-data/pillars.md | 12 +-- docs/brand-data/powergrid.md | 29 +++--- docs/brand-data/preferences.md | 12 +-- docs/brand-data/recommendation.md | 8 +- docs/brand-data/super-cx-tool.md | 10 +-- docs/brand-data/super-cx.md | 10 +-- docs/brand-data/swot.md | 4 +- docs/brand-data/tools.md | 30 ++++--- docs/brand-data/usage.md | 10 +-- 26 files changed, 245 insertions(+), 238 deletions(-) diff --git a/docs/brand-data/agency-change-predictor.md b/docs/brand-data/agency-change-predictor.md index 22b3c77..dcf5d58 100644 --- a/docs/brand-data/agency-change-predictor.md +++ b/docs/brand-data/agency-change-predictor.md @@ -1,7 +1,7 @@ # Agency Change Predictor -The Agency Change Predictor (ACP) analyzes brand vulnerability using ten weighted checks to determine the likelihood of -an agency change. It combines brand equity metrics with category comparisons to provide a vulnerability assessment for +The Agency Change Predictor (ACP) analyzes brand vulnerability. It uses ten weighted checks to determine the likelihood +of an agency change. It combines brand equity metrics with category comparisons to give a vulnerability assessment for each brand. ## Creating a query @@ -18,9 +18,9 @@ The Fount. ## Parameters -The ACP takes the same filters as the [data models](data-models.md#parameters), apart from `benchmarks` and `format`. -The filters can be passed as arrays (`brands[]=148&brands[]=149`) or, for backwards compatibility, as comma-separated -lists (`brands=148,149`). +The ACP takes the same filters as the [data models](data-models.md#parameters), except `benchmarks` and `format`. +You can pass the filters as arrays (`brands[]=148&brands[]=149`). For backwards compatibility, you can also pass them as +comma-separated lists (`brands=148,149`). | Key | Required? | Type | Description | |---------------|:------------------------------:|---------|---------------------------------------------------------------------------------------------------------------------| @@ -29,8 +29,8 @@ lists (`brands=148,149`). | `countries` | At least one* | array | [Country](../metadata/countries.md) IDs, codes or names. | | `years` | At least one* | array | [Year](../metadata/years.md) IDs or year numbers. | | `audiences` | :x: (defaults to All Adults) | array | [Audience](../audiences/audiences.md) IDs or names. | -| `study_types` | :x: (defaults to `syndicated`) | array | The kinds of study that a `countries` and `years` filter may resolve to. See [data models](data-models.md#parameters). | -| `category` | :x: | integer | Only include brands in this [category](../studies/categories.md) ID. | +| `study_types` | :x: (defaults to `syndicated`) | array | The kinds of study that a `countries` and `years` filter can resolve to. See [data models](data-models.md#parameters). | +| `category` | :x: | integer | Include only brands in this [category](../studies/categories.md) ID. | | `search` | :x: | string | Search brands by name. | | `customWeights` | :x: | object | Custom weights for the checks, keyed by check name. See [custom weights](#custom-weights). | | `mustPass` | :x: | array | Checks the brand must pass, i.e. problems it must not have. Max 10. | @@ -41,7 +41,7 @@ lists (`brands=148,149`). ## The checks Each check names a problem, so a brand passes a check when it does not have that problem. Each check has a default -weight that is used in the standard vulnerability score. +weight that the standard vulnerability score uses. | Check | Weight | Name | Description | |---------------------------------------------|:------:|-------------------------------------|-----------------------------------------------------------------------------------------------------| @@ -57,23 +57,25 @@ weight that is used in the standard vulnerability score. | `has_lower_preference_than_category` | 1 | Lower Preference | Preference below the category average. | The popularity rank is the "gaining in popularity" rank on the classic BAV methodology and the "trendy" rank on the -2025 methodology. It is returned as `raw_metrics.popularity_rank`. +2025 methodology. The response gives it as `raw_metrics.popularity_rank`. :::note Spelling The check `has_lower_differentation_than_category` contains a legacy typo ("differentation" instead of -"differentiation"). It is kept for backwards compatibility. +"differentiation"). The API keeps this name for backwards compatibility. ::: -The category comparisons average every brand that the study measured in the category, regardless of which brands you -asked for. They are worked out per study, so a brand is always compared with its own market. +The category comparisons use the average of every brand that the study measured in the category. The brands that you +asked for do not change this average. The API calculates the comparisons per study, so it always compares a brand with +its own market. -A check is `null` when a metric it needs is missing for the brand, for example when usage was not asked. A `null` -check counts as passed in the score, and neither `mustPass` nor `mustNotPass` on that check matches the brand. +A check is `null` when a metric that it needs is missing for the brand. For example, this occurs if the survey did not +ask about usage. In the score, a `null` check counts as passed. Also, neither `mustPass` nor `mustNotPass` on that check +matches the brand. ### Filtering on checks Use `mustPass` and `mustNotPass` to filter the brands by their check results. A check cannot be in both lists. For -example, to get brands that are not vulnerable and not churning, but are poorly differentiated: +example, to get brands that are not vulnerable and do not have high churn, but have low differentiation: ```http request GET /api/v2/tools/agency-change-predictor?studies[]=635&mustPass[]=is_vulnerable&mustPass[]=has_high_churn&mustNotPass[]=low_differentiation @@ -82,7 +84,7 @@ GET /api/v2/tools/agency-change-predictor?studies[]=635&mustPass[]=is_vulnerable ### Custom weights Use `customWeights` to calculate a second vulnerability score with your own weights. Each weight is an integer from 0 -to 10, keyed by check name. A weight of `0` drops the check from the score. A check that you leave out keeps its default +to 10, keyed by check name. A weight of `0` removes the check from the score. A check that you leave out keeps its default weight. At least one weight must be greater than 0. ```http request @@ -91,15 +93,15 @@ GET /api/v2/tools/agency-change-predictor?studies[]=635&customWeights[is_vulnera ## Response -The response contains a `meta` object and a `data` array. Every brand matching the filters is returned, including -brands that pass every check and so score zero. +The response contains a `meta` object and a `data` array. The response contains every brand that matches +the filters. This includes brands that pass every check and thus have a score of zero. ### Meta | Key | Type | Description | |------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------| -| `source` | string | A source label naming the studies and audiences, suitable for captioning. | -| `studies_used` | array | The studies the data came from. This is useful when you filter by `countries`, since the studies are then chosen for you. Each study includes its `study_id`, `name`, `country`, `year` and `type`, along with other details where available. | +| `source` | string | A source label that names the studies and audiences. You can use it as a caption. | +| `studies_used` | array | The studies that the data came from. This is useful if you filter by `countries`, because the API then selects the studies for you. Each study includes its `study_id`, `name`, `country`, `year` and `type`, and other details where available. | | `is_category_specific` | boolean | Whether the data is category specific. | ### Data @@ -120,8 +122,8 @@ The `data` object contains: | Key | Type | Description | |--------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `vulnerability_score_standard` | float | The vulnerability score (0-100) using the default weights. | -| `vulnerability_score_custom` | float | The vulnerability score (0-100) using your `customWeights`. | -| `checks` | object | The result of each of the ten [checks](#the-checks), keyed by check name. `true` when the brand has the problem, `false` when it does not, and `null` when the check could not be evaluated. | +| `vulnerability_score_standard` | float | The vulnerability score (0-100) that uses the default weights. | +| `vulnerability_score_custom` | float | The vulnerability score (0-100) that uses your `customWeights`. | +| `checks` | object | The result of each of the ten [checks](#the-checks), keyed by check name. `true` when the brand has the problem, `false` when it does not, and `null` when the API cannot evaluate the check. | | `category_comparisons` | object | The category averages used by the comparison checks: `differentiation_average`, `gaining_in_popularity_average`, `one_i_prefer_average`, `recommendation_average` and `churn_ratio`. | | `raw_metrics` | object | The metric values used in the checks: `differentiation_rank`, `relevance_rank`, `esteem_rank`, `knowledge_rank`, `brand_strength_rank`, `brand_stature_rank`, `gaining_in_popularity_rank`, `popularity_rank`, `total_users_pct`, `lapsed_user_pct`, `churn_ratio`, `recommend_to_a_friend_pct` and `one_i_prefer_pct`. | diff --git a/docs/brand-data/archetypes.md b/docs/brand-data/archetypes.md index 1dec34b..932d552 100644 --- a/docs/brand-data/archetypes.md +++ b/docs/brand-data/archetypes.md @@ -1,16 +1,16 @@ # Archetypes Archetypes show how strongly a brand is associated with each of the twelve BAV brand archetypes, such as Inventor, -Expert and Rebel, as a percentile rank and a construct score. +Expert and Rebel. Each archetype has a percentile rank and a construct score. -Archetypes data are split across two types: +There are two types of archetypes data: - Cultural archetypes - Competitive archetypes -A cultural archetype is the score of each archetype "in culture", meaning against all the other brands in a study ( +A cultural archetype is the score of each archetype "in culture", that is, against all the other brands in a study ( market + year). A competitive archetype is the score of each archetype against a specific set of brands (the competitive -set). A competitive set can be defined either by a collection or a category. +set). A collection or a category can define a competitive set. ## Creating a query @@ -20,20 +20,21 @@ GET /api/v2/tools/archetypes ## Parameters -When you query the Archetypes endpoint the parameters are split between filtering parameters and comparison parameters. -The filter parameters filter down the data, while the comparison parameters are used to create competitive archetypes. +The Archetypes endpoint has two kinds of parameters: filter parameters and comparison parameters. The filter parameters +filter the data. The comparison parameters create competitive archetypes. | Key | Required? | Type | Description | |---------------|:----------------------------:|---------|---------------------------------------------------------------------------------------------------| | `brands` | :x: | integer | Filter parameter. A single Brand ID. | | `studies` | :white_check_mark: | integer | Filter parameter. A single Study ID. | | `audiences` | :x: (defaults to All Adults) | integer | Filter parameter. A single Audience ID. | -| `categories` | :x: | integer | Comparison parameter. A single Category ID to compare against. Can be combined with `collections`. | -| `collections` | :x: | integer | Comparison parameter. A single Collection ID to compare against. Can be combined with `categories`. | +| `categories` | :x: | integer | Comparison parameter. A single Category ID to compare against. You can combine it with `collections`. | +| `collections` | :x: | integer | Comparison parameter. A single Collection ID to compare against. You can combine it with `categories`. | ## Response The response contains a `data` array with one entry per brand. Each entry has `brand` (with `id`, `name` and -`local_name`), `brand_variation`, `sector`, `category`, `study`, `country`, `year` and `audience` objects, and a `data` -object keyed by archetype (`inventor`, `expert`, `leader`, `innocent`, `enticer`, `fashion_forward`, `adventurer`, -`rebel`, `entertainer`, `companion`, `nurturer` and `trusted_friend`), each with a `rank` and a `construct`. +`local_name`), `brand_variation`, `sector`, `category`, `study`, `country`, `year` and `audience` objects. Each entry also has a +`data` object keyed by archetype (`inventor`, `expert`, `leader`, `innocent`, `enticer`, `fashion_forward`, +`adventurer`, `rebel`, `entertainer`, `companion`, `nurturer` and `trusted_friend`). Each archetype has a `rank` and a +`construct`. diff --git a/docs/brand-data/brand-personality-match.md b/docs/brand-data/brand-personality-match.md index 0cc8973..4d139ee 100644 --- a/docs/brand-data/brand-personality-match.md +++ b/docs/brand-data/brand-personality-match.md @@ -2,7 +2,7 @@ The Brand Personality Match returns the brands in the same study whose imagery profile most closely matches the brand you name, ranked by similarity. Similarity is the correlation of the brands' imagery attribute ranks, so matches can -come from any category. Only brands with a knowledge percentile rank of 50 or above are considered. +come from any category. The tool considers only brands with a knowledge percentile rank of 50 or above. ## Creating a query @@ -20,6 +20,6 @@ GET /api/v2/tools/brand-personality-match ## Response -The response contains a `data` array of matching brands. Each entry has `brand`, `sector`, `category`, `study`, -`country`, `year` and `audience` objects (each with `id` and `name`), plus `correlation` and `varianceExplained`, each -with a `raw` value and a `formatted` percentage string. +The response contains a `data` array of the brands that match. Each entry has `brand`, `sector`, `category`, `study`, +`country`, `year` and `audience` objects (each with `id` and `name`). Each entry also has `correlation` and +`varianceExplained`, each with a `raw` value and a `formatted` percentage string. diff --git a/docs/brand-data/brand-vulnerability-map.md b/docs/brand-data/brand-vulnerability-map.md index 6973f22..f08fcfe 100644 --- a/docs/brand-data/brand-vulnerability-map.md +++ b/docs/brand-data/brand-vulnerability-map.md @@ -1,7 +1,7 @@ # Brand Vulnerability Map -The Brand Vulnerability Map shows how vulnerable a brand is, based on its brand equity metrics. This is the -vulnerability assessment the Agency Change Predictor uses, returned on its own. +The Brand Vulnerability Map shows how vulnerable a brand is, based on its brand equity metrics. It returns the +vulnerability assessment that the Agency Change Predictor uses, on its own. ## Creating a query diff --git a/docs/brand-data/brand-worth-map.md b/docs/brand-data/brand-worth-map.md index e2c8536..87e3f68 100644 --- a/docs/brand-data/brand-worth-map.md +++ b/docs/brand-data/brand-worth-map.md @@ -1,7 +1,7 @@ # Brand Worth Map -The Brand Worth Map places brands on two axes, "Worth paying more for" and "Providing good value", and classifies them -into four quadrants split at a percentile rank of 50: Brand Worth (high on both), Desire (high worth, low value), Value +The Brand Worth Map places brands on two axes, "Worth paying more for" and "Providing good value". It classifies the +brands into four quadrants, split at a percentile rank of 50: Brand Worth (high on both), Desire (high worth, low value), Value Champion (high value, low worth) and Emotional Choice (low on both). ## Creating a query diff --git a/docs/brand-data/brand-worth.md b/docs/brand-data/brand-worth.md index 76c4bf2..11256ce 100644 --- a/docs/brand-data/brand-worth.md +++ b/docs/brand-data/brand-worth.md @@ -30,7 +30,7 @@ The response follows the [standard data model schema](data-models.md#schema). ### Metrics -The data points include the `good_value` and `worth_more` metrics with their `rank` scores. Brands that are studied in -more than one category are only included once. +The data points include the `good_value` and `worth_more` metrics with their `rank` scores. If a study examines a brand in more +than one category, the model includes the brand only once. -The quadrant is not returned as a `classification` on this endpoint. Use the rules above to place the brands. +This endpoint does not return the quadrant as a `classification`. Use the rules above to place the brands. diff --git a/docs/brand-data/brandscape-data.md b/docs/brand-data/brandscape-data.md index eea7b2d..46e5384 100644 --- a/docs/brand-data/brandscape-data.md +++ b/docs/brand-data/brandscape-data.md @@ -2,9 +2,9 @@ ## What is brandscape data? -A fundamental core concept of BAV is the "Brandscape" which is the set of brands in a given country for a given year. -The brandscape data is the collection of metrics and their respective values for the brandscape. You can, in practical -terms, see the brandscape data is the "BAV data". +A fundamental core concept of BAV is the "Brandscape". The brandscape is the set of brands in a given country for a +given year. The brandscape data is the collection of metrics and their respective values for the brandscape. In +practical terms, the brandscape data is the "BAV data". Brandscape data has one row per brand, category, study and audience, with every metric BAV calculates for that combination. You can get the data by: @@ -26,26 +26,26 @@ To list the brandscape data, use the list endpoint: GET /api/v2/brandscape-data ``` -The response is [paginated](../pagination.md). There is no endpoint for retrieving a single brandscape data row. +The response is [paginated](../pagination.md). There is no endpoint that gets a single brandscape data row. ### Scoping the request -Each request is scoped to one or more studies. You can do this in one of two ways: +Scope each request to one or more studies. You can do this in one of two ways: - **By study:** Use the `studies` filter with one or more study IDs. - **By market and year:** Use a country filter (`countries` or `country_code`) together with a year filter (`years` or `year_number`). -A `400` error is returned if you filter by a country without a year, or by a year without a country. +If you filter by a country without a year, or by a year without a country, the API returns a `400` error. -If you don't give a study, country or year filter at all, the request falls back to the most recently released -syndicated BAV study from the last three years. We recommend that you always scope your requests explicitly. +If you do not give a study, country or year filter, the request uses the most recently released syndicated BAV +study from the last three years. We recommend that you always scope your requests explicitly. -When no `audiences` filter is given, the data is returned for the All Adults audience (ID `1`). +If you do not give an `audiences` filter, the API returns the data for the All Adults audience (ID `1`). ### Study types -When you filter by market and year, the request only resolves to syndicated BAV studies by default. To include other +By default, if you filter by market and year, the request resolves only to syndicated BAV studies. To include other types of studies, set the `study_types` filter to a comma-separated list of the study types you want. The available study types are: @@ -54,11 +54,11 @@ study types are: - `fused` - Fused studies. - `custom` - Custom studies. -Unknown values are ignored. The `study_types` filter has no effect when you use the `studies` filter. +The API ignores unknown values. The `study_types` filter has no effect when you use the `studies` filter. -If studies of other types exist for the markets and years you requested but were left out by the study type filter, -they are listed in `meta.available_alternatives`. Each entry tells you about the study, and which `study_types` value -includes it: +Studies of other types can exist for the markets and years that you requested. If the study type filter excludes these +studies, `meta.available_alternatives` lists them. Each entry gives information about the study and the `study_types` +value that includes it: ```json { @@ -80,14 +80,14 @@ includes it: } ``` -Data from BAV AURA studies is never returned by this endpoint. +This endpoint never returns data from BAV AURA studies. ### Data generation -Brandscape data is generated per study and audience the first time it is requested. If any of the requested study and -audience combinations are still being generated, the response has a `202 Accepted` status code. The rows that are -already available are still returned, and `meta.generation` lists the combinations that are pending. Retry the request -shortly to get the full data. +The system generates brandscape data per study and audience the first time that you request it. If the generation of +one or more of the requested study and audience combinations is not complete, the response has a `202 Accepted` status +code. The response still contains the rows that are already available, and `meta.generation` lists the combinations +that are pending. To get the full data, retry the request after a short time. ```json { @@ -119,85 +119,85 @@ The `status` is `partial` when some of the requested data is already available, ### Full response schema -The brandscape data schema is large (≈ 350 fields). For that reason we omit the full schema here. It is divided into: +The brandscape data schema is large (≈ 350 fields). For that reason, this page does not show the full schema. The schema has two parts: - Metadata (for example: study, category, brand, audience information) - Metric data -The metric data field names are built up by the `key` of the [Brand Metrics](../metrics/metrics.md) resource and a -suffix depending on the score type. Not all metrics have all score types. The metric resource will show the available -score types, and its `brandscape_data_columns` field lists the exact field names. Suffixes are: +Each metric data field name is the `key` of the [Brand Metrics](../metrics/metrics.md) resource and a suffix for the +score type. Not all metrics have all score types. The metric resource shows the available score types, and its +`brandscape_data_columns` field lists the exact field names. The suffixes are: - `_rank` for percentile rank scores. - `_pct` for percentage scores. - `_c` for construct scores. - `_brandscape_index` for index scores against the entire brandscape. - `_category_index` for index scores against the brand's category. -- No suffix for value scores, like base sizes. +- No suffix for value scores, such as base sizes. -Every metric you have access to is returned by default. Use the `metric_keys` or `metric_group_keys` parameters (see -below) to limit the metrics returned. +By default, the response contains every metric that you have access to. To limit the metrics in the response, use the +`metric_keys` or `metric_group_keys` parameters (see below). -In addition to the metric data, each row has the following fields: +Each row also has the following fields, together with the metric data: | Key | Type | Description | |----------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | integer | The system ID of the brandscape data row. | -| `study_type` | string | The type of study the row came from: `syndicated`, `snap`, `fused` or `custom`, or `null` for other study types. Returned by default, and when the `study` relationship is included. | -| `is_duplicate` | boolean | `true` for a brand's second and later categories in the same study. All scores but the usage, preference and recommendation scores are category-agnostic, which means that if you perform aggregate analysis (average, standard deviation etc.) on these scores you want to remove duplicates first. | -| `brand_name` | string | The local brand name that was asked in the survey. This can be different from the global brand name from the brand relationship. You should use this field in combination with the data when available as the brand name. | +| `study_type` | string | The type of study that the row came from: `syndicated`, `snap`, `fused` or `custom`, or `null` for other study types. The API returns it by default, and when you include the `study` relationship. | +| `is_duplicate` | boolean | `true` for a brand's second and later categories in the same study. All scores except the usage, preference and recommendation scores are category-agnostic. Thus, before you do an aggregate analysis (average, standard deviation etc.) on these scores, remove the duplicates. | +| `brand_name` | string | The local brand name that the survey asked about. This can be different from the global brand name in the brand relationship. When this field is available, use it as the brand name together with the data. | | `created_at` | string | A datetime string when this row was first created. | | `updated_at` | string | A datetime string when this row was last updated. | -All metric fields are sortable, filterable and configurable. In addition, you may sort by `id`, `brand_name`, +All metric fields are sortable, filterable and configurable. You can also sort by `id`, `brand_name`, `study_id`, `category_id`, `year_id`, `country_id`, `base_id`, `brand_variation_id`, `is_duplicate`, `created_at` and `updated_at`. -For rollup studies (studies made up of several other studies), metrics with a per-study breakdown also return a +For rollup studies (studies that contain several other studies), metrics with a per-study breakdown also return a `{metric}_rollup` field. This is an object with the value for each underlying study, keyed by study ID, or `null` when the row has no breakdown. ## Additional Filters -In addition to the standard filters and the metric fields, we have a set of helper filters to make querying the data -easier by reducing the need for lookups in our database. These are: +Together with the standard filters and the metric fields, you can use a set of helper filters. These filters make it +easier to query the data, because you need fewer lookups in our database. The helper filters are: - `studies` - A comma-separated list of study IDs (for example: 1,2,3). - `countries` - A comma-separated list of country IDs (for example: 1,2,3). Requires a year filter. -- `country_code` - A comma-separated list of ISO two letter country codes (for example: GB). Can be used instead of +- `country_code` - A comma-separated list of ISO two letter country codes (for example: GB). You can use it instead of the `countries` filter. Requires a year filter. - `years` - A comma-separated list of year IDs (for example: 1,2,3). Requires a country filter. -- `year_number` - A comma-separated list of years by their numbers (for example: 2022). Can be used instead of the - `years` filter. Requires a country filter. -- `study_types` - A comma-separated list of study types that a country and year filter may resolve to (see +- `year_number` - A comma-separated list of years by their numbers (for example: 2022). You can use it instead of + the `years` filter. Requires a country filter. +- `study_types` - A comma-separated list of study types that a country and year filter can resolve to (see [study types](#study-types)). - `audiences` - A comma-separated list of audience IDs (for example: 1,2,3). Defaults to All Adults (`1`). - `brands` - A comma-separated list of brand IDs (for example: 1,2,3). - `brand_variations` - A comma-separated list of brand variation IDs (for example: 1,2,3). -- `brand_name` - A search on the brand name, using the search index. +- `brand_name` - A search on the brand name. It uses the search index. - `categories` - A comma-separated list of category IDs (for example: 1,2,3). - `companies` - A comma-separated list of company IDs (for example: 1,2,3). - `sectors` - A comma-separated list of sector IDs (for example: 1,2,3). -Filters must be given per key, for example `filter[country_code]=GB`. A `400` error is returned if `filter` is given as -a single value. +Give each filter as a separate key, for example `filter[country_code]=GB`. If you give `filter` as a single value, the +API returns a `400` error. ## Additional Column Customizations -In addition to the standard column customizations we have two helper parameters. These are used as top-level query +Together with the standard column customizations, you can use two helper parameters. Use them as top-level query parameters. -- `metric_keys` - A comma-separated list of metric keys (for example: `differentiation,relevance`) which can be used to - automatically get all the available score types for these metrics only without having to get each field specifically. +- `metric_keys` - A comma-separated list of metric keys (for example: `differentiation,relevance`). Use it to + automatically get all the available score types for only these metrics. You do not need to ask for each field. - `metric_group_keys` - A comma-separated list of [metric group](../metrics/metric-groups.md) keys (for - example: `pillars`) which can be used to automatically get all the available score types for the metrics in these - groups, without having to set each metric specifically. + example: `pillars`). Use it to automatically get all the available score types for the metrics in these groups. You + do not need to set each metric. ## Relationships & includes -When you don't use the `include` parameter, each row includes the `study`, `audience` (returned as `base`), `category`, -`brand` and `brand_variation` relationships by default. When you use the `include` parameter, only the relationships -you ask for are returned. See the [includes section](../customizing/includes) for more information on how this works. +If you do not use the `include` parameter, each row includes the `study`, `audience` (returned as `base`), `category`, +`brand` and `brand_variation` relationships by default. If you use the `include` parameter, the API returns only the +relationships that you ask for. For more information, see the [includes section](../customizing/includes). The following relationships are available: - `study` - The [study](../studies/studies.md) for the brandscape data row. diff --git a/docs/brand-data/category-worth-map.md b/docs/brand-data/category-worth-map.md index 1e95231..4936992 100644 --- a/docs/brand-data/category-worth-map.md +++ b/docs/brand-data/category-worth-map.md @@ -1,7 +1,8 @@ # Category Worth Map -The Category Worth Map is the [Brand Worth Map](brand-worth-map.md) for categories rather than brands. Each category is -placed on the "Worth paying more for" and "Providing good value" axes using the average percentile rank of its brands. +The Category Worth Map is the [Brand Worth Map](brand-worth-map.md) for categories rather than brands. The map places +each category on the "Worth paying more for" and "Providing good value" axes. It uses the average percentile rank of the +brands in the category. ## Creating a query diff --git a/docs/brand-data/cee-opinions.md b/docs/brand-data/cee-opinions.md index 57adb60..3d758c6 100644 --- a/docs/brand-data/cee-opinions.md +++ b/docs/brand-data/cee-opinions.md @@ -2,12 +2,12 @@ ## What are Consumer Equality Equation opinions? -The Consumer Equality Equation study is a study on minority ethnic groups in the UK. This endpoint lets you access the -aggregated responses by ethnic group on a number of questions around opinions. +The Consumer Equality Equation study is a study on minority ethnic groups in the UK. This endpoint gives you access to the +aggregated responses by ethnic group to several questions about opinions. ## List all opinions -To list all of the opinions and browse them via the API, use the list endpoint: +To list all of the opinions and browse them through the API, use the list endpoint: ```http request GET /api/v2/cee-opinions @@ -15,7 +15,7 @@ GET /api/v2/cee-opinions ## Get an opinion -You may also directly retrieve an opinion's details if you already have its system ID. +If you already have the system ID of an opinion, you can also get its details directly. ```http request GET /api/v2/cee-opinions/123 @@ -23,35 +23,35 @@ GET /api/v2/cee-opinions/123 Where `123` is the system ID of the cee opinion. -The opinion records are only returned for studies you have access to. The endpoints are read-only and require a token +The API returns opinion records only for studies that you have access to. The endpoints are read-only and require a token with the `bav:brand-data` scope. ## Schema ### Full response schema -Because the schema is large we omit it here. Each record is one study, market, year and audience. It consists of the -`id`, `created_at` and `updated_at` columns plus one column per opinion. The values are in percent. +The schema is large, so this page does not show it. Each record is one study, market, year and audience. It contains +the `id`, `created_at` and `updated_at` columns and one column for each opinion. The values are in percent. -Every opinion column can be filtered on, sorted by and selected with [fields](../customizing/fields.md), as can `id` -(exact filter), `created_at` and `updated_at`. +You can filter on, sort by and select every opinion column. To select columns, use [fields](../customizing/fields.md). +You can do the same with `id` (exact filter), `created_at` and `updated_at`. ## Additional Filters -For convenience, we have a set of additional filters for opinions that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +For convenience, there are also some additional filters for opinions. These filters are not in +the [default filters](../customizing/filters.md) and are not part of the columns. They are: -- `years` - A comma-separated list of year IDs. This will filter the opinions to only those for the given years. -- `year_number` - A comma-separated list of year numbers. This will filter the opinions to only those for the given +- `years` - A comma-separated list of year IDs. This filters the opinions to only those for the given years. +- `year_number` - A comma-separated list of year numbers. This filters the opinions to only those for the given years. -- `studies` - A comma-separated list of study IDs. This will filter the opinions to only those for the given studies. -- `audiences` - A comma-separated list of audience IDs. This will filter the opinions to only those in the given +- `studies` - A comma-separated list of study IDs. This filters the opinions to only those for the given studies. +- `audiences` - A comma-separated list of audience IDs. This filters the opinions to only those in the given audiences. -- `countries` - A comma-separated list of country IDs. This will filter the opinions to only those for the given +- `countries` - A comma-separated list of country IDs. This filters the opinions to only those for the given countries. -- `country_code` - A comma-separated list of two-letter ISO country codes. This will filter the opinions to only those +- `country_code` - A comma-separated list of two-letter ISO country codes. This filters the opinions to only those for the given countries. -- `updated_since` - A date. Only include records updated on or after this date. +- `updated_since` - A date. Include only records updated on or after this date. :::note @@ -62,8 +62,8 @@ Unlike most other endpoints, the year number and country code filters on this en ## Relationships & includes -By default, relationships are not included. See the [includes section](../customizing/includes) for more information -on how this works. The following relationships are available: +By default, the API does not include relationships. For more information, see the +[includes section](../customizing/includes). The following relationships are available: - `study` - The [study](../studies/studies.md) the opinions were measured in. - `country` - The [country](../metadata/countries.md) the opinions were measured in. diff --git a/docs/brand-data/commitment-funnel.md b/docs/brand-data/commitment-funnel.md index f59686c..850e100 100644 --- a/docs/brand-data/commitment-funnel.md +++ b/docs/brand-data/commitment-funnel.md @@ -1,7 +1,7 @@ # Commitment Funnel -The Commitment Funnel shows the strength of a brand's behavioral and emotional relationship with consumers, across -seven stages: Loyalty, Adoption and Consideration (behavioral), Awareness, and Respect, Love and Advocate (emotional). +The Commitment Funnel shows the strength of the behavioral and emotional relationship between a brand and consumers. +It has seven stages: Loyalty, Adoption and Consideration (behavioral), Awareness, and Respect, Love and Advocate (emotional). ## Creating a query @@ -9,8 +9,8 @@ seven stages: Loyalty, Adoption and Consideration (behavioral), Awareness, and R GET /api/v2/tools/commitment-funnel ``` -This endpoint takes the same filters as the [brandscape data models](brandscape-data.md). Array parameters are passed -using array syntax, for example: +This endpoint takes the same filters as the [brandscape data models](brandscape-data.md). Pass array parameters with +array syntax, for example: ```http request GET /api/v2/tools/commitment-funnel?brands[]=148&brands[]=149&studies[]=635 @@ -18,27 +18,28 @@ GET /api/v2/tools/commitment-funnel?brands[]=148&brands[]=149&studies[]=635 ## Parameters -At least one of `brands`, `studies`, `countries` or `years` must be provided. `studies` is not required: you can -instead use `countries` and `years` to select studies by market and year. +You must give at least one of `brands`, `studies`, `countries` or `years`. The `studies` parameter is not required. +You can use `countries` and `years` instead to select studies by market and year. | Key | Required? | Type | Description | |-----------------|:----------------------------:|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `brands` | One of the four filters | array | Up to 50 brands, as brand IDs or brand names. Names are matched to the closest brand. | -| `studies` | One of the four filters | array | Up to 50 studies, as study IDs or study names. Names are matched to the closest study you have access to. | +| `brands` | One of the four filters | array | Up to 50 brands, as brand IDs or brand names. The API matches names to the closest brand. | +| `studies` | One of the four filters | array | Up to 50 studies, as study IDs or study names. The API matches names to the closest study that you have access to. | | `countries` | One of the four filters | array | Up to 50 countries, as country IDs, ISO 3166-1 alpha-2 or alpha-3 codes, or country names. | | `years` | One of the four filters | array | Up to 50 years, as year IDs or calendar years. | | `audiences` | :x: (defaults to All Adults) | array | Up to 50 audiences, as audience IDs or audience names. | -| `study_types[]` | :x: (defaults to `syndicated`) | string array | The kinds of study that `countries` and `years` may resolve to: `syndicated` (the standard BAV study), `snap`, `fused` or `custom`. Ignored when `studies` is set. | +| `study_types[]` | :x: (defaults to `syndicated`) | string array | The kinds of study that `countries` and `years` can resolve to: `syndicated` (the standard BAV study), `snap`, `fused` or `custom`. The API ignores this parameter when `studies` is set. | :::note -The `benchmarks` and `format` parameters accepted by the [brandscape data models](brandscape-data.md) pass validation -on this endpoint but are not applied: the Commitment Funnel always responds with JSON and does not add benchmark rows. +The [brandscape data models](brandscape-data.md) accept the `benchmarks` and `format` parameters. These parameters pass +validation on this endpoint, but the endpoint does not apply them. The Commitment Funnel always responds with JSON and +does not add benchmark rows. ::: ## Response The response contains a `data` array with one entry per brand data point. Each entry has `study`, `audience`, -`category`, `year`, `country`, `sector` and `brand` objects (each with `id` and `name`), a `brand_display_name`, a -`data_point_label` and a `metrics` array, where each metric has a `key`, `value` and `label`. +`category`, `year`, `country`, `sector` and `brand` objects (each with `id` and `name`). Each entry also has a +`brand_display_name`, a `data_point_label` and a `metrics` array. Each metric has a `key`, `value` and `label`. diff --git a/docs/brand-data/cost-of-entry.md b/docs/brand-data/cost-of-entry.md index d75281f..539bf2e 100644 --- a/docs/brand-data/cost-of-entry.md +++ b/docs/brand-data/cost-of-entry.md @@ -23,7 +23,7 @@ This endpoint uses the singular `brand`, `study` and `audience` parameters. :::caution -`comparisonName` is accepted but is currently not applied to the Cost of Entry output; the category or collection name -is used. +The endpoint accepts `comparisonName`, but it currently does not apply it to the Cost of Entry output. The output uses +the category or collection name. ::: diff --git a/docs/brand-data/data-models.md b/docs/brand-data/data-models.md index 3ffbe2e..0d92f2b 100644 --- a/docs/brand-data/data-models.md +++ b/docs/brand-data/data-models.md @@ -5,9 +5,9 @@ sidebar_label: Data Models # Data Models The data model endpoints return the data behind the core BAV data models, such as the Powergrid, Pillars and -Imagery. Rather than having to know which [brand metrics](../metrics/metrics.md) make up each model, you ask for the -model and get back the relevant metrics for each brand, together with the brand, study, audience and category they -belong to. +Imagery. You do not need to know which [brand metrics](../metrics/metrics.md) make up each model. You ask for the +model and you get the relevant metrics for each brand. Each data point also includes the brand, study, audience and +category that the metrics belong to. The following models are available: @@ -28,31 +28,30 @@ All data model endpoints require the **BAV Brand Data** (`bav:brand-data`) scope ## Category specific and category agnostic models -Most BAV metrics are category agnostic. Respondents are asked to evaluate the brand without a specific category in mind. +Most BAV metrics are category agnostic. The survey asks respondents to evaluate the brand without a specific category in mind. For these models, the category in the response has no analytical significance. -Usage, preferences, recommendation and Super CX are category specific. Respondents are asked about the brand in the -specific category it is studied in. For these models the category should always be shown together with the brand, as -it can significantly change the interpretation of the results. +Usage, preferences, recommendation and Super CX are category specific. The survey asks respondents about the brand in the +category in which the study includes the brand. For these models, always show the category together with the brand. +The category can significantly change the interpretation of the results. ## Creating a query -Each model is available as a `POST` request to `/api/v2/brandscape/{model}` where the parameters are sent as a JSON -body. +Each model is available as a `POST` request to `/api/v2/brandscape/{model}`. Send the parameters as a JSON body. ```http request POST /api/v2/brandscape/pillars ``` -Most models can also be requested with `GET` and query parameters, as part of the [tools](tools.md#data-model-tools). +You can also request most models with `GET` and query parameters, as part of the [tools](tools.md#data-model-tools). ## Parameters All data model endpoints share the same set of parameters. List parameters are arrays. In a query string, pass repeated values (`brands[]=148&brands[]=149`). Each value can be -either an ID or a name. When you pass a name, the system will attempt to find the right record based on the similarity -of the name. +either an ID or a name. If you pass a name, the system tries to find the correct record from the similarity of the +name. | Key | Required? | Type | Description | |---------------|:----------------------------------------:|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -61,15 +60,15 @@ of the name. | `countries` | At least one* | array | [Country](../metadata/countries.md) IDs, ISO 3166-1 alpha-2 or alpha-3 codes, or names. Max 50. | | `years` | At least one* | array | [Year](../metadata/years.md) IDs or year numbers (e.g. `2025`). Max 50. | | `audiences` | :x: (defaults to All Adults) | array | [Audience](../audiences/audiences.md) IDs or names. Max 50. | -| `study_types` | :x: (defaults to `syndicated`) | array | The kinds of study that a `countries` and `years` filter may resolve to: `syndicated` (the full BAV study), `snap` (SnapBAV), `fused` (AO+BAV, not comparable to syndicated studies) or `custom` (bespoke studies). Ignored when `studies` is set. | +| `study_types` | :x: (defaults to `syndicated`) | array | The kinds of study that a `countries` and `years` filter can resolve to: `syndicated` (the full BAV study), `snap` (SnapBAV), `fused` (AO+BAV, not comparable to syndicated studies) or `custom` (bespoke studies). The API ignores this parameter when `studies` is set. | | `benchmarks` | :x: | object | Benchmark the brands against the average of a competitive set. See [benchmarks](#benchmarks). | | `format` | :x: (defaults to `json`) | string | The response format. See [response formats](#response-formats). | \* At least one of `brands`, `studies`, `countries` or `years` is required. -When you filter by `countries` and `years` rather than `studies`, the studies are chosen for you, limited to -the `study_types` you ask for. By default only the syndicated studies are used, so that the response does not mix in -SnapBAV or fused studies that are not comparable to them. +If you filter by `countries` and `years` and not by `studies`, the API selects the studies for you. It selects only +studies of the `study_types` that you ask for. By default, the API uses only the syndicated studies. This prevents a +response that mixes syndicated studies with SnapBAV or fused studies, which are not comparable to them. An example `POST` body: @@ -84,8 +83,8 @@ An example `POST` body: ### Benchmarks -You can add comparison rows to the response by benchmarking the brands against the average of one or more competitive -sets. Each benchmark adds a row to the response. +To add comparison rows to the response, benchmark the brands against the average of one or more competitive sets. +Each benchmark adds a row to the response. - `benchmarks[categories]` - A comma-separated list of [category](../studies/categories.md) IDs. - `benchmarks[collections]` - A comma-separated list of [collection](../brands/collections.md) IDs. @@ -106,9 +105,9 @@ sets. Each benchmark adds a row to the response. The `format` parameter accepts: - `json` - The default. The standard API response documented below. -- `llm` - The data formatted for use in AI prompts. The response contains `model_instructions` (instructions describing +- `llm` - The data formatted for use in AI prompts. The response contains `model_instructions` (instructions that describe the model), `data` (the data as a CSV string) and `prompt` (a finished prompt that combines the instructions and the - data, ready to send to an AI model). + data, which you can send to an AI model). - `mcp` - The response shape used by our [MCP servers](../ai/mcp/intro.md). ## Schema @@ -119,10 +118,10 @@ The `json` response is an object with a `meta` object and a `data` array. | Key | Type | Description | |------------------------|---------|-------------------------------------------------------------------------------------------------| -| `source` | string | A source label naming the studies and audiences the data came from, suitable for captioning. | +| `source` | string | A source label that names the studies and audiences of the data. You can use it as a caption. | | `is_category_specific` | boolean | Whether the model is category specific. See [above](#category-specific-and-category-agnostic-models). | -Some models add extra keys to the meta object. These are listed on the model's page. +Some models add extra keys to the meta object. The page of each model lists these keys. ### Data @@ -143,9 +142,9 @@ Each item in `data` is a data point for one brand, in one study, category and au | `brand_id` | integer | The system ID of the [brand](../brands/brands.md). | | `brand_variation` | string | The brand variation, used to differentiate between different spellings of the same brand. | | `brand_variation_id` | integer | The system ID of the brand variation. | -| `brand_variation_key` | integer | The key of the brand variation. This can be both a positive and negative integer. | +| `brand_variation_key` | integer | The key of the brand variation. This can be a positive or a negative integer. | | `local_name` | string | The name of the brand (in English) as shown to the respondent in the survey. | -| `category` | string | The category that respondents were asked the brand's usage, preference and recommendation in. All other metrics are category agnostic and unrelated to the category. | +| `category` | string | The category in which respondents answered about the usage, preference and recommendation of the brand. All other metrics are category agnostic and not related to the category. | | `category_id` | integer | The system ID of the [category](../studies/categories.md). | | `sector` | string | The sector that the brand belongs to. | | `sector_id` | integer | The system ID of the [sector](../metadata/sectors.md). | @@ -155,7 +154,7 @@ Each item in `data` is a data point for one brand, in one study, category and au | `competitive_set` | string\|null | The name of the competitive set. Only set for benchmark rows. | | `competitive_set_id` | integer\|null | The system ID of the competitive set. Only set for benchmark rows. | | `competitive_set_type` | string\|null | The type of competitive set. Only set for benchmark rows. | -| `classification` | object\|null | The model's own reading of the data point, such as the Powergrid quadrant or pillar pattern. Only set on models that classify brands. See [classification](#classification). | +| `classification` | object\|null | The model's own interpretation of the data point, such as the Powergrid quadrant or pillar pattern. Only set on models that classify brands. See [classification](#classification). | | `metrics` | object | The metrics for the data point, keyed by metric key. See [metrics](#metrics). | ### Metrics @@ -166,24 +165,24 @@ the score types. A score type that the metric does not support is `null`. | Key | Type | Description | |--------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | `key` | string | The metric key. See [brand metrics](../metrics/metrics.md). | -| `rank` | float\|null | The percentile rank (0-100) comparing the brand to all other brands in the market. | +| `rank` | float\|null | The percentile rank (0-100) that compares the brand to all other brands in the market. | | `value` | float\|null | A raw value for metrics that have none of the other score types, such as base sizes. | | `percentage` | float\|null | The percentage (0-100) of respondents, for example those who selected the attribute. | -| `construct` | float\|null | The underlying calculated score for metrics built from other metrics or respondent-level measures. This is not meant for display or analysis. | +| `construct` | float\|null | The underlying calculated score for metrics built from other metrics or respondent-level measures. Do not use it for display or analysis. | | `brandscape_index` | float\|null | An index of the brand against the whole brandscape. Values above 100 are above average. | | `category_index` | float\|null | An index of the brand against its category. Values above 100 are above average. | ### Classification Models that classify brands, such as the [Powergrid](powergrid.md) and [Pillars](pillars.md), return a -`classification` object on each data point they could classify. Use it rather than deriving the classification from -the scores yourself. +`classification` object on each data point that they can classify. Use it. Do not derive the classification from the +scores yourself. | Key | Type | Description | |---------------|--------------|-----------------------------------------------------------------------------------------------------| -| `key` | string | The machine-readable key for the classification. This is stable, and what you should branch on. | +| `key` | string | The machine-readable key for the classification. This is stable. Use it for conditional logic. | | `label` | string | The human-readable name of the classification, as The Fount labels it. | -| `description` | string\|null | Copy describing what the classification means for the brand. Only set on some models. | +| `description` | string\|null | Copy that describes what the classification means for the brand. Only set on some models. | ### Example diff --git a/docs/brand-data/imagery.md b/docs/brand-data/imagery.md index 2c74ead..2f53845 100644 --- a/docs/brand-data/imagery.md +++ b/docs/brand-data/imagery.md @@ -15,7 +15,7 @@ Imagery is category agnostic. POST /api/v2/brandscape/imagery ``` -The parameters are sent as a JSON body. +Send the parameters as a JSON body. This endpoint requires the `bav:brand-data` scope. @@ -34,4 +34,4 @@ The response follows the [standard data model schema](data-models.md#schema). The data points include the metrics in the `imagery` [metric group](../metrics/metric-groups.md), each with: - `percentage` - The percentage of respondents who associate the brand with the attribute. -- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. +- `rank` - The percentile rank (0-100) that compares the brand to all other brands in the market. diff --git a/docs/brand-data/index.md b/docs/brand-data/index.md index 1c348e0..68953aa 100644 --- a/docs/brand-data/index.md +++ b/docs/brand-data/index.md @@ -1,15 +1,15 @@ # Overview -The brand data endpoints give you access to BAV's research data on brands. They come in two kinds: +The brand data endpoints give you access to the BAV research data on brands. There are two kinds of endpoints: - **[Brandscape data](brandscape-data.md)** is the raw data: every metric for each brand, study and audience. Use it when you want full control over which metrics you use and how you combine them. - **[Data models](data-models.md)** return the metrics behind one of the core BAV models, such as the - [Powergrid](powergrid.md), [Pillars](pillars.md) or [Imagery](imagery.md). You ask for the model, and get back the - relevant metrics for each brand, without needing to know which metrics make up the model. All data models share the + [Powergrid](powergrid.md), [Pillars](pillars.md) or [Imagery](imagery.md). You ask for the model and you get the + relevant metrics for each brand. You do not need to know which metrics make up the model. All data models share the same parameters and response. -If you want BAV data with further work done on it, such as the Commitment Funnel, a SWOT or the Agency Change Predictor, -see the [tools](tools.md). +If you want BAV data that has more processing applied to it, such as the Commitment Funnel, a SWOT or the +Agency Change Predictor, see the [tools](tools.md). All brand data endpoints require a token with the **BAV Brand Data** (`bav:brand-data`) scope. diff --git a/docs/brand-data/influence.md b/docs/brand-data/influence.md index 0765b47..98a3509 100644 --- a/docs/brand-data/influence.md +++ b/docs/brand-data/influence.md @@ -26,5 +26,5 @@ The response follows the [standard data model schema](data-models.md#schema). ### Metrics The data points include the metrics in the `influence` [metric group](../metrics/metric-groups.md), such as -`mib_innovation`, `mib_authenticity`, `mib_status` and `mib_trust`. The overall `mib_influential` metric is not -included in this model. +`mib_innovation`, `mib_authenticity`, `mib_status` and `mib_trust`. This model does not include the overall +`mib_influential` metric. diff --git a/docs/brand-data/partnership-exchange-map.md b/docs/brand-data/partnership-exchange-map.md index 244a6cb..9143c40 100644 --- a/docs/brand-data/partnership-exchange-map.md +++ b/docs/brand-data/partnership-exchange-map.md @@ -1,6 +1,6 @@ # Partnership Exchange Map -The Partnership Exchange Map compares the imagery attributes of two brands to show what each could bring to a +The Partnership Exchange Map compares the imagery attributes of two brands to show what each brand can bring to a partnership. ## Creating a query @@ -11,8 +11,8 @@ GET /api/v2/tools/partnership-exchange-map ## Parameters -Give one brand in `brands` and its partner in `comparison_brands`. The exchange is directional, so swapping the two -gives a different result. +Give one brand in `brands` and its partner in `comparison_brands`. The exchange is directional. If you swap the two +brands, you get a different result. | Key | Required? | Type | Description | |---------------------|:----------------------------:|---------|--------------------------------------| diff --git a/docs/brand-data/personality.md b/docs/brand-data/personality.md index d38c96b..53ff77b 100644 --- a/docs/brand-data/personality.md +++ b/docs/brand-data/personality.md @@ -1,6 +1,6 @@ # Personality -Personality types provide a higher-level understanding of how a brand is perceived by consumers. They categorize brands +Personality types give a higher-level understanding of how consumers perceive a brand. They categorize brands into ten distinct personality types based on the [imagery](imagery.md) attributes. The personality types are consistent across all studies. @@ -12,7 +12,7 @@ Personality is category agnostic. POST /api/v2/brandscape/personality ``` -The parameters are sent as a JSON body. +Send the parameters as a JSON body. This endpoint requires the `bav:brand-data` scope. @@ -31,4 +31,4 @@ The response follows the [standard data model schema](data-models.md#schema). The data points include the metrics in the `personality` [metric group](../metrics/metric-groups.md), each with: - `percentage` - The percentage of respondents who associate the brand with the personality type. -- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. +- `rank` - The percentile rank (0-100) that compares the brand to all other brands in the market. diff --git a/docs/brand-data/pillars.md b/docs/brand-data/pillars.md index a09e276..294e4fe 100644 --- a/docs/brand-data/pillars.md +++ b/docs/brand-data/pillars.md @@ -1,6 +1,6 @@ # Pillars -The four pillars of brand equity are one of the foundational concepts of BAV. They break down the +The four pillars of brand equity are one of the foundational concepts of BAV. They divide the [Powergrid](powergrid.md) into the four key dimensions that define a brand's position: - **Differentiation** @@ -8,7 +8,7 @@ The four pillars of brand equity are one of the foundational concepts of BAV. Th - **Esteem** - **Knowledge** -When charted, the pillars should be displayed as a column chart in the order above. +If you chart the pillars, show them as a column chart in the order above. Pillars are category agnostic. @@ -18,7 +18,7 @@ Pillars are category agnostic. POST /api/v2/brandscape/pillars ``` -The parameters are sent as a JSON body. +Send the parameters as a JSON body. This endpoint requires the `bav:brand-data` scope. @@ -36,11 +36,11 @@ The response follows the [standard data model schema](data-models.md#schema). The data points include the `differentiation`, `relevance`, `esteem` and `knowledge` metrics, each with: -- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. -- `construct` - The underlying construct score. This should not be used for display or analysis. +- `rank` - The percentile rank (0-100) that compares the brand to all other brands in the market. +- `construct` - The underlying construct score. Do not use it for display or analysis. ### Classification -The shape the four pillars make together is the brand's pillar pattern. Each data point includes its pattern as +The shape that the four pillars make together is the pillar pattern of the brand. Each data point includes its pattern as `classification`, with a `key` (for example `balanced-leader` or `cultural-icon`), a translated `label` and a `description` of what the pattern means for the brand. diff --git a/docs/brand-data/powergrid.md b/docs/brand-data/powergrid.md index 39f9ab9..5f2a8e0 100644 --- a/docs/brand-data/powergrid.md +++ b/docs/brand-data/powergrid.md @@ -1,24 +1,24 @@ # Powergrid -The BAV Powergrid is the core of the BAV brand equity model. It represents a brand's position based on two key +The BAV Powergrid is the core of the BAV brand equity model. It shows the position of a brand on two key dimensions: -- **Brand Strength** (the Y-axis) - How well a brand is perceived in terms of its differentiation and relevance. -- **Brand Stature** (the X-axis) - How well a brand is respected and known (esteem and knowledge). +- **Brand Strength** (the Y-axis) - How well consumers perceive a brand in terms of its differentiation and relevance. +- **Brand Stature** (the X-axis) - How well consumers respect and know a brand (esteem and knowledge). -The Powergrid is a two-by-two matrix that categorizes brands into four quadrants, where a percentile rank of 50 or above -is high and anything below 50 is low: +The Powergrid is a two-by-two matrix that categorizes brands into four quadrants. A percentile rank of 50 or above is high, +and a rank below 50 is low: - **Leadership** - High Brand Strength and high Brand Stature. Top right quadrant. - **Momentum** - High Brand Strength and low Brand Stature. Top left quadrant. - **Fatigued** - Low Brand Strength and high Brand Stature. Bottom right quadrant. - **Unfocused** - Low Brand Strength and low Brand Stature. Bottom left quadrant. -The Leadership quadrant can be further divided by a diagonal line from (50, 50) to (100, 100). Brands above the line are +A diagonal line from (50, 50) to (100, 100) can divide the Leadership quadrant further. Brands above the line are in **Leadership** and brands below the line are in **Mass Market**. -When charted, the Powergrid should be displayed as a scatter plot with lines crossing at 50 on both axes and with the -quadrant labels always shown. +If you chart the Powergrid, show it as a scatter plot. Draw lines that cross at 50 on both axes. Always show the +quadrant labels. The Powergrid is category agnostic. @@ -28,7 +28,7 @@ The Powergrid is category agnostic. POST /api/v2/brandscape/powergrid ``` -The parameters are sent as a JSON body. +Send the parameters as a JSON body. This endpoint requires the `bav:brand-data` scope. @@ -46,15 +46,16 @@ The response follows the [standard data model schema](data-models.md#schema). The data points include the `brand_strength` and `brand_stature` metrics, each with: -- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. -- `construct` - The underlying construct score. This should not be used for display or analysis. +- `rank` - The percentile rank (0-100) that compares the brand to all other brands in the market. +- `construct` - The underlying construct score. Do not use it for display or analysis. ### Classification Each data point includes its quadrant as `classification`, with a `key` of `leadership`, `momentum`, `fatigued` or -`unfocused`, and a translated `label`. Use it rather than deriving the quadrant from the ranks yourself. +`unfocused`, and a translated `label`. Use it. Do not derive the quadrant from the ranks yourself. ### Meta -In addition to the standard meta keys, the Powergrid adds a `labels` object with the translated axis labels -(`labels.axis.x` and `labels.axis.y`) and quadrant labels (`labels.quadrants`) for use when drawing the chart. +The Powergrid also adds a `labels` object to the standard meta keys. The object contains the translated axis labels +(`labels.axis.x` and `labels.axis.y`) and quadrant labels (`labels.quadrants`). Use these labels when you draw the +chart. diff --git a/docs/brand-data/preferences.md b/docs/brand-data/preferences.md index 410d875..d8bb3ae 100644 --- a/docs/brand-data/preferences.md +++ b/docs/brand-data/preferences.md @@ -7,10 +7,10 @@ Preferences show consumers' preference for brands on a scale: - One of several - One I prefer -Preferences are consistent across all studies and can be used to understand how likely consumers are to choose a brand. +Preferences are consistent across all studies. You can use them to understand how likely consumers are to choose a brand. -Preferences are category specific. Respondents are asked about their preference for the brand in the specific -category. The category should always be shown together with the brand, as it can significantly change the +Preferences are category specific. The survey asks respondents about their preference for the brand in the +specific category. Always show the category together with the brand. The category can significantly change the interpretation of the results. ## Creating a query @@ -19,7 +19,7 @@ interpretation of the results. POST /api/v2/brandscape/preferences ``` -The parameters are sent as a JSON body. +Send the parameters as a JSON body. This endpoint requires the `bav:brand-data` scope. @@ -37,5 +37,5 @@ The response follows the [standard data model schema](data-models.md#schema). The data points include the metrics in the `preference` [metric group](../metrics/metric-groups.md), each with: -- `percentage` - The percentage of respondents who fall into each preference level. -- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. +- `percentage` - The percentage of respondents who are in each preference level. +- `rank` - The percentile rank (0-100) that compares the brand to all other brands in the market. diff --git a/docs/brand-data/recommendation.md b/docs/brand-data/recommendation.md index ecfafb9..789a76b 100644 --- a/docs/brand-data/recommendation.md +++ b/docs/brand-data/recommendation.md @@ -2,8 +2,8 @@ Recommendation shows how likely consumers are to recommend a brand to a friend. It is consistent across all studies. -Recommendation is category specific. Respondents are asked about their likelihood to recommend the brand in the -specific category. The category should always be shown together with the brand, as it can significantly change the +Recommendation is category specific. The survey asks respondents about their likelihood to recommend the brand in +the specific category. Always show the category together with the brand. The category can significantly change the interpretation of the results. ## Creating a query @@ -12,7 +12,7 @@ interpretation of the results. POST /api/v2/brandscape/recommendation ``` -The parameters are sent as a JSON body. +Send the parameters as a JSON body. This endpoint requires the `bav:brand-data` scope. @@ -31,4 +31,4 @@ The response follows the [standard data model schema](data-models.md#schema). The data points include the metrics in the `recommendation` [metric group](../metrics/metric-groups.md), each with: - `percentage` - The percentage of respondents who would recommend the brand. -- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. +- `rank` - The percentile rank (0-100) that compares the brand to all other brands in the market. diff --git a/docs/brand-data/super-cx-tool.md b/docs/brand-data/super-cx-tool.md index 1607994..51509a0 100644 --- a/docs/brand-data/super-cx-tool.md +++ b/docs/brand-data/super-cx-tool.md @@ -4,11 +4,11 @@ sidebar_label: Super CX # Super CX Tool -Super CX measures a brand's perceived customer experience. It is made up of the overall Super CX score and its Head, -Heart and X Factor components, which in turn are built from a set of underlying measures. +Super CX measures a brand's perceived customer experience. It contains the overall Super CX score and its Head, Heart +and X Factor components. Each component is built from a set of underlying measures. -Super CX is category specific. The category should always be shown together with the brand, as it can significantly -change the interpretation of the results. +Super CX is category specific. Always show the category together with the brand. The category can significantly change +the interpretation of the results. The Super CX tool returns the percentile ranks of the Super CX metrics for a set of brands in one study. For Super CX data with the same parameters and response as the other data models, use the [Super CX data model](super-cx.md). @@ -68,4 +68,4 @@ The metric keys in `data` are: } ``` -The values in the example are illustrative, and only some of the metrics are shown. +The values in the example are illustrative, and the example shows only some of the metrics. diff --git a/docs/brand-data/super-cx.md b/docs/brand-data/super-cx.md index 2c220e1..cc6752a 100644 --- a/docs/brand-data/super-cx.md +++ b/docs/brand-data/super-cx.md @@ -1,13 +1,13 @@ # Super CX -Super CX measures a brand's perceived customer experience. It is made up of the overall Super CX score and its Head, -Heart and X Factor components, which in turn are built from a set of underlying measures. +Super CX measures a brand's perceived customer experience. It contains the overall Super CX score and its Head, Heart +and X Factor components. Each component is built from a set of underlying measures. -Super CX is category specific. The category should always be shown together with the brand, as it can significantly -change the interpretation of the results. +Super CX is category specific. Always show the category together with the brand. The category can significantly change +the interpretation of the results. There is also a [Super CX tool](super-cx-tool.md) with its own parameters and response. We recommend this data model -endpoint for new integrations, as it shares its parameters and response with the other [data models](data-models.md). +endpoint for new integrations, because it shares its parameters and response with the other [data models](data-models.md). ## Creating a query diff --git a/docs/brand-data/swot.md b/docs/brand-data/swot.md index d2fc22c..e9cf1e1 100644 --- a/docs/brand-data/swot.md +++ b/docs/brand-data/swot.md @@ -1,6 +1,6 @@ # SWOT -SWOT classifies a brand's imagery attributes as strengths, weaknesses, opportunities and threats, by comparing each +SWOT classifies the imagery attributes of a brand as strengths, weaknesses, opportunities and threats. It compares each attribute against the brand's own average and against the average of a competitive set. ## Creating a query @@ -18,4 +18,4 @@ GET /api/v2/tools/swot | `audiences` | :x: (defaults to All Adults) | numeric array | A comma-separated list of Audience IDs. | | `categories` | If no collections. | numeric array | A comma-separated list of Category IDs that form the competitive set. | | `collections` | If no categories. | numeric array | A comma-separated list of Collection IDs that form the competitive set. | -| `comparisonName` | :x: | string | Give the comparison a custom name (max 255 characters). Otherwise the category or collection name will be used. | +| `comparisonName` | :x: | string | Give the comparison a custom name (max 255 characters). If you do not give a name, the API uses the category or collection name. | diff --git a/docs/brand-data/tools.md b/docs/brand-data/tools.md index 683fa04..b31388c 100644 --- a/docs/brand-data/tools.md +++ b/docs/brand-data/tools.md @@ -4,35 +4,37 @@ sidebar_label: Overview # Tools -The tools do further work on BAV data, such as combining metrics to tell a specific story or running calculations to -arrive at new insights. They correspond to the tools in The Fount and its TurboPitch suite, such as the +The tools process BAV data further. For example, they combine metrics to tell a specific story, or they run calculations +to find new insights. They correspond to the tools in The Fount and its TurboPitch suite, such as the [Commitment Funnel](commitment-funnel.md), [SWOT](swot.md) or [Agency Change Predictor](agency-change-predictor.md). -Each tool has its own parameters and response, which are described on its page. We also suggest that you try each tool -in The Fount to get a better understanding of the results. +Each tool has its own parameters and response, which are described on its page. We also recommend that you try each tool +in The Fount to better understand the results. If you only need the metrics behind a BAV model, such as the Powergrid or Pillars, use the [data models](data-models.md) instead. ## Access -All tool endpoints require a token with the **BAV Brand Data** (`bav:brand-data`) scope. In addition, each tool -requires that the user has access to that tool in The Fount; otherwise a `403` response is returned. +All tool endpoints require a token with the **BAV Brand Data** (`bav:brand-data`) scope. Each tool also +requires that the user has access to that tool in The Fount. If the user does not have access, the API returns a `403` +response. ## Parameter formats -Most tool endpoints take comma-separated lists of IDs, for example `brands=148,149`. Where a page lists a parameter as -taking a single ID, only one value is accepted. The [Commitment Funnel](commitment-funnel.md) and the -[Agency Change Predictor](agency-change-predictor.md) instead follow the [data models](data-models.md) and take array -parameters (`brands[]=148&brands[]=149`), which also accept names, and can select studies by `countries` and `years`. +Most tool endpoints take comma-separated lists of IDs, for example `brands=148,149`. If a page lists a parameter as a +single ID, the parameter accepts only one value. The [Commitment Funnel](commitment-funnel.md) and the +[Agency Change Predictor](agency-change-predictor.md) use the parameter format of the [data models](data-models.md) +instead. They take array parameters (`brands[]=148&brands[]=149`), which also accept names. They can also select +studies by `countries` and `years`. -Unless stated otherwise, the `audiences` parameter defaults to All Adults (audience ID `1`), and responses are returned -as JSON in a `data` key. +Unless a page states otherwise, the `audiences` parameter defaults to All Adults (audience ID `1`). The API returns +responses as JSON in a `data` key. ## Data model tools -Most of the [data models](data-models.md) can also be requested as a tool, with a `GET` request and the -[data model parameters](data-models.md#parameters) sent as query parameters. The response is the same as for the data +You can also request most of the [data models](data-models.md) as a tool. Send a `GET` request with the +[data model parameters](data-models.md#parameters) as query parameters. The response is the same as for the data model. | Tool | Endpoint | Same as | diff --git a/docs/brand-data/usage.md b/docs/brand-data/usage.md index 06787ce..81e887f 100644 --- a/docs/brand-data/usage.md +++ b/docs/brand-data/usage.md @@ -9,8 +9,8 @@ Usage shows how consumers use brands on a scale: Usage is consistent across all studies. -Usage is category specific. Respondents are asked about their usage of the brand in the specific category. The -category should always be shown together with the brand, as it can significantly change the interpretation of the +Usage is category specific. The survey asks respondents about their usage of the brand in the specific category. +Always show the category together with the brand. The category can significantly change the interpretation of the results. ## Creating a query @@ -19,7 +19,7 @@ results. POST /api/v2/brandscape/usage ``` -The parameters are sent as a JSON body. +Send the parameters as a JSON body. This endpoint requires the `bav:brand-data` scope. @@ -37,5 +37,5 @@ The response follows the [standard data model schema](data-models.md#schema). The data points include the metrics in the `usage` [metric group](../metrics/metric-groups.md), each with: -- `percentage` - The percentage of respondents who fall into each usage level. -- `rank` - The percentile rank (0-100) comparing the brand to all other brands in the market. +- `percentage` - The percentage of respondents who are in each usage level. +- `rank` - The percentile rank (0-100) that compares the brand to all other brands in the market. From 9e55502128fc944c797b46745979cc132e274cbc Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sun, 25 Oct 2026 10:33:34 +0100 Subject: [PATCH 16/23] Rewrite audiences, Audience Origin, Best Countries and brands docs in Simplified Technical English Co-Authored-By: Claude Opus 5.5 --- docs/audience-origin/frequencies.md | 20 ++--- docs/audience-origin/index.md | 16 ++-- docs/audience-origin/metric-groups.md | 20 ++--- docs/audience-origin/metrics.md | 23 ++--- docs/audience-origin/query.md | 19 +++-- docs/audience-origin/touchpoints.md | 20 ++--- docs/audiences/audience-groups.md | 16 ++-- docs/audiences/audiences.md | 91 ++++++++++---------- docs/audiences/export.md | 112 ++++++++++++------------ docs/audiences/managing-audiences.md | 118 +++++++++++++------------- docs/best-countries/country-data.md | 28 +++--- docs/best-countries/factors.md | 28 +++--- docs/best-countries/index.md | 6 +- docs/best-countries/metric-groups.md | 22 ++--- docs/best-countries/metrics.md | 8 +- docs/best-countries/models.md | 16 ++-- docs/best-countries/raw-data.md | 23 +++-- docs/brands/brand-tags.md | 12 +-- docs/brands/brand-variations.md | 32 +++---- docs/brands/brands.md | 96 ++++++++++----------- docs/brands/collections.md | 38 ++++----- 21 files changed, 382 insertions(+), 382 deletions(-) diff --git a/docs/audience-origin/frequencies.md b/docs/audience-origin/frequencies.md index ae8a3d1..165ff5b 100644 --- a/docs/audience-origin/frequencies.md +++ b/docs/audience-origin/frequencies.md @@ -2,13 +2,13 @@ ## What are frequencies? -Some [Audience Origin metrics](metrics.md) measure a frequency, that is how often something happens. A metric that -measures a frequency is linked to it, which lets you find all the metrics for a given frequency, either with the -`metrics` include here or with the `frequency_id` filter on the metrics endpoint. +Some [Audience Origin metrics](metrics.md) measure a frequency, that is, how often something occurs. A metric that +measures a frequency has a link to it. Thus you can find all the metrics for a given frequency. Use the `metrics` +include here or the `frequency_id` filter on the metrics endpoint. ## List all frequencies -To list all of the frequencies and browse them via the API, use the list endpoint: +To list all of the frequencies and browse them through the API, use the list endpoint: ```http request GET /api/v2/audience-origin/frequencies @@ -16,7 +16,7 @@ GET /api/v2/audience-origin/frequencies ## Get a frequency -You may also directly retrieve a frequency's details if you already have its system ID. +If you already have the system ID of a frequency, you can also get its details directly. ```http request GET /api/v2/audience-origin/frequencies/123 @@ -38,7 +38,7 @@ Where `123` is the system ID of the frequency. ### Relationship Response Schema -The slim relationship schema is used when the frequency is used as part of an include in another resource. +The API uses the slim relationship schema when the frequency is part of an include in another resource. | Key | Type | Description | |--------|---------|-----------------------------------| @@ -48,14 +48,14 @@ The slim relationship schema is used when the frequency is used as part of an in ## Additional Filters -For convenience, we have a set of additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +For convenience, there is a set of additional filters. These filters are not in +the [default filters](../customizing/filters.md) and are not columns. The additional filters are: -- `has_metrics` - Set to `1` to only return frequencies that are used by at least one metric. +- `has_metrics` - Set to `1` to return only frequencies that are used by at least one metric. ## Relationships & includes -By default, relationships are not included. See +By default, the response does not include relationships. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: diff --git a/docs/audience-origin/index.md b/docs/audience-origin/index.md index b17eb2e..e46d7fa 100644 --- a/docs/audience-origin/index.md +++ b/docs/audience-origin/index.md @@ -7,11 +7,11 @@ sidebar_label: Overview Audience Origin is WPP's global study of people's media consumption, attitudes and behaviors. It contains demographic, psychographic and behavioral data on people from around the world. -The Audience Origin API is made up of two parts: +The Audience Origin API has two parts: -- **The catalog.** The [metrics](metrics.md) that are measured, the [metric groups](metric-groups.md) they are - organized in, and the [touchpoints](touchpoints.md) and [frequencies](frequencies.md) that media metrics measure. Use - these to find out what you can ask for. +- **The catalog.** The measured [metrics](metrics.md), the [metric groups](metric-groups.md) that contain them, and the + [touchpoints](touchpoints.md) and [frequencies](frequencies.md) that media metrics measure. Use these endpoints to + find the data that you can request. - **The data.** The [query endpoint](query.md) returns the Audience Origin data for a set of metrics in one or more studies, for an [audience](../audiences/audiences.md). @@ -20,14 +20,14 @@ endpoint to find the Audience Origin studies you have access to. ## Access -All Audience Origin endpoints require the `bav:audience-origin-data` scope (shown as **Audience Origin Data** when you -create your API key). Your user also needs access to Audience Origin data in The Fount. +All Audience Origin endpoints require the `bav:audience-origin-data` scope. This scope shows as **Audience Origin +Data** when you create your API key. Your user also needs access to Audience Origin data in The Fount. :::note Access is granted separately -The Audience Origin Data scope can only be added to an API key if your user has access to Audience Origin data. +You can add the Audience Origin Data scope to an API key only if your user has access to Audience Origin data. ::: ## Building audiences from Audience Origin -Audience Origin metrics can be used as conditions when [building your own audiences](../audiences/managing-audiences.md). +You can use Audience Origin metrics as conditions when you [build your own audiences](../audiences/managing-audiences.md). Use the `audience-origins-metric` metric type together with the ID of the metric. diff --git a/docs/audience-origin/metric-groups.md b/docs/audience-origin/metric-groups.md index 10bce75..a56032f 100644 --- a/docs/audience-origin/metric-groups.md +++ b/docs/audience-origin/metric-groups.md @@ -5,11 +5,11 @@ [Audience Origin metrics](metrics.md) are organized in metric groups, such as a group for media usage or for attitudes. Groups nest one level deep: a top-level group can have child groups, and metrics belong to a group. -The `key` of a group can be used in the [query endpoint](query.md) to get the data for every metric in the group. +You can use the `key` of a group in the [query endpoint](query.md) to get the data for every metric in the group. ## List all Audience Origin metric groups -To list all of the metric groups and browse them via the API, use the list endpoint: +To list all of the metric groups and browse them through the API, use the list endpoint: ```http request GET /api/v2/audience-origin/metric-groups @@ -17,7 +17,7 @@ GET /api/v2/audience-origin/metric-groups ## Get an Audience Origin metric group -You may also directly retrieve a metric group's details if you already have its system ID. +If you already have the system ID of a metric group, you can also get its details directly. ```http request GET /api/v2/audience-origin/metric-groups/123 @@ -41,7 +41,7 @@ Where `123` is the system ID of the metric group. ### Relationship Response Schema -The slim relationship schema is used when the metric group is used as part of an include in another resource. +The API uses the slim relationship schema when the metric group is part of an include in another resource. | Key | Type | Description | |-------------|---------|-----------------------------------------------------------------------------| @@ -49,19 +49,19 @@ The slim relationship schema is used when the metric group is used as part of an | `name` | string | The name of the metric group. | | `key` | string | The key of the metric group. | | `is_parent` | boolean | Whether this is a top-level metric group. | -| `parent` | object | The parent metric group, when it has been included. | +| `parent` | object | The parent metric group, when you include it. | ## Additional Filters -For convenience, we have a set of additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +For convenience, there is a set of additional filters. These filters are not in +the [default filters](../customizing/filters.md) and are not columns. The additional filters are: -- `only_parents` - Set to `1` to only return top-level groups. -- `only_children` - Set to `1` to only return groups nested under a parent. +- `only_parents` - Set to `1` to return only top-level groups. +- `only_children` - Set to `1` to return only groups nested under a parent. ## Relationships & includes -By default, relationships are not included. See +By default, the response does not include relationships. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available on the list endpoint: diff --git a/docs/audience-origin/metrics.md b/docs/audience-origin/metrics.md index bdc4bc2..c66f3f5 100644 --- a/docs/audience-origin/metrics.md +++ b/docs/audience-origin/metrics.md @@ -6,14 +6,14 @@ Audience Origin metrics are the questions and variables in the [Audience Origin] belongs to a [metric group](metric-groups.md). Media metrics can also measure a [touchpoint](touchpoints.md) and a [frequency](frequencies.md). -The `key` of a metric is what you use to ask for its data in the [query endpoint](query.md). +Use the `key` of a metric to request its data in the [query endpoint](query.md). Not every metric is available in every study. Use the `for_studies` filter or the `studies` include to see where a metric is available. ## List all Audience Origin metrics -To list all of the Audience Origin metrics and browse them via the API, use the list endpoint: +To list all of the Audience Origin metrics and browse them through the API, use the list endpoint: ```http request GET /api/v2/audience-origin/metrics @@ -21,7 +21,7 @@ GET /api/v2/audience-origin/metrics ## Get an Audience Origin metric -You may also directly retrieve a metric's details if you already have its system ID. +If you already have the system ID of a metric, you can also get its details directly. ```http request GET /api/v2/audience-origin/metrics/123 @@ -51,7 +51,7 @@ Where `123` is the system ID of the metric. ### Relationship Response Schema -The slim relationship schema is used when the metric is used as part of an include in another resource. +The API uses the slim relationship schema when the metric is part of an include in another resource. | Key | Type | Description | |-------------|---------|-------------------------------------------------------------------------------------| @@ -77,19 +77,20 @@ value can mean different things in two studies. ## Additional Filters -For convenience, we have a set of additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +For convenience, there is a set of additional filters. These filters are not in +the [default filters](../customizing/filters.md) and are not columns. The additional filters are: - `touchpoint_id` - The ID of a [touchpoint](touchpoints.md) to filter by. - `frequency_id` - The ID of a [frequency](frequencies.md) to filter by. -- `for_studies` - A comma-separated list of study IDs. Only metrics available in these studies are returned. -- `has_touchpoint` - Set to `1` to only return metrics with a touchpoint. -- `has_frequency` - Set to `1` to only return metrics with a frequency. -- `has_studies` - Set to `1` to only return metrics that are available in at least one study. +- `for_studies` - A comma-separated list of study IDs. The filter returns only metrics that are available in these + studies. +- `has_touchpoint` - Set to `1` to return only metrics with a touchpoint. +- `has_frequency` - Set to `1` to return only metrics with a frequency. +- `has_studies` - Set to `1` to return only metrics that are available in at least one study. ## Relationships & includes -By default, relationships are not included. See +By default, the response does not include relationships. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: diff --git a/docs/audience-origin/query.md b/docs/audience-origin/query.md index ac35163..cab6dda 100644 --- a/docs/audience-origin/query.md +++ b/docs/audience-origin/query.md @@ -5,11 +5,12 @@ sidebar_label: Query Data # Querying Audience Origin Data The query endpoint returns Audience Origin data for a set of [metrics](metrics.md) in one or more Audience Origin -studies. The data is returned for an [audience](../audiences/audiences.md), which defaults to All Adults. +studies. The endpoint returns the data for an [audience](../audiences/audiences.md). The default audience is All +Adults. ## Creating a query -The query is sent as a `POST` request with a JSON body: +Send the query as a `POST` request with a JSON body: ```http request POST /api/v2/audience-origin/query @@ -25,21 +26,21 @@ POST /api/v2/audience-origin/query } ``` -You choose which metrics to get data for with `metrics`, `metric_keys`, `metric_group_keys` or `metric_group_ids`. You -can combine these, and a group returns every metric in it. +To select the metrics to get data for, use `metrics`, `metric_keys`, `metric_group_keys` or `metric_group_ids`. You can +combine these parameters. A group returns every metric in it. ### Parameters -All parameters are passed inside the `filter` object. +Send all parameters inside the `filter` object. | Key | Type | Required | Description | |---------------------|---------|:------------------:|--------------------------------------------------------------------------------------------------------------------------------------| -| `studies` | array | :white_check_mark: | The IDs of the Audience Origin [studies](../studies/studies.md) to read from. Only active Audience Origin studies you have access to are accepted. | +| `studies` | array | :white_check_mark: | The IDs of the Audience Origin [studies](../studies/studies.md) to read from. The endpoint accepts only active Audience Origin studies that you have access to. | | `metrics` | array | :x: | The IDs of the [metrics](metrics.md) to return. | | `metric_keys` | array | :x: | The keys of the [metrics](metrics.md) to return. | | `metric_group_keys` | array | :x: | The keys of [metric groups](metric-groups.md) to return every metric from. | | `metric_group_ids` | array | :x: | The IDs of [metric groups](metric-groups.md) to return every metric from. | -| `quarters` | array | :x: | The quarters of the year to include, as numbers from `1` to `4`. All quarters are included by default. | +| `quarters` | array | :x: | The quarters of the year to include, as numbers from `1` to `4`. By default, the endpoint includes all quarters. | | `audience` | integer | :x: | The ID of the [audience](../audiences/audiences.md) to get the data for. Defaults to All Adults (`1`). | If any of the parameters are invalid, for example a study that is not an Audience Origin study or a metric key that @@ -119,14 +120,14 @@ a `metrics` object with the data for each metric. | `id` | integer | The system ID of the [metric](metrics.md). | | `key` | string | The key of the metric. | | `name` | string | The name of the metric. | -| `label` | string | The label of the metric. Falls back to the name. | +| `label` | string | The label of the metric. If there is no label, this is the name. | | `type` | string | The type of the metric, such as `dictionary`, `boolean`, `integer` or `decimal`. | | `values` | object | The scores for the metric, keyed by value. See below. | | `dictionary` | object | The answer options for the metric, as a map of values to labels. | | `primaryGroup` | string | The name of the parent [metric group](metric-groups.md), if any. | | `secondaryGroup` | string | The name of the metric group the metric belongs to, if any. | -How `values` is built depends on the type of the metric: +The structure of `values` depends on the type of the metric: - **Dictionary and integer metrics.** One entry per value, with the `value`, its `label`, the `score` and a `full_label` that combines the metric label and the value label. The score is the weighted percentage of respondents diff --git a/docs/audience-origin/touchpoints.md b/docs/audience-origin/touchpoints.md index 5140661..a6fc41e 100644 --- a/docs/audience-origin/touchpoints.md +++ b/docs/audience-origin/touchpoints.md @@ -2,13 +2,13 @@ ## What are touchpoints? -Some [Audience Origin metrics](metrics.md) measure a touchpoint. A metric that measures a touchpoint is linked to it, -which lets you find all the metrics for a given touchpoint, either with the `metrics` include here or with the -`touchpoint_id` filter on the metrics endpoint. +Some [Audience Origin metrics](metrics.md) measure a touchpoint. A metric that measures a touchpoint has a link to it. +Thus you can find all the metrics for a given touchpoint. Use the `metrics` include here or the `touchpoint_id` filter +on the metrics endpoint. ## List all touchpoints -To list all of the touchpoints and browse them via the API, use the list endpoint: +To list all of the touchpoints and browse them through the API, use the list endpoint: ```http request GET /api/v2/audience-origin/touchpoints @@ -16,7 +16,7 @@ GET /api/v2/audience-origin/touchpoints ## Get a touchpoint -You may also directly retrieve a touchpoint's details if you already have its system ID. +If you already have the system ID of a touchpoint, you can also get its details directly. ```http request GET /api/v2/audience-origin/touchpoints/123 @@ -38,7 +38,7 @@ Where `123` is the system ID of the touchpoint. ### Relationship Response Schema -The slim relationship schema is used when the touchpoint is used as part of an include in another resource. +The API uses the slim relationship schema when the touchpoint is part of an include in another resource. | Key | Type | Description | |--------|---------|------------------------------------| @@ -48,14 +48,14 @@ The slim relationship schema is used when the touchpoint is used as part of an i ## Additional Filters -For convenience, we have a set of additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +For convenience, there is a set of additional filters. These filters are not in +the [default filters](../customizing/filters.md) and are not columns. The additional filters are: -- `has_metrics` - Set to `1` to only return touchpoints that are used by at least one metric. +- `has_metrics` - Set to `1` to return only touchpoints that are used by at least one metric. ## Relationships & includes -By default, relationships are not included. See +By default, the response does not include relationships. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: diff --git a/docs/audiences/audience-groups.md b/docs/audiences/audience-groups.md index af547e1..526a59d 100644 --- a/docs/audiences/audience-groups.md +++ b/docs/audiences/audience-groups.md @@ -2,13 +2,13 @@ ## What are audience groups? -[Audiences](audiences.md) are cuts of respondents that can be used to analyze datasets. Audience Groups are a way to -organize audiences into groups. For example, there are several audiences for different age cuts which are all grouped -under the Age group. +[Audiences](audiences.md) are cuts of respondents that you can use to analyze datasets. Audience Groups organize +audiences into groups. For example, there are several audiences for different age cuts, and the Age group contains all +of them. ## List all audience groups -To list all of the audience groups and browse them via the API, use the list endpoint: +To list all of the audience groups and browse them through the API, use the list endpoint: ```http request GET /api/v2/audience-groups @@ -16,7 +16,7 @@ GET /api/v2/audience-groups ## Get an audience group -You may also directly retrieve an audience group's details if you already have its system ID. +If you already have the system ID of an audience group, you can also get its details directly. ```http request GET /api/v2/audience-groups/123 @@ -40,7 +40,7 @@ The audience groups endpoints are read-only. ### Relationship Response Schema -The slim relationship schema is used when the audience group is used as part of an include in another resource. +The API uses the slim relationship schema when the audience group is part of an include in another resource. | Key | Type | Description | |--------|---------|-----------------------------------------| @@ -49,11 +49,11 @@ The slim relationship schema is used when the audience group is used as part of ## Relationships & includes -By default, relationships are not included. See +By default, the response does not include relationships. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: -- `audiences` - The [audiences](audiences.md) that belong to this audience group, using the +- `audiences` - The [audiences](audiences.md) that belong to this audience group, with the [audience relationship schema](audiences.md#relationship-response-schema). ## Searching diff --git a/docs/audiences/audiences.md b/docs/audiences/audiences.md index 93c8e13..172697e 100644 --- a/docs/audiences/audiences.md +++ b/docs/audiences/audiences.md @@ -1,29 +1,29 @@ # Audiences -You may use the Audiences endpoint to retrieve details about one or more audiences. +Use the Audiences endpoint to get details about one or more audiences. ## What are audiences? -Audiences are the core of all our datasets. An audience is a group of respondents, such as women aged 18-34. Brand -data is always read for a study and an audience. +Audiences are the core of all our datasets. An audience is a group of respondents, such as women aged 18-34. You +always read brand data for a study and an audience. -Examples of audiences include: All Adults (everyone), Female, Age 18-25, etc. +Examples of audiences include All Adults (everyone), Female and Age 18-25. -For the BAV dataset they correspond to the available cuts of data that you can access on audiences. For the Best -Countries dataset they correspond to a set of filters that you can then query the dataset with. +For the BAV dataset, audiences are the available cuts of data that you can access. For the Best Countries dataset, +audiences are a set of filters that you can use to query the dataset. -Audiences can be active and inactive. Your application should not display inactive audiences to users even if they are +Audiences can be active or inactive. Do not show inactive audiences to users in your application, even if they are available through the API. -Audiences can also be public/private. Public audiences are available to all users across the group. Private audiences -are only accessible by the user who owns them and the users they have been shared with. The API only returns the -audiences you have access to: public audiences, your own audiences and audiences shared with you. +Audiences can also be public or private. Public audiences are available to all users across the group. Only the user +who owns a private audience and the users it is shared with can access it. The API returns only the audiences you have +access to: public audiences, your own audiences and audiences shared with you. -Audiences are either standard audiences provided by The Fount (`is_standard`) or audiences built by users. A new -audience has no data until it is deployed. +An audience is either a standard audience from The Fount (`is_standard`) or an audience that a user built. A new +audience has no data until you deploy it. -Audiences in turn belong to [audience groups](audience-groups.md). These groups can be used to create a better -selection experience in an interface as the number of audiences can be plentiful. +Audiences belong to [audience groups](audience-groups.md). There can be many audiences, so you can use these groups to +make the selection of audiences easier in an interface. :::tip Creating and managing audiences @@ -34,7 +34,7 @@ segments and metrics, see [Managing audiences](managing-audiences.md). ## List all audiences -To list all of the audiences and browse them via the API, use the list endpoint: +To list all of the audiences and browse them through the API, use the list endpoint: ```http request GET /api/v2/audiences @@ -42,7 +42,7 @@ GET /api/v2/audiences ## Get a single audience -You may also directly retrieve an audience's details if you already have its system ID. +If you already have the system ID of an audience, you can also get its details directly. ```http request GET /api/v2/audiences/1 @@ -56,20 +56,20 @@ The All Adults audience is our definition of "unfiltered" or "everyone". It alwa ## Get the studies for an audience -To list the studies an audience has data in, along with the audience's size in each study, use: +To list the studies that an audience has data in, and the size of the audience in each study, use: ```http request GET /api/v2/audiences/1/studies ``` -Where `1` is the system ID of the audience. An audience that has not been deployed has no studies. This endpoint is -paginated and returns the following for each study: +Where `1` is the system ID of the audience. An audience that is not deployed has no studies. This endpoint is +paginated and returns these keys for each study: | Key | Type | Description | |---------------|---------|---------------------------------------------------------------------------------------------------| | `study` | object | The [study](../studies/studies.md#relationship-response-schema), with its `country` and `year`. | | `respondents` | integer | The number of respondents in this study who are in the audience. | -| `population` | integer | The population projection: the number of people the audience represents in the study's market. Calculated when the audience is deployed. `null` for markets without a population figure to project to. | +| `population` | integer | The population projection: the number of people the audience represents in the study's market. The API calculates it when you deploy the audience. `null` for markets without a population figure to project to. | ## Schema @@ -80,51 +80,52 @@ paginated and returns the following for each study: | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | | `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The display name of the audience. | | `description` | string | :x: | :x: | :white_check_mark: | A more detailed description (optional) of the audience. | -| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience is active (should be used) or not. Please don't show inactive audiences in a user interface. | +| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience is active (for use) or not. Do not show inactive audiences in a user interface. | | `is_public` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience is publicly available to everyone (true) or restricted (false). | | `is_standard` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the audience is one of The Fount's standard audiences. | | `available_for_diversity` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience can be used for diversity analysis (the Consumer Equality Equation study). | | `is_ethnic_minority` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether this audience represents an ethnic minority group. | | `deployed_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when the audience was last deployed. `null` if it has never been deployed. | -| `definitions_updated_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when the audience's segments last changed. If this is later than `deployed_at`, the audience must be deployed again for the change to show in its data. | -| `deleted_at` | string | :x: | :x: | :white_check_mark: | Always `null`. Deleted audiences are not returned. | +| `definitions_updated_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when the audience's segments last changed. If this is later than `deployed_at`, deploy the audience again to show the change in its data. | +| `deleted_at` | string | :x: | :x: | :white_check_mark: | Always `null`. The API does not return deleted audiences. | | `url` | string | :x: | :x: | :x: | The URL to view the audience in The Fount. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this audience was first created. | | `updated_at` | string | ([updated since](../customizing/filters.md)) | :white_check_mark: | :white_check_mark: | A datetime string when this audience was last updated. | -The `group`, `user` and `definitions` keys are added when the matching relationship is [included](#relationships--includes). +The API adds the `group`, `user` and `definitions` keys when you [include](#relationships--includes) the matching +relationship. :::caution Removed fields -`available_for_bav`, `available_for_bc` and `bc_filters` are no longer part of the full audience response. The first -two are still part of the relationship schema below. +`available_for_bav`, `available_for_bc` and `bc_filters` are no longer part of the full audience response. +`available_for_bav` and `available_for_bc` are still part of the relationship schema below. ::: ### Relationship Response Schema -The slim relationship schema is used when the audience is used as part of an include in another resource, for example +The API uses the slim relationship schema when the audience is part of an include in another resource, for example the `audiences` include on [audience groups](audience-groups.md). | Key | Type | Description | |---------------------|---------|--------------------------------------------------------------------------------------------------------------------| | `id` | integer | The system ID for the audience. | | `name` | string | The primary name of the audience. | -| `is_active` | boolean | Whether this audience is active (should be used) or not. Please don't show inactive audiences in a user interface. | +| `is_active` | boolean | Whether this audience is active (for use) or not. Do not show inactive audiences in a user interface. | | `is_public` | boolean | Whether this audience is publicly available to everyone (true) or restricted (false). | | `available_for_bav` | boolean | Whether this audience can be used with the BAV dataset. | | `available_for_bc` | boolean | Whether this audience can be used with the Best Countries dataset. | ### Definition Schema -The `definitions` include returns a list of definitions. An audience without definitions cannot be deployed. +The `definitions` include returns a list of definitions. You cannot deploy an audience without definitions. | Key | Type | Description | |---------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | integer | The definition ID. | | `defined_for` | object | What the definition is limited to: `type` is `country` or `study`, with the `id` of that record. Both are `null` when the definition applies to all of the audience's data. | | `dataset` | object | The dataset the definition reads, as a `key` and a `label`. | -| `segments` | array | The definition's segments, when `definitions.segments` is included. Each has `id`, `uuid`, `sort_order`, `name`, `within_segment_operator`, `between_segments_operator`, `created_at`, `updated_at` and, when `definitions.segments.metrics` is included, `metrics`. | +| `segments` | array | The definition's segments, when you include `definitions.segments`. Each segment has `id`, `uuid`, `sort_order`, `name`, `within_segment_operator`, `between_segments_operator`, `created_at` and `updated_at`. When you include `definitions.segments.metrics`, each segment also has `metrics`. | | `created_at` | string | A datetime string when the definition was created. | | `updated_at` | string | A datetime string when the definition was last updated. | @@ -132,28 +133,28 @@ See [Managing audiences](managing-audiences.md) for the full segment and metric ## Additional Filters -For convenience, we have a set of additional filters for audiences that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: - -- `active` - Set to `1` to only return active audiences. -- `inactive` - Set to `1` to only return inactive audiences. -- `public` - Set to `1` to only return public audiences. -- `private` - Set to `1` to only return private audiences. -- `system_provided` - Set to `1` to only return The Fount's standard audiences. -- `user_generated` - Set to `1` to only return audiences built by users. -- `has_definitions` - Set to `1` to only return audiences with at least one definition. -- `groups` - A comma-separated list of audience group IDs. This will only return audiences that belong to the +For convenience, audiences have a set of additional filters. These filters are not in +the [default filters](../customizing/filters.md) and are not columns. The additional filters are: + +- `active` - Set to `1` to return only active audiences. +- `inactive` - Set to `1` to return only inactive audiences. +- `public` - Set to `1` to return only public audiences. +- `private` - Set to `1` to return only private audiences. +- `system_provided` - Set to `1` to return only The Fount's standard audiences. +- `user_generated` - Set to `1` to return only audiences that users built. +- `has_definitions` - Set to `1` to return only audiences with one or more definitions. +- `groups` - A comma-separated list of audience group IDs. The filter returns only audiences that belong to the specified groups. -- `users` - A comma-separated list of user IDs. This will only return audiences owned by the specified users. -- `available_for_studies` - A comma-separated list of study IDs. This will only return audiences with data available in - the specified studies. +- `users` - A comma-separated list of user IDs. The filter returns only audiences that the specified users own. +- `available_for_studies` - A comma-separated list of study IDs. The filter returns only audiences with data in the + specified studies. For the `active`, `inactive`, `public`, `private`, `system_provided`, `user_generated` and `has_definitions` filters, any value turns the filter on. ## Relationships & includes -By default, relationships are not included. See the [includes section](../customizing/includes.md) for more information +By default, the response does not include relationships. See the [includes section](../customizing/includes.md) for more information on how this works. The following relationships are available: - `group` - The [audience group](audience-groups.md) that this audience belongs to. diff --git a/docs/audiences/export.md b/docs/audiences/export.md index 769d58e..9dbe07a 100644 --- a/docs/audiences/export.md +++ b/docs/audiences/export.md @@ -4,86 +4,84 @@ sidebar_label: Export # Exporting Audiences -[Audiences](../audiences/audiences.md) are the core of all our datasets. They are used to define the group of -respondents we want to analyze data for. It can be useful to make audiences created within The Fount available in -your own systems. This is what the Audience Export Integration is designed for. +[Audiences](../audiences/audiences.md) are the core of all our datasets. An audience defines the group of respondents +that we analyze data for. You can make the audiences that users create in The Fount available in your own systems. The +Audience Export Integration has this purpose. ## How it works -All audiences are available through the [Audiences API](audiences.md) and you can listen to data change events for -updated audiences through [Webhooks](../webhooks.md). However, doing so requires you to always maintain the -full list of audiences in your system. This is where the Audience Export Integration comes in. +All audiences are available through the [Audiences API](audiences.md). You can also listen to data change events for +updated audiences through [Webhooks](../webhooks.md). But then you must always keep the full list of audiences in your +system. The Audience Export Integration solves this problem. -With the Audience Export Integration your application is added as an export destination for an audience within The -Fount. At any point in time users can export the audience, selecting your application as the destination. This triggers -a webhook event to your application with the audience data. +With the Audience Export Integration, The Fount adds your application as an export destination for an audience. Users +can export the audience at any time and select your application as the destination. The export sends a webhook event +with the audience data to your application. -You can then use the data to update your application with the latest audience data, letting the user access the audience -right away in your application. +You can then use this data to update your application with the latest audience data. The user can then access the +audience in your application immediately. ## Export formats -We offer four formats for the audience export: +There are four formats for the audience export: -1. **Audience Definition**. This is the full audience definition with segments and metrics and their logic. This is - useful if you want to recreate the audience in your own system. This is the same format as is available through +1. **Audience Definition**. This is the full audience definition with segments and metrics and their logic. Use this + format if you want to create the audience again in your own system. This format is the same as the format in the [Audiences API](../audiences/audiences.md). 2. **BAV Respondent IDs**. A list of BAV Respondent IDs that are part of the audience. This format requires specific approval from BAV. 3. **Audience Origin Respondent IDs**. A list of AO IDs for each respondent that matches the audience definition. This format requires specific approval from Choreograph. 4. **Audience Origin Respondent Progressive Numbers**. A list of progressive - number IDs for each respondent that matches the audience definition. These numbers are primarily used within the - Italy Audience Creator. This format requires specific approval from Choreograph. + number IDs for each respondent that matches the audience definition. The Italy Audience Creator is the + primary user of these numbers. This format requires specific approval from Choreograph. -Which format you choose depends on your use case and the data you need, as well as which studies you are working with. -The first format is always available for all datasets. The second format is available for all BAV studies. Formats 3 and +The format that you choose depends on your use case, the data you need and the studies that you work with. The first +format is always available for all datasets. The second format is available for all BAV studies. Formats 3 and 4 are available for all Audience Origin studies. -In addition, formats 2, 3 and 4 are available for all fused studies (the "AO+BAV Fused" study type). These are studies -where BAV and Audience Origin data have been fused together. +Formats 2, 3 and 4 are also available for all fused studies (the "AO+BAV Fused" study type). In these studies, BAV +data and Audience Origin data are fused together. -Formats 3 and 4 can also be fetched directly from the API for a given audience and study. See +You can also get formats 3 and 4 directly from the API for a given audience and study. See [Fetching respondents from the API](#fetching-respondents-from-the-api). ## Access control -As part of the integration you may control which users are allowed to export audiences to your application. This can -either be done by allowing on an operating company level, or on a user-by-user basis. We can also provide you with -a method of programmatically sharing with us a list of users are allowed to export audiences to your application based -on their e-mail address. +As part of the integration, you can control which users can export audiences to your application. You can give +access at the operating company level or to each user separately. We can also give you a method to send us a list of +these users programmatically. This list identifies the users by their e-mail address. ## Getting started -To get started with the Audience Export Integration you'll want to become familiar with: +Before you start with the Audience Export Integration, learn about: -- The different type of supported formats for the audience export. +- The different types of supported formats for the audience export. - The [Audiences API](audiences.md) and how to use it to read audiences, and [Managing audiences](managing-audiences.md) for how to create and manage them. - The [Webhooks](../webhooks.md) and how to listen to audience export events. -As you start thinking about how to use the Audience Export Integration, -please [reach out to us](mailto:support@bernskiold.com) so that we can start planning the integration activities -that need to happen on The Fount side to make your application visible as an export destination. +When you start to plan how to use the Audience Export Integration, [contact us](mailto:support@bernskiold.com). We can +then plan the integration tasks on The Fount side that make your application visible as an export destination. -We want to make sure that the integration is as smooth as possible for you and your users. +We want to make the integration as smooth as possible for you and your users. ## Export Types ### BAV Respondent IDs -The BAV Respondent ID is a unique identifier for each respondent in an audience. This ID is used to link the -respondent to each of the respondent-level data points. The ID is a V4 UUID and is unique across all studies. +The BAV Respondent ID is a unique identifier for each respondent in an audience. This ID links the respondent to each +of the respondent-level data points. The ID is a V4 UUID and is unique across all studies. :::warning Specific approval required -This export option is only available after approval from BAV. +This export option is available only after approval from BAV. ::: #### Schema -When your application receives the webhook event for an audience export the payload will be a JSON object with the -following schema. This is a slimmed-down version of the full audience schema. For more details about each field, please -see the [Audience API schema](audiences.md). +When your application receives the webhook event for an audience export, the payload is a JSON object with the +schema below. This schema is a smaller version of the full audience schema. For more details about each field, see +the [Audience API schema](audiences.md). ```json { @@ -118,18 +116,18 @@ see the [Audience API schema](audiences.md). ### Audience Origin Respondent IDs -The Audience Origin Respondent ID (AO ID) is a unique identifier for each respondent in an audience. This ID is used to link the respondent to the data in the data warehouse. IDs take slightly different forms depending on the study but are most -recently v4 UUIDs. +The Audience Origin Respondent ID (AO ID) is a unique identifier for each respondent in an audience. This ID links the respondent to the data in the data warehouse. The form of the IDs is slightly different for each +study, but the most recent IDs are v4 UUIDs. :::warning Specific approval required -This export option is only available after approval from Choreograph. +This export option is available only after approval from Choreograph. ::: #### Schema -When your application receives the webhook event for an audience export the payload will be a JSON object with the -following schema. This is a slimmed-down version of the full audience schema. For more details about each field, please -see the [Audience API schema](audiences.md). +When your application receives the webhook event for an audience export, the payload is a JSON object with the +schema below. This schema is a smaller version of the full audience schema. For more details about each field, see +the [Audience API schema](audiences.md). ```json { @@ -164,17 +162,17 @@ see the [Audience API schema](audiences.md). ### Audience Origin Progressive Numbers -The Audience Origin progressive numbers is an alternative ID used primarily by the GroupM Italy Audience Creator. +The Audience Origin progressive number is an alternative ID. The GroupM Italy Audience Creator is its primary user. :::warning Specific approval required -This export option is only available after approval from Choreograph. +This export option is available only after approval from Choreograph. ::: #### Schema -When your application receives the webhook event for an audience export the payload will be a JSON object with the -following schema. This is a slimmed-down version of the full audience schema. For more details about each field, please -see the [Audience API schema](audiences.md). +When your application receives the webhook event for an audience export, the payload is a JSON object with the +schema below. This schema is a smaller version of the full audience schema. For more details about each field, see +the [Audience API schema](audiences.md). ```json { @@ -211,8 +209,8 @@ see the [Audience API schema](audiences.md). ## Fetching respondents from the API -In addition to the webhook-based export, the Audience Origin respondent IDs and progressive numbers for an audience can -be fetched directly from the API, one study at a time. +You can also get the Audience Origin respondent IDs and progressive numbers for an audience directly from the API. +Get them for one study at a time. ### Audience Origin Respondent IDs @@ -220,8 +218,8 @@ be fetched directly from the API, one study at a time. GET /api/v2/audiences/{audienceId}/respondents/ao-ids/{studyId} ``` -Returns the Audience Origin IDs of the respondents in the audience for the given study. Respondents without an Audience -Origin ID are left out. +Returns the Audience Origin IDs of the respondents in the audience for the given study. The response does not include +respondents without an Audience Origin ID. ### Audience Origin Progressive Numbers @@ -229,8 +227,8 @@ Origin ID are left out. GET /api/v2/audiences/{audienceId}/respondents/ao-progressive-numbers/{studyId} ``` -Returns the Audience Origin progressive numbers of the respondents in the audience for the given study. Respondents -without a progressive number are left out. +Returns the Audience Origin progressive numbers of the respondents in the audience for the given study. The response +does not include respondents without a progressive number. ### Requirements @@ -239,10 +237,10 @@ Both endpoints require: - A token with the `bav:audience-origin-data` scope. - Access to both the audience and the study. - The user's permission to export Audience Origin IDs (`ao-ids`) or Audience Origin progressive numbers - (`ao-progressive-numbers`) respectively. This permission requires specific approval. + (`ao-progressive-numbers`), for the related endpoint. This permission requires specific approval. -A `404` is returned if the audience or study does not exist, and a `403` if you are not allowed to access them or to -export. +If the audience or study does not exist, the API returns a `404`. If you do not have permission to access them or to +export, the API returns a `403`. ### Response diff --git a/docs/audiences/managing-audiences.md b/docs/audiences/managing-audiences.md index 1db50f3..788343e 100644 --- a/docs/audiences/managing-audiences.md +++ b/docs/audiences/managing-audiences.md @@ -4,12 +4,12 @@ sidebar_label: Managing Audiences # Managing Audiences -In addition to reading [audiences](audiences.md), you may create your own audiences through the API, define who is -part of them and deploy them so that their data becomes available. +You can read [audiences](audiences.md), and you can also create your own audiences through the API. You can define who +is part of them. Then you deploy them to make their data available. ## How audiences are built -An audience is made up of a few layers: +An audience has these layers: - **Audience.** The audience itself with its name, description and visibility. - **Definitions.** An audience has one or more definitions. Each definition reads from a dataset (`bav` or @@ -18,31 +18,31 @@ An audience is made up of a few layers: - **Segments.** Each definition contains segments. A segment is a group of conditions that a respondent has to meet. The `within_segment_operator` decides how the conditions inside the segment combine (`AND` requires all of them, `OR` requires any of them). The `between_segments_operator` decides how the segment combines with the segment before it. - Segments are combined in their `sort_order`. + The API combines segments in their `sort_order`. - **Segment metrics.** Each segment contains metrics. A segment metric points to an [Audience Origin metric](../audience-origin/metrics.md), a [BAV brand measure](../measures/brand-measures.md) or a [BAV question](../measures/bav-questions.md) and the values a respondent must have given. -A new audience has no data. Once the definition is in place, you [deploy](#deploy-an-audience) the audience. The data -is built in the background and shows up in the data endpoints shortly after. Whenever you change the definition of an -audience, you need to deploy it again for the change to show in its data. +A new audience has no data. When the definition is complete, [deploy](#deploy-an-audience) the audience. The API builds +the data in the background, and the data shows in the data endpoints a short time after. If you change the definition +of an audience, deploy it again to show the change in its data. -You can see whether an audience needs to be deployed again by comparing `definitions_updated_at` with `deployed_at` on -the [audience](audiences.md). If `definitions_updated_at` is later, the audience has changed since it was last deployed. +To see if an audience needs a new deployment, compare `definitions_updated_at` with `deployed_at` on +the [audience](audiences.md). If `definitions_updated_at` is later, the audience changed after the last deployment. ## Access -Reading audiences, segments and segment metrics uses the `bav:shared-resources` scope like the rest of -the [Audiences](audiences.md) endpoints. +To read audiences, segments and segment metrics, you need the `bav:shared-resources` scope, the same as for the other +[Audiences](audiences.md) endpoints. -Creating, updating, deleting and deploying audiences requires the `bav:audiences:write` scope (shown as **Build -Audiences** when you create your API key). Your user also needs the permission to build audiences in The Fount. +To create, update, delete and deploy audiences, you need the `bav:audiences:write` scope. This scope shows as **Build +Audiences** when you create your API key. Your user also needs the permission to build audiences in The Fount. -In addition to the scope, regular audience permissions apply: +The usual audience permissions also apply: -- You may only update an audience that you own, that has been shared with you with edit rights, or if you have access - to manage all audiences. -- You may only delete audiences that you own. +- You can update only the audiences that you own or that are shared with you with edit rights. If you have access to + manage all audiences, you can update all audiences. +- You can delete only the audiences that you own. ## Create an audience @@ -52,8 +52,8 @@ To create an audience, send a `POST` request to the audiences endpoint: POST /api/v2/audiences ``` -You may create an empty audience with just a name, or create the whole audience with its definitions, segments and -metrics in one call. Definitions can only be created as part of this request. +You can create an empty audience with only a name. You can also create the full audience with its definitions, +segments and metrics in one call. You can create definitions only in this request. ```json { @@ -88,8 +88,8 @@ metrics in one call. Definitions can only be created as part of this request. } ``` -The response has the status code `201` and contains the created [audience](audiences.md), with its definitions, -segments and metrics included. +The response has the status code `201` and contains the created [audience](audiences.md). The response includes the +definitions, segments and metrics of the audience. ### Request body @@ -97,11 +97,11 @@ segments and metrics included. |---------------|---------|:--------:|---------------------------------------------------------------------------------------------------------------------| | `name` | string | :x: | The name of the audience. Maximum 255 characters. | | `description` | string | :x: | A description of the audience. | -| `is_active` | boolean | :x: | Whether the audience should be active. | -| `is_public` | boolean | :x: | Whether the audience is available to all users (true) or just you and the users you share it with (false). | +| `is_active` | boolean | :x: | Whether the audience is active. | +| `is_public` | boolean | :x: | Whether the audience is available to all users (true) or only to you and the users you share it with (false). | | `group_id` | integer | :x: | The ID of the [audience group](audience-groups.md) to put the audience in. | -| `user_id` | integer | :x: | The ID of the user who owns the audience. Only your own user ID is accepted. If omitted, you become the owner. | -| `definitions` | array | :x: | The audience's definitions. See below. Only used when creating an audience. | +| `user_id` | integer | :x: | The ID of the user who owns the audience. The API accepts only your own user ID. If you do not send it, you become the owner. | +| `definitions` | array | :x: | The definitions of the audience. See below. Used only when you create an audience. | Each definition in `definitions` accepts: @@ -111,21 +111,21 @@ Each definition in `definitions` accepts: | `base_study_id` | integer | :white_check_mark: | The ID of the [study](../studies/studies.md) whose questions the definition uses. | | `definitionable_type` | string | :x: | What the definition is limited to: `country` or `study`. Leave empty for a definition that applies to all of the audience's data. | | `definitionable_id` | integer | :x: | The ID of the country or study the definition is limited to. | -| `segments` | array | :x: | The segments in the definition. Each segment accepts the same fields as when [creating a segment](#create-a-segment), apart from `definition_id`. | +| `segments` | array | :x: | The segments in the definition. Each segment accepts the same fields as when you [create a segment](#create-a-segment), except `definition_id`. | ### Validation -Validation errors are returned with the status code `422` and follow the -standard [error format](../errors.md). In particular: +The API returns validation errors with the status code `422`. The errors use the +standard [error format](../errors.md). The validation rules include: - `definitions.*.dataset` and `definitions.*.base_study_id` are required for each definition. - `within_segment_operator` and `between_segments_operator` must be `AND` or `OR`. - `metric_type` and `metric_id` are required for each segment metric. -- `brands` may not be set on an Audience Origin metric. +- You cannot set `brands` on an Audience Origin metric. ## Update an audience -You may update an audience's name, description, visibility, group or owner with a `PUT` or `PATCH` request: +To update the name, description, visibility, group or owner of an audience, send a `PUT` or `PATCH` request: ```http request PUT /api/v2/audiences/123 @@ -133,13 +133,13 @@ PUT /api/v2/audiences/123 Where `123` is the system ID of the audience. -The request accepts the same top-level fields as when creating an audience (`name`, `description`, `is_active`, -`is_public`, `group_id` and `user_id`). Only the fields you send are changed. The definitions of the audience are not -changed by this endpoint. Use the [segment](#segments) and [segment metric](#segment-metrics) endpoints to change who is -part of the audience. +The request accepts the same top-level fields as the create request (`name`, `description`, `is_active`, `is_public`, +`group_id` and `user_id`). The API changes only the fields that you send. This endpoint does not change the definitions +of the audience. To change who is part of the audience, use the [segment](#segments) and +[segment metric](#segment-metrics) endpoints. -The response contains the updated [audience](audiences.md), with its definitions, segments, metrics, user and group -included. +The response contains the updated [audience](audiences.md). The response includes the definitions, segments, metrics, +user and group of the audience. ## Delete an audience @@ -155,8 +155,8 @@ The response contains the [audience](audiences.md) that was deleted. ## Segments -Segments live inside one of the audience's definitions. To find the definitions of an audience and their IDs, get the -audience with the `definitions` include: +Each segment is in one of the definitions of the audience. To find the definitions of an audience and their IDs, get +the audience with the `definitions` include: ```http request GET /api/v2/audiences/123?include=definitions.segments.metrics @@ -182,8 +182,8 @@ Where `123` is the system ID of the audience and `456` is the system ID of the s ### Create a segment -To add a segment to one of the audience's definitions, send a `POST` request. You may create the segment's metrics in -the same call. +To add a segment to one of the audience's definitions, send a `POST` request. You can create the metrics of the segment +in the same call. ```http request POST /api/v2/audiences/123/segments @@ -209,12 +209,12 @@ POST /api/v2/audiences/123/segments | Key | Type | Required | Description | |-----------------------------|---------|:----------------------------------:|----------------------------------------------------------------------------------------------------------------| -| `definition_id` | integer | :white_check_mark: (when creating) | The ID of the definition the segment belongs to. It has to be a definition of the audience in the path. | -| `sort_order` | integer | :x: | The position of the segment within its definition. Segments are combined in this order. Minimum `0`. | +| `definition_id` | integer | :white_check_mark: (when creating) | The ID of the definition the segment belongs to. It must be a definition of the audience in the path. | +| `sort_order` | integer | :x: | The position of the segment in its definition. The API combines segments in this order. Minimum `0`. | | `name` | string | :x: | The name of the segment. Maximum 255 characters. | | `within_segment_operator` | string | :x: | How the metrics in this segment combine. `AND` requires all of them, `OR` requires any. | | `between_segments_operator` | string | :x: | How this segment combines with the one before it. `AND` or `OR`. | -| `metrics` | array | :x: | The metrics that make up the segment. Each accepts the same fields as when [creating a segment metric](#create-a-segment-metric). Only used when creating a segment. | +| `metrics` | array | :x: | The metrics in the segment. Each metric accepts the same fields as when you [create a segment metric](#create-a-segment-metric). Used only when you create a segment. | The response has the status code `201` and contains the created segment with its metrics. @@ -224,9 +224,9 @@ The response has the status code `201` and contains the created segment with its PUT /api/v2/audiences/123/segments/456 ``` -The request accepts the same fields as when creating a segment, except `metrics`. The segment's metrics are managed -through the [segment metric endpoints](#segment-metrics). You may move a segment to another definition of the same -audience by changing `definition_id`. +The request accepts the same fields as the create request, except `metrics`. To manage the metrics of the segment, use +the [segment metric endpoints](#segment-metrics). To move a segment to another definition of the same audience, change +`definition_id`. ### Delete a segment @@ -234,7 +234,7 @@ audience by changing `definition_id`. DELETE /api/v2/audiences/123/segments/456 ``` -Deleting a segment also deletes its metrics. The response has the status code `204` and no content. +When you delete a segment, the API also deletes its metrics. The response has the status code `204` and no content. ### Segment schema @@ -294,14 +294,14 @@ POST /api/v2/audiences/123/segments/456/metrics |---------------|---------|:------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `metric_type` | string | :white_check_mark: | The kind of metric. One of `audience-origins-metric` ([Audience Origin metric](../audience-origin/metrics.md)), `bav-study-measure` ([brand measure](../measures/brand-measures.md)) or `bav-study-question` ([BAV question](../measures/bav-questions.md)). | | `metric_id` | integer | :white_check_mark: | The ID of the metric, of the kind given in `metric_type`. | -| `operator` | string | :x: | How the values are compared. The operators accepted depend on the type of the metric. See [operators](#operators). Defaults to `eq`. | +| `operator` | string | :x: | How the API compares the values. The accepted operators depend on the type of the metric. See [operators](#operators). Defaults to `eq`. | | `brands` | array | Sometimes | The IDs of the [brands](../brands/brands.md) the metric applies to. Required for metrics that support a brand filter (see `supports_brands_filter` in the response). | -| `values` | array | :x: | The values a respondent must have given. Which values are valid depends on the metric. For Audience Origin metrics the values are validated against the metric's type and answer options. | +| `values` | array | :x: | The values a respondent must have given. The valid values depend on the metric. For Audience Origin metrics, the API validates the values against the type and answer options of the metric. | The response has the status code `201` and contains the created segment metric. :::caution Every metric needs values -An audience with a segment metric that has no values selected cannot be deployed. +You cannot deploy an audience if one of its segment metrics has no selected values. ::: ### Update a segment metric @@ -310,7 +310,7 @@ An audience with a segment metric that has no values selected cannot be deployed PUT /api/v2/audiences/123/segments/456/metrics/789 ``` -The request accepts the same fields as when creating a segment metric. +The request accepts the same fields as the create request. ### Delete a segment metric @@ -337,7 +337,7 @@ The operators you can use depend on the type of the metric: |--------------|---------|-----------------------------------------------------------------------------------------------------------------------------------| | `id` | integer | The system ID of the segment metric. | | `metric` | object | The metric. See below. | -| `operator` | object | How the values are compared. Contains `id` (for example `is`), `label`, `is_multiple_choice` and `mysql_operator`. | +| `operator` | object | How the API compares the values. Contains `id` (for example `is`), `label`, `is_multiple_choice` and `mysql_operator`. | | `brands` | array | The IDs of the brands the metric applies to, for metrics that support a brand filter. | | `values` | object | The values a respondent must have given. `raw` is the list of values and `formatted` is a list of objects with an `id` and `label`. | | `created_at` | string | A datetime string when this segment metric was first created. | @@ -353,18 +353,18 @@ The `metric` object contains: | `key` | string | The key of the metric. | | `dataset` | string | The acronym of the dataset the metric belongs to, for example `BAV` or `AO`. | | `default_value` | mixed | The default value for the metric. | -| `supports_brands_filter` | boolean | Whether the metric is asked per brand, and so needs `brands` to be set. | +| `supports_brands_filter` | boolean | Whether the survey asks the metric per brand. If it does, you must set `brands`. | | `group` | object | The group the metric belongs to, with an `id` and `label`. Null if the metric has no group. | | `variable` | string | The Audience Origin questionnaire variable. Only present for Audience Origin metrics. | ## Audience studies -To see which studies an audience has data in, including population projections, see +To see the studies that an audience has data in, with population projections, see [Get the studies for an audience](./audiences.md#get-the-studies-for-an-audience). ## Deploy an audience -Once your audience is defined, deploy it to build its data: +When your audience has a definition, deploy it to build its data: ```http request GET /api/v2/audiences/123/deploy @@ -372,8 +372,8 @@ GET /api/v2/audiences/123/deploy Where `123` is the system ID of the audience. -The audience is queued for deployment and the data is built in the background. It shows up in the data endpoints -shortly after the request returns. Deploy the audience again every time you change its definition. +The API puts the audience in a queue for deployment and builds the data in the background. The data shows in the data +endpoints a short time after the request returns. Each time you change the definition, deploy the audience again. A successful request returns: @@ -385,8 +385,8 @@ A successful request returns: } ``` -If the audience cannot be deployed, the endpoint returns the status code `422` with a message explaining why. This -happens when: +If the API cannot deploy the audience, the endpoint returns the status code `422` and a message that tells why. This +occurs when: - The audience has no definitions. - One or more segment metrics have no values selected. The message lists the names of these metrics. diff --git a/docs/best-countries/country-data.md b/docs/best-countries/country-data.md index b4a474b..4d79a1a 100644 --- a/docs/best-countries/country-data.md +++ b/docs/best-countries/country-data.md @@ -5,34 +5,34 @@ The country data API contains details about how people perceive countries across - Raw/Respondent Level data. - Calculated data. -For building on top of Best Countries, you typically want the calculated data as the respondent level data is put through a series of processing pipelines to arrive at the scores and ranks of Best Countries. We do not recommend that you calculate this yourself. +To build on top of Best Countries, you usually need the calculated data. A series of processing pipelines changes the respondent-level data into the scores and ranks of Best Countries. We do not recommend that you calculate this yourself. Country data has two types of data: - **Attributes. (`attributes`)** The 74 imagery/perception attributes that respondents answer in the Best Countries survey. -- **Factors. (`factors`)** The 10 factors that contribute to GDP growth and is made up by a selection of the attributes. Included in the factors is the overall score that is a weighted average of all factors. +- **Factors. (`factors`)** The 10 factors that contribute to GDP growth. The factors are made from a selection of the attributes. The factors also include the overall score, which is a weighted average of all factors. Country data has two types of scores: -- **Scores. (`scores`)** A normalized 100-point score where 100 is best and 0 is worst, scaled across the countries and calculated through a pipeline based on the responses. -- **Ranks. (`ranks`)** The 100-point score turned into a sorted simple rank against the other countries, where 1 is the best. +- **Scores. (`scores`)** A normalized 100-point score where 100 is best and 0 is worst. The score is scaled across the countries. A pipeline calculates the score from the responses. +- **Ranks. (`ranks`)** The 100-point score, changed into a simple sorted rank against the other countries, where 1 is the best. Any other data type or score type returns a `400 Bad Request` response. ## Creating a query -The endpoint HTTP query accepts dynamic parameters for the year, score type and data type as described above. In a generic case, the query looks like this: +The endpoint HTTP query accepts dynamic parameters for the year, score type and data type, as described above. The general form of the query is: ```http GET /api/v2/best-countries/countries/{year}/{dataType}/{scoreType} ``` -Where `{year}` is either the system ID of the year or the calendar year (e.g. `2024`), `{dataType}` is `attributes` or -`factors` and `{scoreType}` is `scores` or `ranks`. A `404` is returned if the year has no Best Countries data. +Where `{year}` is either the system ID of the year or the calendar year (for example `2024`), `{dataType}` is `attributes` or +`factors` and `{scoreType}` is `scores` or `ranks`. If the year has no Best Countries data, the endpoint returns a `404`. This endpoint requires a token with the `bav:best-countries-data` scope. -For example, getting the factor ranks for 2024 would look like this: +For example, to get the factor ranks for 2024, send this request: ```http GET /api/v2/best-countries/countries/2024/factors/ranks @@ -40,24 +40,24 @@ GET /api/v2/best-countries/countries/2024/factors/ranks ## Schema -The API response for the country data endpoint will give you an array of datapoint objects in a `data` key. The response is not paginated. Each object is a one-level object that contains a few metadata fields and a series of metrics. The meta fields are: +The response of the country data endpoint gives you an array of datapoint objects in a `data` key. The response is not paginated. Each object is a one-level object with some metadata fields and a series of metrics. The metadata fields are: - `country`. The name of the country the datapoint relates to. - `country_id`. The system ID of the country. - `country_code`. The ISO 3166-1 alpha-2 two-letter country code. - `year_id`. The system ID of the year. -The metric fields are made up by the metric or factor key and its corresponding value. +Each metric field contains the metric or factor key and its related value. ## Filters -For convenience, a set of filters allow you to further refine the data: +For convenience, you can use a set of filters to refine the data more: - `country_codes`. A comma-separated list of two-letter ISO country codes to include data from. - `countries`. A comma-separated list of country system IDs to include data from. -When neither filter is given, every country is returned. Unlike most other endpoints, the filters are applied as plain -query parameters (not inside `filter[...]`) like this: +If you do not give a filter, the endpoint returns every country. Unlike most other endpoints, you send the filters as +plain query parameters (not inside `filter[...]`), as in this example: ```http GET /api/v2/best-countries/countries/2024/factors/ranks?country_codes=US @@ -65,4 +65,4 @@ GET /api/v2/best-countries/countries/2024/factors/ranks?country_codes=US ## Sorting -By default the data will be sorted by the country name. All fields returned by the endpoint are [sortable](../customizing/filters#sorting-results) using the `sort` query parameter, prefixed with `-` for descending order (e.g. `sort=-total`). Only one sort column is supported. +By default, the endpoint sorts the data by the country name. You can [sort](../customizing/filters#sorting-results) on all fields that the endpoint returns. Use the `sort` query parameter. For descending order, put `-` before the field name (for example `sort=-total`). You can sort on only one column. diff --git a/docs/best-countries/factors.md b/docs/best-countries/factors.md index e989895..d2fe78e 100644 --- a/docs/best-countries/factors.md +++ b/docs/best-countries/factors.md @@ -6,11 +6,11 @@ sidebar_label: Factors ## What are best countries factors? -In Best Countries, the individual [metrics](metrics.md) (attributes) that countries are surveyed on are aggregated into -a smaller number of broader factors, such as Adventure or Entrepreneurship. The factors are weighted together to -calculate the overall Best Countries ranking, which is returned as `total` in the factor data. +Best Countries surveys countries on individual [metrics](metrics.md) (attributes). Best Countries aggregates these +metrics into a smaller number of broader factors, such as Adventure or Entrepreneurship. The weighted factors together +give the overall Best Countries ranking. The factor data returns this ranking as `total`. -The factors endpoint gives you the list of factors and which metrics each factor is built from. To get the scores and +The factors endpoint gives you the list of factors and the metrics that each factor uses. To get the scores and ranks for each country on the factors, use the [country data](country-data.md) endpoint with the `factors` data type, or the [country factors model](models.md#country-factors). @@ -18,7 +18,7 @@ This endpoint requires the **Best Countries Data** (`bav:best-countries-data`) s ## List all best countries factors -To list all of the best countries factors and browse them via the API, use the list endpoint: +To list all of the best countries factors and browse them through the API, use the list endpoint: ```http request GET /api/v2/best-countries-factors @@ -26,7 +26,7 @@ GET /api/v2/best-countries-factors ## Get a best countries factor -You may also directly retrieve a best countries factor's details if you already have its system ID. +If you already have the system ID of a best countries factor, you can also get its details directly. ```http request GET /api/v2/best-countries-factors/123 @@ -38,28 +38,28 @@ Where `123` is the system ID of the factor. ### Full response schema -The factor endpoint returns every column of the factor. The `name` and `description` are translatable and are returned -as an object keyed by locale, for example `{"en": "Adventure"}`. +The factor endpoint returns every column of the factor. The `name` and `description` are translatable. The endpoint +returns them as an object keyed by locale, for example `{"en": "Adventure"}`. | Key | Type | Description | |---------------|---------|---------------------------------------------------------------------------------------------------------------------| | `id` | integer | The system ID. | | `name` | object | The name of the factor, keyed by locale. | | `key` | string | The machine-readable key of the factor. The [country data](country-data.md) endpoint names its factor fields after it. | -| `description` | object | A description of the factor, keyed by locale. May be `null`. | +| `description` | object | A description of the factor, keyed by locale. Can be `null`. | | `created_at` | string | A datetime string when this factor was first created. | | `updated_at` | string | A datetime string when this factor was last updated. | ## Filters & Sorting -This endpoint does not support any filters or sorting. As there are only a handful of factors, we recommend that you -retrieve the full list and filter it in your application. +This endpoint does not support filters or sorting. There are only a small number of factors. We recommend that you get +the full list and filter it in your application. ## Relationships & includes -By default, relationships are not included. See the [includes section](../customizing/includes) for more information +By default, the response does not include relationships. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: -- `metrics` - The [best countries metrics](metrics.md) that the factor is built from. The metrics are returned with all - of their stored columns, along with a `pivot` object linking the metric to the factor. For the documented metric +- `metrics` - The [best countries metrics](metrics.md) that the factor uses. The API returns the metrics with all of + their stored columns and a `pivot` object that links the metric to the factor. For the documented metric schema, use the [best countries metrics](metrics.md) endpoint. diff --git a/docs/best-countries/index.md b/docs/best-countries/index.md index a485307..2aca162 100644 --- a/docs/best-countries/index.md +++ b/docs/best-countries/index.md @@ -4,11 +4,11 @@ sidebar_label: Overview # Best Countries -Best Countries is WPP's annual study of countries. Each country is surveyed on a range of attributes which are -aggregated into a smaller number of broader factors. +Best Countries is WPP's annual study of countries. The study surveys each country on a range of attributes. The study +then aggregates these attributes into a smaller number of broader factors. The dataset has several types of scores: - Raw Country Data (the responses by respondent) - Calculated Country Data (the scores and ranks for each country) -- Origin Index (scores and ranks on respondents likelihood to purchase products made in a country) \ No newline at end of file +- Origin Index (scores and ranks on respondents' likelihood to purchase products made in a country) \ No newline at end of file diff --git a/docs/best-countries/metric-groups.md b/docs/best-countries/metric-groups.md index da87c0b..3437792 100644 --- a/docs/best-countries/metric-groups.md +++ b/docs/best-countries/metric-groups.md @@ -6,15 +6,15 @@ sidebar_label: Metric Groups ## What are best countries metric groups? -The [best countries metrics](metrics.md) are divided into groups for easier browsing, such as imagery, visiting, -doing business, product origin and education. The groups also make up the basis for the +The [best countries metrics](metrics.md) are divided into groups to make them easier to browse, such as imagery, visiting, +doing business, product origin and education. The groups are also the basis for the Best Countries [models](models.md). For example, the country imagery model returns the metrics in the `imagery` group. This endpoint requires the **Best Countries Data** (`bav:best-countries-data`) scope. ## List all best countries metric groups -To list all of the best countries metric groups and browse them via the API, use the list endpoint: +To list all of the best countries metric groups and browse them through the API, use the list endpoint: ```http request GET /api/v2/best-countries-metric-groups @@ -22,7 +22,7 @@ GET /api/v2/best-countries-metric-groups ## Get a best countries metric group -You may also directly retrieve a best countries metric group's details if you already have its system ID. +If you already have the system ID of a best countries metric group, you can also get its details directly. ```http request GET /api/v2/best-countries-metric-groups/123 @@ -34,8 +34,8 @@ Where `123` is the system ID of the metric group. ### Full response schema -The metric group endpoint returns every column of the group. The `name` and `description` are translatable and are -returned as an object keyed by locale, for example `{"en": "Imagery"}`. +The metric group endpoint returns every column of the group. The `name` and `description` are translatable. The +endpoint returns them as an object keyed by locale, for example `{"en": "Imagery"}`. | Key | Type | Description | |---------------|---------|------------------------------------------------------------------------------------------------| @@ -43,7 +43,7 @@ returned as an object keyed by locale, for example `{"en": "Imagery"}`. | `is_active` | integer | Whether the group is active (`1`) or not (`0`). | | `name` | object | The name of the group, keyed by locale. | | `key` | string | The machine-readable key of the group, for example `imagery` or `doing-business`. | -| `description` | object | A description of the group, keyed by locale. May be `null`. | +| `description` | object | A description of the group, keyed by locale. Can be `null`. | | `created_at` | string | A datetime string when this group was first created. | | `updated_at` | string | A datetime string when this group was last updated. | @@ -57,13 +57,13 @@ The groups used by the Best Countries [models](models.md) are: ## Filters & Sorting -This endpoint does not support any filters or sorting. As there are only a handful of groups, we recommend that you -retrieve the full list and filter it in your application. +This endpoint does not support filters or sorting. There are only a small number of groups. We recommend that you get +the full list and filter it in your application. ## Relationships & includes -By default, relationships are not included. See the [includes section](../customizing/includes) for more information +By default, the response does not include relationships. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: -- `metrics` - The [best countries metrics](metrics.md) in the group. The metrics are returned with all of their stored +- `metrics` - The [best countries metrics](metrics.md) in the group. The API returns the metrics with all of their stored columns. For the documented metric schema, use the [best countries metrics](metrics.md) endpoint. diff --git a/docs/best-countries/metrics.md b/docs/best-countries/metrics.md index 18c6ea3..482c80c 100644 --- a/docs/best-countries/metrics.md +++ b/docs/best-countries/metrics.md @@ -6,12 +6,12 @@ sidebar_label: Metrics ## What are best countries metrics? -When BAV studies a country in Best Countries it does so on a variety of metrics. These metrics are divided -into [groups](metric-groups.md) for easier browsing. +When BAV studies a country in Best Countries, it uses different metrics. These metrics are divided +into [groups](metric-groups.md) to make them easier to browse. ## List all best countries metrics -To list all of the best countries metrics and browse them via the API, use the list endpoint: +To list all of the best countries metrics and browse them through the API, use the list endpoint: ```http request GET /api/v2/best-countries-metrics @@ -19,7 +19,7 @@ GET /api/v2/best-countries-metrics ## Get a best countries metric -You may also directly retrieve a best countries metric's details if you already have its system ID. +If you already have the system ID of a best countries metric, you can also get its details directly. ```http request GET /api/v2/best-countries-metrics/123 diff --git a/docs/best-countries/models.md b/docs/best-countries/models.md index 9c2a029..f9c0325 100644 --- a/docs/best-countries/models.md +++ b/docs/best-countries/models.md @@ -25,14 +25,14 @@ All model endpoints require the **Best Countries Data** (`bav:best-countries-dat ## Parameters -The parameters are sent as a JSON body. List parameters are arrays, and each value can be either an ID or a name. +Send the parameters as a JSON body. List parameters are arrays, and each value can be either an ID or a name. ### Country models | Key | Required? | Type | Description | |-------------|:----------------------------:|--------|------------------------------------------------------------------------------------------------------------------------------| | `years` | :white_check_mark: | array | The [years](../metadata/years.md) to read, as year IDs or calendar years. | -| `countries` | :x: (defaults to all) | array | The [countries](../metadata/countries.md) to read, by country ID, two- or three-letter ISO code, or name. Returns every country measured in the year when left out. | +| `countries` | :x: (defaults to all) | array | The [countries](../metadata/countries.md) to read, by country ID, two- or three-letter ISO code, or name. If you do not send it, the endpoint returns every country measured in the year. | | `audiences` | :x: (defaults to All Adults) | array | The [audiences](../audiences/audiences.md) to read, by audience ID or name. | | `scoreType` | :x: (depends on the model) | string | The score type. See [score types](#score-types). | | `format` | :x: (defaults to `json`) | string | The response format: `json`, `llm` or `mcp`. See [response formats](../brand-data/data-models.md#response-formats). | @@ -44,7 +44,7 @@ The city models take the same parameters as the country models, but with `cities | Key | Required? | Type | Description | |-------------|:----------------------------:|--------|---------------------------------------------------------------------------------------------------------------------| | `years` | :white_check_mark: | array | The [years](../metadata/years.md) to read, as year IDs or calendar years. | -| `cities` | :x: (defaults to all) | array | The [cities](../metadata/cities.md) to read, by city ID or name. Returns every city measured in the year when left out. | +| `cities` | :x: (defaults to all) | array | The [cities](../metadata/cities.md) to read, by city ID or name. If you do not send it, the endpoint returns every city measured in the year. | | `audiences` | :x: (defaults to All Adults) | array | The [audiences](../audiences/audiences.md) to read, by audience ID or name. | | `scoreType` | :x: (depends on the model) | string | The score type. See [score types](#score-types). | | `format` | :x: (defaults to `json`) | string | The response format: `json`, `llm` or `mcp`. See [response formats](../brand-data/data-models.md#response-formats). | @@ -57,7 +57,7 @@ The `scoreType` parameter accepts: - `percentage` - The percentage of respondents, for example those who would consider visiting. - `score` - A score from 0 to 100. -The default score type depends on the model and is listed in the [table above](#available-models). +The default score type depends on the model. The [table above](#available-models) shows the default for each model. ### Example @@ -87,7 +87,7 @@ contains: | `year_id` | integer | The system ID of the [year](../metadata/years.md). Only on the country models. | | `audience_id` | integer | The system ID of the [audience](../audiences/audiences.md). | | `audience` | string | The name of the audience. | -| _metric keys_ | number | One field per metric in the model, named after the [metric](metrics.md) or [factor](factors.md) `key`, holding the value for the requested score type. | +| _metric keys_ | number | One field per metric in the model, named after the [metric](metrics.md) or [factor](factors.md) `key`, with the value for the requested score type. | ```json [ @@ -103,7 +103,7 @@ contains: ] ``` -The values in the example are illustrative, and only some of the metrics are shown. +The values in the example are for illustration only. The example shows only some of the metrics. ## Country Imagery @@ -120,8 +120,8 @@ the `rank` score type by default. POST /api/v2/best-countries/countries/factors ``` -Each country's scores on the Best Countries [factors](factors.md), the weighted categories that the overall ranking is -calculated from. Returns one field per factor `key`, along with the overall `total`. Uses the `rank` score type by +Each country's scores on the Best Countries [factors](factors.md), the weighted categories that give the overall +ranking. Returns one field per factor `key` and the overall `total`. Uses the `rank` score type by default. ## Country Doing Business diff --git a/docs/best-countries/raw-data.md b/docs/best-countries/raw-data.md index 03b967f..f7b4b0d 100644 --- a/docs/best-countries/raw-data.md +++ b/docs/best-countries/raw-data.md @@ -1,12 +1,11 @@ # Raw Data -The raw data endpoint gives you the respondent-level Best Countries data for one year, with every stored answer and no -ranking or scoring applied. Each row is one respondent's answers about one country. +The raw data endpoint gives you the respondent-level Best Countries data for one year, with every stored answer. The +endpoint does not apply ranks or scores to the data. Each row is one respondent's answers about one country. :::tip Use the calculated data where you can -The respondent-level data is put through a series of processing pipelines to arrive at the Best Countries scores and -ranks. For building on top of Best Countries, you typically want the [country data](country-data.md) or -the [models](models.md) instead. We do not recommend that you calculate the scores yourself. +A series of processing pipelines changes the respondent-level data into the Best Countries scores and ranks. To build +on top of Best Countries, you usually need the [country data](country-data.md) or the [models](models.md) instead. We do not recommend that you calculate the scores yourself. ::: This endpoint requires the **Best Countries Data** (`bav:best-countries-data`) scope. @@ -23,7 +22,7 @@ Where `{year}` is either the system ID of the [year](../metadata/years.md) or th GET /api/v2/best-countries/countries/raw/2024 ``` -The endpoint returns a `404` if the year cannot be found or has no Best Countries data. +If the endpoint cannot find the year, or the year has no Best Countries data, the endpoint returns a `404`. :::note Cities and Origin Index The equivalent raw data endpoints for cities (`/api/v2/best-countries/cities/raw/{year}`) and the Origin Index @@ -40,16 +39,16 @@ The response is [paginated](../pagination.md). Each row contains: | `respondent_id` | integer | :white_check_mark: | :white_check_mark: | The respondent ID. Rows with the same respondent ID are one person's answers about different countries. | | `year` | object | :x: | :x: | The [year](../metadata/years.md) the answers were collected, with `id` and `year`. | | `country` | object | :x: | :x: | The [country](../metadata/countries.md) the answers are about, with `id`, `name`, `region`, `code`, `code_alpha3` and `code_numeric`. | -| _metric keys_ | number | :white_check_mark: | :white_check_mark: | One field per [best countries metric](metrics.md) asked about countries, holding the respondent's answer. | +| _metric keys_ | number | :white_check_mark: | :white_check_mark: | One field per [best countries metric](metrics.md) asked about countries, with the respondent's answer. | The metric fields are named after the metric `key`, for example `familiarity`, `friendly`, `safe`, `consider_visiting`, `consider_doing_business` or `has_top_universities`. ## Configurable fields -You may limit the response to specific fields with the `fields` parameter, passing a comma-separated list of field -names. Any column of the data can be used. When you limit the fields, include `id`, `year_id` and `country_id` in the -list to keep the record ID, the year and the country populated in the response. +To limit the response to specific fields, use the `fields` parameter with a comma-separated list of field names. You +can use any column of the data. When you limit the fields, include `id`, `year_id` and `country_id` in the list. These +fields keep the record ID, the year and the country populated in the response. ```http request GET /api/v2/best-countries/countries/raw/2024?fields=id,year_id,country_id,respondent_id,familiarity @@ -57,8 +56,8 @@ GET /api/v2/best-countries/countries/raw/2024?fields=id,year_id,country_id,respo ## Sorting -All data fields can be [sorted](../customizing/filters#sorting-results) on. In addition, you can sort by the country -using `country.name`, `country.code`, `country.code_alpha3` and `country.code_numeric`. +You can [sort](../customizing/filters#sorting-results) on all data fields. You can also sort by the country +with `country.name`, `country.code`, `country.code_alpha3` and `country.code_numeric`. ```http request GET /api/v2/best-countries/countries/raw/2024?sort=country.code,-familiarity diff --git a/docs/brands/brand-tags.md b/docs/brands/brand-tags.md index bcf2f93..77b0e83 100644 --- a/docs/brands/brand-tags.md +++ b/docs/brands/brand-tags.md @@ -23,17 +23,17 @@ GET /api/v2/brands?filter[tags]=luxury ## List all brand tags -To list all of the brand tags and browse them via the API, use the list endpoint: +To list all of the brand tags and browse them through the API, use the list endpoint: ```http request GET /api/v2/brand-tags ``` -The tags are sorted by category and name by default. +By default, the API sorts the tags by category and name. ## Get a brand tag -You may also directly retrieve a brand tag's details if you already have its system ID. +If you already have the system ID of a brand tag, you can also get its details directly. ```http request GET /api/v2/brand-tags/123 @@ -59,8 +59,8 @@ Where `123` is the system ID of the brand tag. ### Relationship Response Schema -The slim relationship schema is used when the brand tag is used as part of an include in another resource, such as -the `tags` include on [brands](brands.md). +The API uses the slim relationship schema when the brand tag is part of an include in another resource, such as the +`tags` include on [brands](brands.md). | Key | Type | Description | |-------------------|---------|--------------------------------------------------------------------------------------------------------| @@ -72,7 +72,7 @@ the `tags` include on [brands](brands.md). ## Relationships & includes -By default, relationships are not included. See +By default, the response does not include relationships. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: diff --git a/docs/brands/brand-variations.md b/docs/brands/brand-variations.md index 7fb6357..4abe66e 100644 --- a/docs/brands/brand-variations.md +++ b/docs/brands/brand-variations.md @@ -6,16 +6,16 @@ A [brand](brands.md) can be known under more than one name. Brand variations are A variation is either: - `equivalent` - Another name for the brand. -- `previously` - A name the brand was previously known as. +- `previously` - A name the brand had in the past. Each brand variation has a unique numeric `key`, which can be negative, and a short `code`. When a brand variation is -deprecated, it may point to the variation that replaced it. +deprecated, it can point to the variation that replaced it. This endpoint requires the `bav:brand-data` scope. ## List all brand variations -To list all of the brand variations and browse them via the API, use the list endpoint: +To list all of the brand variations and browse them through the API, use the list endpoint: ```http request GET /api/v2/brand-variations @@ -23,7 +23,7 @@ GET /api/v2/brand-variations ## Get a brand variation -You may also directly retrieve a brand variation's details if you already have its system ID. +If you already have the system ID of a brand variation, you can also get its details directly. ```http request GET /api/v2/brand-variations/123 @@ -53,8 +53,8 @@ Where `123` is the system ID of the brand variation. ### Relationship Response Schema -The slim relationship schema is used when the brand variation is used as part of an include in another resource, such -as the brandscape data. +The API uses the slim relationship schema when the brand variation is part of an include in another resource, such as +the brandscape data. | Key | Type | Description | |---------|---------|---------------------------------------------------------------------| @@ -66,18 +66,18 @@ as the brandscape data. ## Additional Filters -For convenience, we have a set of additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +For convenience, brand variations have a set of additional filters. These filters are not in +the [default filters](../customizing/filters.md) and are not columns. The additional filters are: -- `brands` - A comma-separated list of brand IDs. Only variations of these brands are returned. +- `brands` - A comma-separated list of brand IDs. The filter returns only the variations of these brands. - `keys` - A comma-separated list of brand variation keys. -- `studies` - A comma-separated list of study IDs. Only variations included in these studies are returned. -- `has_studies` - Set to `1` to only return variations that have been measured in at least one study, or `0` for - variations that have not. +- `studies` - A comma-separated list of study IDs. The filter returns only the variations that are in these studies. +- `has_studies` - Set to `1` to return only the variations that were measured in one or more studies. Set to `0` to + return only the variations that were not measured. ## Relationships & includes -By default, relationships are not included. See +By default, the response does not include relationships. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: @@ -88,6 +88,6 @@ are available: This endpoint supports searching by name. See the [searching section](../customizing/searching) for more details. -When searching, either with `search` or `filter[name]`, only these filters apply: `id`, `brand_id`, `type`, `code`, -`keys`, `studies`, `is_core`, `is_global`, `is_ranked`, `is_deprecated` and `has_studies`. Sorting is also limited to a -single column. +When you search with `search` or `filter[name]`, only these filters apply: `id`, `brand_id`, `type`, `code`, `keys`, +`studies`, `is_core`, `is_global`, `is_ranked`, `is_deprecated` and `has_studies`. You can also sort on only one +column. diff --git a/docs/brands/brands.md b/docs/brands/brands.md index 3986120..931c0b7 100644 --- a/docs/brands/brands.md +++ b/docs/brands/brands.md @@ -1,24 +1,24 @@ # Brands -You may use the Brands endpoint to retrieve details about one or more brands. +Use the Brands endpoint to get details about one or more brands. ## What are brands? -Brands are the core of BAV. They are the entities that are researched by BAV surveys and is connected to many other -resources. Brands differ from companies in that they are not necessarily a legal entity. Brands are owned by companies. +Brands are the core of BAV. BAV surveys research these entities, and brands connect to many other resources. Brands +differ from companies in that they are not necessarily a legal entity. Brands are owned by companies. Brands in BAV do not belong specifically to a [category resource](../studies/categories.md). Each brand is studied in a specific category in a specific [study](../studies/studies.md). However, for classification purposes each brand belongs to a [sector](../metadata/sectors.md) based on the studies it is in. -A brand has no scores of its own. Brand data always belongs to a brand in a study, so use these endpoints to find a -brand, then read its data from the [brandscape data](../brand-data/brandscape-data.md) endpoints. +A brand has no scores of its own. Brand data always belongs to a brand in a study. Use these endpoints to find a +brand. Then read its data from the [brandscape data](../brand-data/brandscape-data.md) endpoints. The brands endpoints are read-only. ## List all brands -To list all of the brands and browse them via the API, use the list endpoint: +To list all of the brands and browse them through the API, use the list endpoint: ```http request GET /api/v2/brands @@ -26,7 +26,7 @@ GET /api/v2/brands ## Get a brand -You may also directly retrieve a brand's details if you already have its system ID. +If you already have the system ID of a brand, you can also get its details directly. ```http request GET /api/v2/brands/123 @@ -48,7 +48,7 @@ Where `123` is the system ID of the brand. | `share_of_company` | float | :white_check_mark: | :white_check_mark: | :white_check_mark: | The percentage share that this brand makes up of the parent company's revenue. | | `is_core` | null | :x: | :x: | :x: | **Deprecated.** Always `null`. | | `is_studied_globally` | null | :x: | :x: | :x: | **Deprecated.** Always `null`. | -| `is_deprecated` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the brand is deprecated. A deprecated brand keeps its historical data and may point to a `replacement` brand. | +| `is_deprecated` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the brand is deprecated. A deprecated brand keeps its historical data and can point to a `replacement` brand. | | `signalai_id` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The brand's identifier in Signal AI. | | `parent_brand_id` | integer | :x: | :x: | :white_check_mark: | The ID of the parent brand in the brand hierarchy, or `null` if the brand has no parent. | | `website_url` | string | :white_check_mark: | :white_check_mark: | :x: | The brand's website address. | @@ -64,16 +64,16 @@ Where `123` is the system ID of the brand. :::caution Deprecated fields -`bav_brand_id`, `bav_id`, `is_core` and `is_studied_globally` are still returned for backwards compatibility, but are -always `null`. They can no longer be filtered or sorted on. Use `id` to identify brands. The `logo_url` field has been -removed. +The API still returns `bav_brand_id`, `bav_id`, `is_core` and `is_studied_globally` for backwards compatibility, but +they are always `null`. You cannot filter or sort on them. Use `id` to identify brands. The API no longer returns the +`logo_url` field. ::: ### Relationship Response Schema -The slim relationship schema is used when the brand is used as part of an include in another resource, and for the -`replacement`, `parent` and `children` includes. +The API uses the slim relationship schema when the brand is part of an include in another resource. The API also uses +it for the `replacement`, `parent` and `children` includes. | Key | Type | Description | |---------------|---------|----------------------------------------------------------------------------| @@ -84,59 +84,59 @@ The slim relationship schema is used when the brand is used as part of an includ ## Additional Filters -For convenience, we have a set of additional filters for brands that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +For convenience, brands have a set of additional filters. These filters are not in +the [default filters](../customizing/filters.md) and are not columns. The additional filters are: -- `years` - A comma-separated list of year IDs. This will filter the brands to only those that are studied in the - specified years. -- `year_numbers` - A comma-separated list of year numbers (e.g. `2024,2025`). This will filter the brands to only those +- `years` - A comma-separated list of year IDs. The filter returns only the brands that are studied in the specified + years. +- `year_numbers` - A comma-separated list of year numbers (for example `2024,2025`). The filter returns only the brands that are studied in the specified years. -- `categories` - A comma-separated list of category IDs. This will filter the brands to only those that are studied in - the specified categories. A brand can be in different categories in different studies. -- `sectors` - A comma-separated list of sector IDs. This will filter the brands to only those in the given sectors. -- `countries` - A comma-separated list of country IDs. This will filter the brands to only those that are studied in - the specified countries. -- `country_codes` - A comma-separated list of two-letter ISO country codes. This will filter the brands to only those - that are studied in the specified countries. -- `regions` - A comma-separated list of region IDs. This will filter the brands to only those that are studied in - the specified regions. -- `region_blocs` - A comma-separated list of region bloc IDs. This will filter the brands to only those that are - studied in countries belonging to the specified region blocs. -- `studies` - A comma-separated list of study IDs. This will filter the brands to only those that are included in the - specified studies. -- `companies` - A comma-separated list of [company](../company-data/companies.md) IDs. This will filter the brands to - only those owned by the specified companies. -- `tags` - A comma-separated list of brand tag IDs or keys (e.g. `luxury`). See `/api/v2/brand-tags` for the available - tags. -- `variations` - A comma-separated list of brand variation IDs. This will filter the brands to only those with the - specified variations. -- `has_studies` - Set to `1` to only include brands that have been included in any study at any point in time, or `0` - for brands that have never been studied. +- `categories` - A comma-separated list of category IDs. The filter returns only the brands that are studied in the + specified categories. A brand can be in different categories in different studies. +- `sectors` - A comma-separated list of sector IDs. The filter returns only the brands in the specified sectors. +- `countries` - A comma-separated list of country IDs. The filter returns only the brands that are studied in the + specified countries. +- `country_codes` - A comma-separated list of two-letter ISO country codes. The filter returns only the brands that are + studied in the specified countries. +- `regions` - A comma-separated list of region IDs. The filter returns only the brands that are studied in the + specified regions. +- `region_blocs` - A comma-separated list of region bloc IDs. The filter returns only the brands that are studied in + countries that belong to the specified region blocs. +- `studies` - A comma-separated list of study IDs. The filter returns only the brands that are in the specified + studies. +- `companies` - A comma-separated list of [company](../company-data/companies.md) IDs. The filter returns only the + brands that the specified companies own. +- `tags` - A comma-separated list of brand tag IDs or keys (for example `luxury`). See `/api/v2/brand-tags` for the + available tags. +- `variations` - A comma-separated list of brand variation IDs. The filter returns only the brands with the specified + variations. +- `has_studies` - Set to `1` to include only the brands that were in a study at any time. Set to `0` to include only + the brands that were never studied. ## Relationships & includes -By default, only the `replacement` relationship is included. See the [includes section](../customizing/includes.md) for +By default, the response includes only the `replacement` relationship. See the [includes section](../customizing/includes.md) for more information on how this works. The following relationships are available: - `company` - The [company](../company-data/companies.md) that owns the brand. - `sector` - The [sector](../metadata/sectors.md) that the brand belongs to. -- `studies` - A list of [BAV studies](../studies/studies.md) where this brand was included. Each study contains its - `id`, `name`, `year`, `country`, `period` and `data_available_at`, plus the `brand_name` and `category_id` the brand - was measured under in that study. -- `studies.category` - Accepted for compatibility. The study entries still only expose the `category_id`; look the - category up via the [categories endpoint](../studies/categories.md). +- `studies` - A list of the [BAV studies](../studies/studies.md) that included this brand. Each study contains its + `id`, `name`, `year`, `country`, `period` and `data_available_at`. Each study also contains the `brand_name` and + `category_id` that the study used to measure the brand. +- `studies.category` - The API accepts this include for compatibility. The study entries still show only the + `category_id`. To get the category, use the [categories endpoint](../studies/categories.md). - `countries` - The [countries](../metadata/countries.md) where the brand is present, with its local name and whether the country is its country of origin. - `variations` - The other names this brand is known by. - `replacement` - The brand that replaced this one, if it is deprecated. Always included. - `parent` - The parent brand in the brand hierarchy. - `children` - The child brands in the brand hierarchy. -- `tags` - The brand's tags. `is_ai_generated` shows whether a tag was assigned by AI rather than by hand. +- `tags` - The brand's tags. `is_ai_generated` shows if AI assigned the tag or a person assigned it by hand. ## Searching This endpoint supports searching. See the [searching section](../customizing/searching.md) for more details. -When searching (using `search` or `filter[name]`), only the `years`, `year_numbers`, `countries`, `country_codes`, +When you search (with `search` or `filter[name]`), only the `years`, `year_numbers`, `countries`, `country_codes`, `regions`, `region_blocs`, `studies`, `categories`, `sectors`, `companies`, `variations`, `tags`, `is_deprecated` -and `has_studies` filters apply, and sorting is limited to a single column. +and `has_studies` filters apply. You can also sort on only one column. diff --git a/docs/brands/collections.md b/docs/brands/collections.md index 13e8cc4..b339ed4 100644 --- a/docs/brands/collections.md +++ b/docs/brands/collections.md @@ -2,34 +2,34 @@ ## What are collections? -Collections are a way to group brands together. A collection can then be used for a variety of purposes to save time -when adding brands. Instead of searching for a number of brands every time a user can add the collection in one go. -Examples of useful collections are: +Collections let you group brands together. You can use a collection for different purposes to save time when you add +brands. A user can add the collection in one step, and does not have to search for each brand every time. Examples of +useful collections are: - All brands that are part of a company. - Client brands - Competitor brands -A collection may be public or private. A public collection is available to all users. A private collection is only +A collection can be public or private. A public collection is available to all users. A private collection is only available to the user who created it. -A collection can also be shared with any number of users. Through the API you only see your own collections, public +A collection can also be shared with any number of users. Through the API, you see only your own collections, public collections and collections shared with you. -Collection IDs can be used wherever an endpoint takes a `collections` filter or benchmark, for example in the +You can use collection IDs in all endpoints that take a `collections` filter or benchmark, for example in the [brand data tools](../brand-data/index.md). :::info Read-only -The collections endpoints are read-only. Although a `bav:collections:write` token scope exists, the REST API has no -endpoints for creating, updating or deleting collections, and `POST`, `PUT`/`PATCH` and `DELETE` requests to -`/api/v2/collections` return a `400 Bad Request` response. +The collections endpoints are read-only. A `bav:collections:write` token scope exists, but the REST API has no +endpoints to create, update or delete collections. `POST`, `PUT`/`PATCH` and `DELETE` requests to `/api/v2/collections` +return a `400 Bad Request` response. ::: ## List all collections -To list all of the collections and browse them via the API, use the list endpoint: +To list all of the collections and browse them through the API, use the list endpoint: ```http request GET /api/v2/collections @@ -37,7 +37,7 @@ GET /api/v2/collections ## Get a collection -You may also directly retrieve a collection's details if you already have its system ID. +If you already have the system ID of a collection, you can also get its details directly. ```http request GET /api/v2/collections/123 @@ -54,28 +54,28 @@ Where `123` is the system ID of the collection. | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | | `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The primary name of the collection. | | `collection_type` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The collection type: `1` public, `2` private or `3` report (deprecated). | -| `uuid` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The public unique identifier for the collection. Whenever a collection is shared outside of the system, or a direct link is required we use the UUID over the ID. | +| `uuid` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The public unique identifier for the collection. When a collection is shared outside the system, or needs a direct link, the system uses the UUID and not the ID. | | `url` | string | :x: | :x: | :x: | The URL to view the collection in The Fount. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this collection was first created. | | `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this collection was last updated. | ## Additional Filters -For convenience, we have a set of additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +For convenience, collections have a set of additional filters. These filters are not in +the [default filters](../customizing/filters.md) and are not columns. The additional filters are: -- `public` - Set to `1` to only return public collections. -- `shared_with_me` - Set to `1` to only return collections shared with the user. -- `mine` - Set to `1` to only return collections created by the user. +- `public` - Set to `1` to return only public collections. +- `shared_with_me` - Set to `1` to return only collections shared with the user. +- `mine` - Set to `1` to return only collections that the user created. Any value turns these filters on. ## Relationships & includes -By default, relationships are not included. See the [includes section](../customizing/includes) for more information +By default, the response does not include relationships. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: -- `brands` - The [brands](brands.md) in the collection, using the brand relationship schema (`id`, `name`, `sector` +- `brands` - The [brands](brands.md) in the collection, with the brand relationship schema (`id`, `name`, `sector` and `signalai_id`). ## Searching From 4646b60280fd68849abd1b9e81f7367d431e5ec2 Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sun, 25 Oct 2026 10:33:34 +0100 Subject: [PATCH 17/23] Rewrite company, market share, measures, metadata, metrics and studies docs in Simplified Technical English Co-Authored-By: Claude Opus 5.5 --- docs/company-data/companies.md | 16 +++--- docs/company-data/stock-prices.md | 46 +++++++++-------- docs/market-share/brand-shares.md | 46 ++++++++--------- docs/market-share/catalog.md | 30 +++++------ docs/market-share/company-shares.md | 36 +++++++------- docs/market-share/index.md | 50 +++++++++---------- docs/measures/bav-question-groups.md | 14 +++--- docs/measures/bav-questions.md | 22 ++++---- docs/measures/brand-measure-groups.md | 10 ++-- docs/measures/brand-measures.md | 21 ++++---- docs/measures/index.md | 6 +-- docs/measures/study-catalog.md | 16 +++--- docs/metadata/cities.md | 12 ++--- docs/metadata/countries.md | 18 +++---- docs/metadata/country-indicators.md | 10 ++-- docs/metadata/gics-sectors.md | 10 ++-- docs/metadata/operating-companies.md | 14 +++--- docs/metadata/regions.md | 10 ++-- docs/metadata/sectors.md | 14 +++--- docs/metadata/stock-exchanges.md | 12 ++--- docs/metadata/tools.md | 12 ++--- docs/metadata/years.md | 8 +-- docs/metrics/metric-groups.md | 12 ++--- docs/metrics/metrics.md | 16 +++--- docs/studies/categories.md | 19 +++---- docs/studies/studies.md | 72 +++++++++++++-------------- 26 files changed, 279 insertions(+), 273 deletions(-) diff --git a/docs/company-data/companies.md b/docs/company-data/companies.md index fd37349..e535fe2 100644 --- a/docs/company-data/companies.md +++ b/docs/company-data/companies.md @@ -7,7 +7,7 @@ companies can be privately or publicly owned. ## List all companies -To list all of the companies and browse them via the API, use the list endpoint: +To list all of the companies and browse them through the API, use the list endpoint: ```http request GET /api/v2/companies @@ -15,7 +15,7 @@ GET /api/v2/companies ## Get a company -You may also directly retrieve a company's details if you already have its system ID. +If you already have the system ID of a company, you can also get the company details directly. ```http request GET /api/v2/companies/123 @@ -36,11 +36,11 @@ Where `123` is the system ID of the company. This returns the same response as the [stock prices endpoint](stock-prices.md#response) and is not paginated. It accepts the `from`, `to` and `interval` parameters described in -the [stock prices documentation](stock-prices.md#parameters). Omitting `from` and `to` returns the full price history, -so use a date window or a `weekly` or `monthly` `interval` to keep the response small. +the [stock prices documentation](stock-prices.md#parameters). If you do not send `from` and `to`, the endpoint returns +the full price history. To keep the response small, use a date window or a `weekly` or `monthly` `interval`. -A company without a primary listing returns no rows, and its ID is listed in `meta.companies_without_listing`. A `503` -error is returned if the market data provider cannot be reached. +A company without a primary listing returns no rows, and the response lists its ID in `meta.companies_without_listing`. +If the API cannot connect to the market data provider, it returns a `503` error. ## Schema @@ -67,7 +67,7 @@ error is returned if the market data provider cannot be reached. ### Relationship Response Schema -The slim relationship schema is used when the company is used as part of an include in another resource. +The API uses the slim relationship schema when the company is part of an include in another resource. | Key | Type | Description | |--------|---------|----------------------------------| @@ -76,7 +76,7 @@ The slim relationship schema is used when the company is used as part of an incl ## Additional Filters -For convenience, we have a set of additional filters that are not available in +For convenience, there are some additional filters that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: - `public` - Set to `1` to only return public (listed) companies. diff --git a/docs/company-data/stock-prices.md b/docs/company-data/stock-prices.md index 72b1e62..2def8dd 100644 --- a/docs/company-data/stock-prices.md +++ b/docs/company-data/stock-prices.md @@ -2,11 +2,12 @@ ## What are stock prices? -Stock prices are the historical share prices of a company's stock exchange listings. They are read from our market data -provider when you request them, one listing at a time, so a request has to name the companies or tickers it wants. +Stock prices are the historical share prices of a company's stock exchange listings. The API reads them from our market data +provider when you request them, one listing at a time. For this reason, a request must name the companies or tickers +that it needs. -Prices are available for any company with a primary stock exchange listing, as well as for any ticker you name -directly, even when it isn't linked to a company in The Fount. +Prices are available for any company with a primary stock exchange listing. Prices are also available for any ticker +that you name directly, even when the ticker is not linked to a company in The Fount. ## List stock prices @@ -16,20 +17,20 @@ To get the stock prices for one or more listings, use the list endpoint: GET /api/v2/stock-prices?companies[]=91&from=2024-01-01&to=2024-12-31 ``` -There is no endpoint for retrieving a single stock price. To get the prices for a single company, you can also use the +There is no endpoint to get a single stock price. To get the prices for a single company, you can also use the [company stock prices endpoint](companies.md#get-a-companys-stock-prices). :::note This endpoint works differently Unlike most other list endpoints, the stock prices endpoint is not paginated and does not support [filters](../customizing/filters.md), [sorting](../customizing/filters.md#sorting-results), -[configurable fields](../customizing/fields.md), [includes](../customizing/includes.md) or `updated_since`. Omitting -`from` and `to` returns the full price history for each listing, so set a date window or a `weekly` or `monthly` -`interval` to keep the response small. +[configurable fields](../customizing/fields.md), [includes](../customizing/includes.md) or `updated_since`. If you do +not send `from` and `to`, the endpoint returns the full price history for each listing. To keep the response small, set +a date window or a `weekly` or `monthly` `interval`. ::: ## Parameters -You must name at least one company or ticker. You may name up to 25 companies and tickers in total per request. +You must name at least one company or ticker. You can name up to 25 companies and tickers in total in each request. | Key | Required? | Type | Description | |-------------|:---------:|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -39,20 +40,20 @@ You must name at least one company or ticker. You may name up to 25 companies an | `to` | :x: | date | The last trading day to return, inclusive, as `YYYY-MM-DD`. Must be on or after `from`. Omit to return up to the most recent close. | | `interval` | :x: | string | One of `daily` (default), `weekly` or `monthly`. See [intervals](#intervals). | -A ticker that duplicates the primary listing of a requested company is only returned once. +If a ticker duplicates the primary listing of a requested company, the response contains that ticker only once. ### Intervals -By default, one row is returned per trading day. Daily rows only exist for trading days, so there are no rows for +By default, the response contains one row for each trading day. Daily rows only exist for trading days, so there are no rows for weekends and market holidays. With a `weekly` or `monthly` interval, each row covers a full week or month. The row holds the period's first open, -its highest high and lowest low, its total volume and its last close. The row is dated on the period's last trading day. +its highest high and lowest low, its total volume and its last close. The date of the row is the last trading day of the period. ## Response -The response contains a `data` array with the price rows and a `meta` object describing the response. Rows are grouped -by ticker and sorted oldest first within each ticker. +The response contains a `data` array with the price rows and a `meta` object that describes the response. The API +groups the rows by ticker and sorts them oldest first within each ticker. ```json { @@ -95,10 +96,10 @@ by ticker and sorted oldest first within each ticker. | `high` | float | The highest price traded at during the row's day, week or month. | | `low` | float | The lowest price traded at during the row's day, week or month. | | `close` | float | The last price traded at. This is not adjusted for splits and dividends. | -| `adjusted_close` | float | The close adjusted for splits and dividends. Use this when comparing prices over time, as `close` is not comparable across a split. | +| `adjusted_close` | float | The close adjusted for splits and dividends. Use this value to compare prices over time, because `close` is not comparable across a split. | | `volume` | integer | The number of shares traded during the row's day, week or month. | -All price and volume fields may be `null` when the provider has no value for them. +All price and volume fields can be `null` when the provider has no value for them. ### Meta schema @@ -109,12 +110,15 @@ All price and volume fields may be `null` when the provider has no value for the | `from` | string | The requested start date, or `null` when the series starts at the beginning of the history. | | `to` | string | The requested end date, or `null` when the series runs to the most recent close. | | `interval` | string | The interval used: `daily`, `weekly` or `monthly`. | -| `tickers_without_prices` | string array | Tickers with no prices at all, usually because they are mistyped or delisted. A ticker that simply didn't trade in the requested window isn't listed here. | +| `tickers_without_prices` | string array | Tickers with no prices at all, usually because they are mistyped or delisted. A ticker that did not trade in the requested window is not in this list. | | `companies_without_listing` | integer array | The IDs of requested companies that have no primary stock exchange listing, and so returned no rows. | ## Errors -- A `422` error is returned if neither `companies` nor `tickers` is given, if more than 25 companies and tickers are - named in total, if a ticker contains characters other than letters, numbers, dots, dashes and underscores, or if `to` - is before `from`. -- A `503` error is returned if the market data provider cannot be reached. Retry the request later. +- The API returns a `422` error if one of these conditions is true: + - The request does not contain `companies` or `tickers`. + - The request names more than 25 companies and tickers in total. + - A ticker contains characters other than letters, numbers, dots, dashes and underscores. + - `to` is before `from`. +- If the API cannot connect to the market data provider, it returns a `503` error. If this occurs, retry the request + later. diff --git a/docs/market-share/brand-shares.md b/docs/market-share/brand-shares.md index 95fce35..92eff86 100644 --- a/docs/market-share/brand-shares.md +++ b/docs/market-share/brand-shares.md @@ -3,7 +3,7 @@ The brand shares endpoint returns Euromonitor's market share for brands. Each row is one brand, in one category, geography (market), data type and year. -Before using this endpoint, please read the [market share overview](index.md). In particular, note +Before you use this endpoint, read the [market share overview](index.md). In particular, note that [Euromonitor IDs are not BAV IDs](index.md#euromonitor-ids-are-not-bav-ids) and that [null is not zero](index.md#null-is-not-zero). @@ -21,38 +21,38 @@ This endpoint requires the `bav:market-share-data` scope. ## Parameters -All list parameters are arrays. In a query string, pass repeated values (`categories[]=1&categories[]=2`) rather than a -single comma-separated string. Each value can be either an ID or a name. When you pass a name, the system attempts to +All list parameters are arrays. In a query string, pass repeated values (`categories[]=1&categories[]=2`) and not a +single comma-separated string. Each value can be either an ID or a name. When you pass a name, the system tries to find the matching record. If no record matches a name, the request fails with a validation error. An ID that does not -exist simply matches nothing. +exist matches nothing. | Key | Required? | Type | Description | |-----------------|:---------------------:|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `brands` | One narrowing filter* | array | Euromonitor brands, as Euromonitor brand IDs or names. Use the [brands catalog](catalog.md#brands) to find them. Max 50. | -| `companies` | One narrowing filter* | array | Owning companies, as Euromonitor company IDs or names. Filters the rows down to brands owned by these companies at the time of the extract. Max 50. | -| `bav_brands` | One narrowing filter* | array | [BAV brands](../brands/brands.md), as BAV brand IDs or names. Resolved to Euromonitor brands through the link held on the brand, so a brand that has not been linked matches nothing. Max 50. | -| `bav_companies` | One narrowing filter* | array | [BAV companies](../company-data/companies.md), as BAV company IDs or names. Resolved to Euromonitor companies through the link held on the company, so a company that has not been linked matches nothing. Max 50. | +| `companies` | One narrowing filter* | array | Owning companies, as Euromonitor company IDs or names. Filters the rows to brands that these companies owned at the time of the extract. Max 50. | +| `bav_brands` | One narrowing filter* | array | [BAV brands](../brands/brands.md), as BAV brand IDs or names. The API resolves them to Euromonitor brands through the link on the brand. A brand that is not linked matches nothing. Max 50. | +| `bav_companies` | One narrowing filter* | array | [BAV companies](../company-data/companies.md), as BAV company IDs or names. The API resolves them to Euromonitor companies through the link on the company. A company that is not linked matches nothing. Max 50. | | `categories` | One narrowing filter* | array | Euromonitor categories, as IDs or names. Max 50. | | `geographies` | One narrowing filter* | array | Euromonitor geographies (markets), as IDs or names. These are not BAV countries. Use the [geographies catalog](catalog.md#geographies) to find them. Max 50. | | `industries` | One narrowing filter* | array | Euromonitor industries, as IDs or names. Max 50. | -| `data_types` | :x: | array | What is being measured, as Euromonitor data type IDs or names. Rows that differ only by data type are not comparable, so filtering to one is usually what you want. Max 50. | -| `years` | :x: | array | The [years](../metadata/years.md), as year IDs or year numbers. A year does not narrow a query on its own and has to be combined with a narrowing filter. Max 50. | +| `data_types` | :x: | array | What the rows measure, as Euromonitor data type IDs or names. Rows that differ only by data type are not comparable. In most cases, filter to one data type. Max 50. | +| `years` | :x: | array | The [years](../metadata/years.md), as year IDs or year numbers. A year does not narrow a query on its own. You must use it with a narrowing filter. Max 50. | | `score_type` | :x: | string | Which measure the `value` of each row carries. One of `actual_usd` (default), `actual_local`, `percentage` or `rank`. See [score types](#score-types). | | `format` | :x: | string | The response format: `json` (default), `llm` (the data as CSV with instructions for use in AI prompts, see [response formats](../brand-data/data-models.md#response-formats)) or `mcp` (the response shape used by our MCP servers). | \* At least one of `brands`, `companies`, `bav_brands`, `bav_companies`, `categories`, `geographies` or `industries` is -required. A request without any of these is rejected with a validation error. +required. The API rejects a request without any of these with a validation error. ### Score types -The `score_type` parameter decides which measure each row's `value` holds: +The `score_type` parameter sets which measure each row's `value` holds: - `actual_usd` - The absolute value in USD at a fixed exchange rate. This is the default. - `actual_local` - The absolute value in the market's own currency. - `percentage` - The share of the category in that market, on a 0-100 scale. -- `rank` - The position within the category in that market, where 1 is the largest. A rank only means something when - compared against the other brands in the same category, geography, data type and year. Ranks must never be summed - or averaged. +- `rank` - The position within the category in that market, where 1 is the largest. A rank has a meaning only when you + compare it with the other brands in the same category, geography, data type and year. Do not sum or average + ranks. Not every slice carries every measure. A `null` value means that the figure was not supplied, not that it is zero. @@ -81,26 +81,26 @@ Or as a `POST` request: The response is not paginated. It contains a `meta` object and a `data` array with one object per row. :::note Row limit -A query matching more than 25,000 rows is rejected with a validation error rather than truncated. Narrow the query with -a geography, category or year filter if this happens. +If a query matches more than 25,000 rows, the API rejects it with a validation error and does not truncate it. If this +occurs, narrow the query with a geography, category or year filter. ::: ### Meta | Key | Type | Description | |--------------|--------|-----------------------------------------------------------------| -| `source` | string | A source label suitable for captioning the data. | +| `source` | string | A source label that you can use as a caption for the data. | | `score_type` | string | The score type that each row's `value` holds. | ### Data Each entity in a row is a nested object with an `id` and a `name` (the year has an `id` and a `year`). An entity is -`null` where there is nothing to point at, such as an unlinked brand or a dimension that Euromonitor left blank. +`null` when there is no record to refer to, such as an unlinked brand or a dimension that Euromonitor left blank. | Key | Type | Description | |---------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | `brand` | object | The Euromonitor brand. | -| `bav_brand` | object\|null | The [BAV brand](../brands/brands.md) the Euromonitor brand is linked to. `null` when there is no link, in which case the row cannot be compared with BAV brand data. | +| `bav_brand` | object\|null | The [BAV brand](../brands/brands.md) the Euromonitor brand is linked to. `null` when there is no link. In that case, you cannot compare the row with BAV brand data. | | `company` | object | The Euromonitor company that owns the brand. | | `bav_company` | object\|null | The [BAV company](../company-data/companies.md) the Euromonitor company is linked to, or `null`. | | `category` | object | The Euromonitor category. | @@ -112,7 +112,7 @@ Each entity in a row is a nested object with an `id` and a `name` (the year has | `unit` | string\|null | What `value` is measured in: `USD`, the local currency code, or `%`. `null` for ranks. | | `score_type` | string | The score type that `value` holds. | -Rows that differ only by data type measure different things and should not be summed or averaged. +Rows that differ only by data type measure different things. Do not sum or average them. ```json { @@ -144,6 +144,6 @@ The values in the example are illustrative. ## Errors - `403` - Your account does not have access to Euromonitor market share data. -- `422` - A validation error. This is returned when no narrowing filter is provided, when a name could not be matched - to a record, or when the query matches more than 25,000 rows. The `errors` object is keyed by the filter you sent, - for example `geographies.0`, or `filters` for errors about the query as a whole. +- `422` - A validation error. The API returns this error when the request has no narrowing filter, when a name does + not match a record, or when the query matches more than 25,000 rows. The `errors` object uses the filter that you + sent as the key, for example `geographies.0`, or `filters` for errors about the query as a whole. diff --git a/docs/market-share/catalog.md b/docs/market-share/catalog.md index 8e1629f..20d930b 100644 --- a/docs/market-share/catalog.md +++ b/docs/market-share/catalog.md @@ -3,7 +3,7 @@ ## What is the catalog? Euromonitor keeps its own catalog of the brands, companies, categories, data types, geographies and industries that -market share is measured for. The catalog endpoints give you read-only access to these lists so that you can find the +market share is measured for. The catalog endpoints give you read-only access to these lists. Use them to find the Euromonitor IDs to pass to the [brand shares](brand-shares.md) and [company shares](company-shares.md) endpoints. :::note Euromonitor IDs @@ -15,19 +15,19 @@ All catalog endpoints require the `bav:market-share-data` scope. They are pagina support [filters & sorting](../customizing/filters.md), [configurable fields](../customizing/fields.md) and [includes](../customizing/includes.md). -Every relationship that can be included (including the `bav_` links) is returned in a slim relationship schema: +Every relationship that you can include, and also the `bav_` links, uses a slim relationship schema: | Key | Type | Description | |--------|---------|--------------------------------------| | `id` | integer | The ID of the related record. | | `name` | string | The name of the related record. | -A relationship that is not linked is returned as `null`. +If a relationship is not linked, the API returns it as `null`. ## Brands Euromonitor's own brand catalog. This is not the same list as the [BAV brands](../brands/brands.md). It covers brands -BAV has never surveyed, splits some brands that BAV holds as one, and names others differently. The `id` here is what +that BAV has never surveyed, splits some brands that BAV holds as one, and names others differently. The `id` here is what the `brands` filter on [brand shares](brand-shares.md) takes. ```http request @@ -50,12 +50,12 @@ Where `123` is the Euromonitor ID of the brand. ### Relationships & includes - `company` - The Euromonitor company that owns the brand. -- `bav_brand` - The [BAV brand](../brands/brands.md) this brand is linked to. `null` when there is no link, in which - case its market share cannot be compared with BAV brand data. +- `bav_brand` - The [BAV brand](../brands/brands.md) this brand is linked to. `null` when there is no link. In that + case, you cannot compare its market share with BAV brand data. ## Companies -Euromonitor's own company catalog. As with brands, this is Euromonitor's list rather than the +Euromonitor's own company catalog. As with brands, this is Euromonitor's list and not the BAV [companies](../company-data/companies.md). The `id` here is what the `companies` filter on the share endpoints takes. @@ -83,11 +83,11 @@ Where `123` is the Euromonitor ID of the company. ## Categories The categories that market share is measured within. Categories form a tree: `level` 1 is a top-level category within -its industry, and `parent_id` walks up from there. Filter on `level` to get one tier of the tree, or on `parent_id` to +its industry, and `parent_id` gives the category one level above. Filter on `level` to get one tier of the tree, or on `parent_id` to get one category's children. -A category's industry is not fixed for all time, as Euromonitor may reorganize its categories. Filter share rows by -category rather than treating the industry as a permanent property of a category. +A category's industry is not fixed for all time, because Euromonitor can reorganize its categories. Filter share rows +by category. Do not treat the industry as a permanent property of a category. ```http request GET /api/v2/market-share/categories @@ -119,8 +119,8 @@ Where `123` is the Euromonitor ID of the category. ## Data Types What a share row measures, such as retail value or retail volume. Two rows that differ only by data type measure -different things and are not comparable. They must not be summed or averaged across. Not every data type applies to -every category, which is what the `categories` and `industries` includes describe. +different things and are not comparable. Do not sum or average across them. Not every data type applies to every +category. The `categories` and `industries` includes show where each data type applies. ```http request GET /api/v2/market-share/data-types @@ -146,8 +146,8 @@ Where `123` is the Euromonitor ID of the data type. ## Geographies The markets that market share is measured in, as a tree of regions, countries and cities. These are Euromonitor's -geographies, not the BAV [countries](../metadata/countries.md). Where a geography lines up with a BAV country, -`bav_country_id` points to it. It is `null` for regions and cities. +geographies, not the BAV [countries](../metadata/countries.md). If a geography matches a BAV country, +`bav_country_id` refers to that country. It is `null` for regions and cities. ```http request GET /api/v2/market-share/geographies @@ -169,7 +169,7 @@ Where `123` is the Euromonitor ID of the geography. ### Additional Filters -To take one level of the geography tree, use one of these filters. Any value turns the filter on. +To get one level of the geography tree, use one of these filters. Any value turns the filter on. - `filter[regions]=1` - Only include regions, the top level of the tree. - `filter[countries]=1` - Only include countries. diff --git a/docs/market-share/company-shares.md b/docs/market-share/company-shares.md index 3c13fc6..fb39981 100644 --- a/docs/market-share/company-shares.md +++ b/docs/market-share/company-shares.md @@ -3,11 +3,11 @@ The company shares endpoint returns Euromonitor's market share for companies. Each row is one company, in one category, geography (market), data type and year. -Company share is measured separately from brand share. A company's share of a category is not the sum of its brands' -shares, because brands below Euromonitor's reporting threshold are not listed individually and some share comes from -unbranded products. +Euromonitor measures company share separately from brand share. A company's share of a category is not the sum of the +shares of its brands. One reason is that Euromonitor does not list brands below its reporting threshold individually. +Another reason is that some share comes from unbranded products. -Before using this endpoint, please read the [market share overview](index.md). In particular, note +Before you use this endpoint, read the [market share overview](index.md). In particular, note that [Euromonitor IDs are not BAV IDs](index.md#euromonitor-ids-are-not-bav-ids) and that [null is not zero](index.md#null-is-not-zero). @@ -25,25 +25,25 @@ This endpoint requires the `bav:market-share-data` scope. ## Parameters -All list parameters are arrays. In a query string, pass repeated values (`categories[]=1&categories[]=2`) rather than a -single comma-separated string. Each value can be either an ID or a name. When you pass a name, the system attempts to +All list parameters are arrays. In a query string, pass repeated values (`categories[]=1&categories[]=2`) and not a +single comma-separated string. Each value can be either an ID or a name. When you pass a name, the system tries to find the matching record. If no record matches a name, the request fails with a validation error. An ID that does not -exist simply matches nothing. +exist matches nothing. | Key | Required? | Type | Description | |-----------------|:---------------------:|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `companies` | One narrowing filter* | array | Euromonitor companies, as Euromonitor company IDs or names. Use the [companies catalog](catalog.md#companies) to find them. Max 50. | -| `bav_companies` | One narrowing filter* | array | [BAV companies](../company-data/companies.md), as BAV company IDs or names. Resolved to Euromonitor companies through the link held on the company, so a company that has not been linked matches nothing. Max 50. | +| `bav_companies` | One narrowing filter* | array | [BAV companies](../company-data/companies.md), as BAV company IDs or names. The API resolves them to Euromonitor companies through the link on the company. A company that is not linked matches nothing. Max 50. | | `categories` | One narrowing filter* | array | Euromonitor categories, as IDs or names. Max 50. | | `geographies` | One narrowing filter* | array | Euromonitor geographies (markets), as IDs or names. These are not BAV countries. Use the [geographies catalog](catalog.md#geographies) to find them. Max 50. | | `industries` | One narrowing filter* | array | Euromonitor industries, as IDs or names. Max 50. | -| `data_types` | :x: | array | What is being measured, as Euromonitor data type IDs or names. Rows that differ only by data type are not comparable, so filtering to one is usually what you want. Max 50. | -| `years` | :x: | array | The [years](../metadata/years.md), as year IDs or year numbers. A year does not narrow a query on its own and has to be combined with a narrowing filter. Max 50. | +| `data_types` | :x: | array | What the rows measure, as Euromonitor data type IDs or names. Rows that differ only by data type are not comparable. In most cases, filter to one data type. Max 50. | +| `years` | :x: | array | The [years](../metadata/years.md), as year IDs or year numbers. A year does not narrow a query on its own. You must use it with a narrowing filter. Max 50. | | `score_type` | :x: | string | Which measure the `value` of each row carries. One of `actual_usd` (default), `actual_local`, `percentage` or `rank`. See [score types](brand-shares.md#score-types). | | `format` | :x: | string | The response format: `json` (default), `llm` (the data as CSV with instructions for use in AI prompts, see [response formats](../brand-data/data-models.md#response-formats)) or `mcp` (the response shape used by our MCP servers). | -\* At least one of `companies`, `bav_companies`, `categories`, `geographies` or `industries` is required. A request -without any of these is rejected with a validation error. +\* At least one of `companies`, `bav_companies`, `categories`, `geographies` or `industries` is required. The API rejects +a request without any of these with a validation error. ## Example @@ -62,14 +62,14 @@ The response is not paginated. It contains a `meta` object and a `data` array wi object is the same as for [brand shares](brand-shares.md#meta). :::note Row limit -A query matching more than 25,000 rows is rejected with a validation error rather than truncated. Narrow the query with -a geography, category or year filter if this happens. +If a query matches more than 25,000 rows, the API rejects it with a validation error and does not truncate it. If this +occurs, narrow the query with a geography, category or year filter. ::: ### Data Each entity in a row is a nested object with an `id` and a `name` (the year has an `id` and a `year`). An entity is -`null` where there is nothing to point at, such as an unlinked company or a dimension that Euromonitor left blank. +`null` when there is no record to refer to, such as an unlinked company or a dimension that Euromonitor left blank. | Key | Type | Description | |---------------|--------------|---------------------------------------------------------------------------------------------------------------------| @@ -87,6 +87,6 @@ Each entity in a row is a nested object with an `id` and a `name` (the year has ## Errors - `403` - Your account does not have access to Euromonitor market share data. -- `422` - A validation error. This is returned when no narrowing filter is provided, when a name could not be matched - to a record, or when the query matches more than 25,000 rows. The `errors` object is keyed by the filter you sent, - or `filters` for errors about the query as a whole. +- `422` - A validation error. The API returns this error when the request has no narrowing filter, when a name does + not match a record, or when the query matches more than 25,000 rows. The `errors` object uses the filter that you + sent as the key, or `filters` for errors about the query as a whole. diff --git a/docs/market-share/index.md b/docs/market-share/index.md index f65ef82..58f3865 100644 --- a/docs/market-share/index.md +++ b/docs/market-share/index.md @@ -5,7 +5,7 @@ sidebar_label: Overview # Market Share The market share endpoints give you access to Euromonitor's market share data for brands and companies, sliced by -category, geography (market), data type and year. Alongside the share data you also get Euromonitor's catalogs of +category, geography (market), data type and year. With the share data, you also get Euromonitor's catalogs of brands, companies, categories, data types, geographies and industries that the data is sliced by. All market share endpoints live under the `/api/v2/market-share` prefix: @@ -21,22 +21,22 @@ All market share endpoints live under the `/api/v2/market-share` prefix: | `GET`/`POST` | `/api/v2/market-share/brand-shares` | Market share for brands. | | `GET`/`POST` | `/api/v2/market-share/company-shares`| Market share for companies. | -The catalog endpoints are documented on the [catalog](catalog.md) page, and the share data on -the [brand shares](brand-shares.md) and [company shares](company-shares.md) pages. +The [catalog](catalog.md) page documents the catalog endpoints. The [brand shares](brand-shares.md) +and [company shares](company-shares.md) pages document the share data. ## Access The market share endpoints require the **Market Share Data** (`bav:market-share-data`) scope on your API key or application. See [authentication](../authentication.md#scopes) for more information on scopes. -The scope can only be assigned by users who have access to Euromonitor data in The Fount. Access is also checked -against the user on every request, so if the user behind a token loses access to Euromonitor data, the token will -receive a `403` response even though it still holds the scope. +Only users who have access to Euromonitor data in The Fount can assign the scope. The API also checks the access of +the user on every request. If the user behind a token loses access to Euromonitor data, the token will receive a `403` +response. This occurs even though the token still holds the scope. ## Important concepts -Euromonitor data works differently from the BAV data in a few important ways. Please read through these before you -start building on top of the market share endpoints. +Euromonitor data works differently from the BAV data in a few important ways. Read these concepts before you +start to build on the market share endpoints. ### Euromonitor IDs are not BAV IDs @@ -45,7 +45,7 @@ None of these are the same as the BAV resources with similar names. The Euromoni BAV has never surveyed, splits some brands that BAV holds as one, and names others differently. Likewise, Euromonitor geographies are not the same as the BAV [countries](../metadata/countries.md). -Everything on the market share endpoints is Euromonitor's unless it is prefixed with `bav_`. This means that: +Everything on the market share endpoints is Euromonitor's unless it has the prefix `bav_`. This means that: - `brands`, `companies`, `categories`, `geographies`, `industries` and `data_types` always take Euromonitor IDs. - `bav_brands` and `bav_companies` take BAV [brand](../brands/brands.md) and [company](../company-data/companies.md) @@ -53,36 +53,36 @@ Everything on the market share endpoints is Euromonitor's unless it is prefixed - `bav_brand`, `bav_company` and `bav_country` in responses are the BAV records that a Euromonitor record is linked to. :::warning Do not mix up the IDs -A BAV ID sent where a Euromonitor ID is expected does not fail. It silently reads as another, unrelated Euromonitor -entity (or matches nothing). Always look up Euromonitor IDs using the [catalog endpoints](catalog.md) first, or use the -`bav_brands` and `bav_companies` filters when you only know the BAV ID. +If you send a BAV ID where the API expects a Euromonitor ID, the request does not fail. The API silently reads it as +another, unrelated Euromonitor entity (or it matches nothing). Always use the [catalog endpoints](catalog.md) to look up +Euromonitor IDs first. If you only know the BAV ID, use the `bav_brands` and `bav_companies` filters. ::: ### Linking to BAV -Where a Euromonitor brand or company has been linked to a BAV brand or company, the catalog and share endpoints tell -you so through the `bav_brand` and `bav_company` fields. Only linked records can be read alongside BAV brand equity -data. Where no link exists, these fields are `null`. +If a Euromonitor brand or company is linked to a BAV brand or company, the `bav_brand` and `bav_company` fields in the +catalog and share endpoints show the link. You can read only linked records together with BAV brand equity data. Where no link exists, these fields are `null`. ### Null is not zero The different measures (USD value, local currency value, percentage share and rank) arrive from Euromonitor in separate -extracts and are merged into one row. A row carrying one measure but not another is normal. +extracts. These extracts are merged into one row. It is normal for a row to have one measure but not another. -A `null` value means that the figure was not supplied for that slice. It never means zero, and it should never be read -as the brand or company holding none of the category. +A `null` value means that the figure was not supplied for that slice. It never means zero. Do not read it as a sign that +the brand or company has none of the category. ### Data types are not comparable -Each share row is measured as a specific [data type](catalog.md#data-types), such as retail value or retail volume. -Rows that differ only by data type measure different things. They must not be summed or averaged across. Filtering your -share queries to a single data type is usually what you want. +Each share row measures a specific [data type](catalog.md#data-types), such as retail value or retail volume. Rows +that differ only by data type measure different things. Do not sum or average across them. In most cases, filter your +share queries to a single data type. ### At least one narrowing filter is required -Every share query has to name at least one entity, category, geography or industry. Without one the query would be the -whole of Euromonitor. A year on its own does not count, since every brand in every market is measured each year. See +Every share query must name at least one entity, category, geography or industry. Without one, the query will be the +whole of Euromonitor. A year on its own does not count, because Euromonitor measures every brand in every market each +year. See the [brand shares](brand-shares.md) and [company shares](company-shares.md) pages for the exact filters that qualify. -The share responses are not paginated. A query matching more than 25,000 rows is rejected with a validation error -rather than truncated. Narrow the query with a geography, category or year filter if this happens. +The share responses are not paginated. If a query matches more than 25,000 rows, the API rejects it with a +validation error and does not truncate it. If this occurs, narrow the query with a geography, category or year filter. diff --git a/docs/measures/bav-question-groups.md b/docs/measures/bav-question-groups.md index 9c2d581..9714b73 100644 --- a/docs/measures/bav-question-groups.md +++ b/docs/measures/bav-question-groups.md @@ -2,12 +2,12 @@ ## What are BAV question groups? -[BAV questions](bav-questions.md) are organized in groups, such as demographics. The groups can be used to create a -better selection experience in an interface, for example when building an [audience](../audiences/audiences.md). +[BAV questions](bav-questions.md) are organized in groups, such as demographics. You can use the groups to create a +better selection experience in an interface, for example when you build an [audience](../audiences/audiences.md). ## List all BAV question groups -To list all of the BAV question groups and browse them via the API, use the list endpoint: +To list all of the BAV question groups and browse them through the API, use the list endpoint: ```http request GET /api/v2/bav-question-groups @@ -15,7 +15,7 @@ GET /api/v2/bav-question-groups ## Get a BAV question group -You may also directly retrieve a BAV question group's details if you already have its system ID. +If you already have the system ID of a BAV question group, you can also get its details directly. ```http request GET /api/v2/bav-question-groups/123 @@ -38,7 +38,7 @@ Where `123` is the system ID of the BAV question group. ### Relationship Response Schema -The slim relationship schema is used when the BAV question group is used as part of an include in another resource. +The API uses the slim relationship schema when the BAV question group is part of an include in another resource. | Key | Type | Description | |---------------|---------|----------------------------------------------------------------| @@ -52,10 +52,10 @@ The slim relationship schema is used when the BAV question group is used as part ## Additional Filters -For convenience, we have a set of additional filters that are not available in +For convenience, there are some additional filters that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: -- `questions` - A comma-separated list of BAV question IDs. Only groups containing these questions are returned. +- `questions` - A comma-separated list of BAV question IDs. The API returns only the groups that contain these questions. ## Relationships & includes diff --git a/docs/measures/bav-questions.md b/docs/measures/bav-questions.md index c9b9551..945224f 100644 --- a/docs/measures/bav-questions.md +++ b/docs/measures/bav-questions.md @@ -3,7 +3,7 @@ ## What are BAV questions? BAV questions are the respondent-level questions that BAV asks, such as demographics, opinions and behaviors. Unlike -[brand measures](brand-measures.md), they are asked about the respondent rather than about a brand. +[brand measures](brand-measures.md), they ask about the respondent and not about a brand. [Audiences](../audiences/audiences.md) are defined from these questions. Use these endpoints to find the questions that you can [build an audience](../audiences/managing-audiences.md) from, and the studies that asked them. @@ -12,7 +12,7 @@ Questions are organized in [BAV question groups](bav-question-groups.md). ## List all BAV questions -To list all of the BAV questions and browse them via the API, use the list endpoint: +To list all of the BAV questions and browse them through the API, use the list endpoint: ```http request GET /api/v2/bav-questions @@ -20,7 +20,7 @@ GET /api/v2/bav-questions ## Get a BAV question -You may also directly retrieve a BAV question's details if you already have its system ID. +If you already have the system ID of a BAV question, you can also get its details directly. ```http request GET /api/v2/bav-questions/123 @@ -44,7 +44,7 @@ Where `123` is the system ID of the BAV question. ### Relationship Response Schema -The slim relationship schema is used when the BAV question is used as part of another resource. +The API uses the slim relationship schema when the BAV question is part of another resource. | Key | Type | Description | |---------|---------|------------------------------------------| @@ -59,12 +59,12 @@ the [includes section](../customizing/includes) for more information on how this are available: - `group` - The [BAV question group](bav-question-groups.md) that the question belongs to. -- `studies` - The [studies](../studies/studies.md) that asked the question. Only studies you have access to are - included. +- `studies` - The [studies](../studies/studies.md) that asked the question. The API includes only the studies + that you have access to. ## Studies that asked a BAV question -To list every study that asked a BAV question, use the studies endpoint. This is useful to check where a question has +To list every study that asked a BAV question, use the studies endpoint. Use it to check where a question has answers before you build an audience definition with it. ```http request @@ -73,10 +73,10 @@ GET /api/v2/bav-questions/123/studies Where `123` is the system ID of the BAV question. -Only studies you have access to are listed. Fused studies take their questions from the studies they were fused from, -so they are listed under those source studies rather than on their own. +The endpoint lists only the studies that you have access to. Fused studies take their questions from the studies that +they were fused from. For this reason, the endpoint lists those source studies and not the fused study. -The results are sorted by `study_id` by default. You may also sort by `id`, `created_at` and `updated_at`. +By default, the results are sorted by `study_id`. You can also sort by `id`, `created_at` and `updated_at`. | Key | Type | Description | |--------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------| @@ -90,4 +90,4 @@ The following filters are available: - `studies` - A comma-separated list of study IDs to filter by. - `updated_since` - Only return records changed on or after this date. See [filters](../customizing/filters.md). -To go the other way and list the questions a specific study asked, see the [study catalog](study-catalog.md). +To list the questions that a specific study asked, see the [study catalog](study-catalog.md). diff --git a/docs/measures/brand-measure-groups.md b/docs/measures/brand-measure-groups.md index 1141825..52745e8 100644 --- a/docs/measures/brand-measure-groups.md +++ b/docs/measures/brand-measure-groups.md @@ -6,7 +6,7 @@ ## List all brand measure groups -To list all of the brand measure groups and browse them via the API, use the list endpoint: +To list all of the brand measure groups and browse them through the API, use the list endpoint: ```http request GET /api/v2/brand-measure-groups @@ -14,7 +14,7 @@ GET /api/v2/brand-measure-groups ## Get a brand measure group -You may also directly retrieve a brand measure group's details if you already have its system ID. +If you already have the system ID of a brand measure group, you can also get its details directly. ```http request GET /api/v2/brand-measure-groups/123 @@ -37,7 +37,7 @@ Where `123` is the system ID of the brand measure group. ### Relationship Response Schema -The slim relationship schema is used when the brand measure group is used as part of an include in another resource. +The API uses the slim relationship schema when the brand measure group is part of an include in another resource. | Key | Type | Description | |---------------|---------|--------------------------------------------------------------| @@ -50,10 +50,10 @@ The slim relationship schema is used when the brand measure group is used as par ## Additional Filters -For convenience, we have a set of additional filters that are not available in +For convenience, there are some additional filters that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: -- `measures` - A comma-separated list of brand measure IDs. Only groups containing these measures are returned. +- `measures` - A comma-separated list of brand measure IDs. The API returns only the groups that contain these measures. ## Relationships & includes diff --git a/docs/measures/brand-measures.md b/docs/measures/brand-measures.md index fde5e9f..75b9af1 100644 --- a/docs/measures/brand-measures.md +++ b/docs/measures/brand-measures.md @@ -2,11 +2,11 @@ ## What are brand measures? -Brand measures are the brand-level measures in BAV studies. Most are asked about each brand directly in the survey, -while some are calculated afterwards. Each measure belongs to a [brand measure group](brand-measure-groups.md). +Brand measures are the brand-level measures in BAV studies. The survey asks most of them directly about each brand. +Some are calculated afterwards. Each measure belongs to a [brand measure group](brand-measure-groups.md). Brand measures differ from [brand metrics](../metrics/metrics.md). Brand metrics are the calculated scores in -the [brandscape data](../brand-data/brandscape-data.md), while brand measures describe what is asked about a brand and +the [brandscape data](../brand-data/brandscape-data.md). Brand measures describe what the survey asks about a brand and how its answers are stored. A measure is not asked in every study. Use the [studies endpoint](#studies-a-brand-measure-was-asked-in) to see where a @@ -14,7 +14,7 @@ measure has data, or the [study catalog](study-catalog.md) to see which measures ## List all brand measures -To list all of the brand measures and browse them via the API, use the list endpoint: +To list all of the brand measures and browse them through the API, use the list endpoint: ```http request GET /api/v2/brand-measures @@ -22,7 +22,7 @@ GET /api/v2/brand-measures ## Get a brand measure -You may also directly retrieve a brand measure's details if you already have its system ID. +If you already have the system ID of a brand measure, you can also get its details directly. ```http request GET /api/v2/brand-measures/123 @@ -48,7 +48,7 @@ Where `123` is the system ID of the brand measure. ### Relationship Response Schema -The slim relationship schema is used when the brand measure is used as part of another resource. +The API uses the slim relationship schema when the brand measure is part of another resource. | Key | Type | Description | |---------|---------|---------------------------------------------------------------------| @@ -77,11 +77,12 @@ GET /api/v2/brand-measures/123/studies Where `123` is the system ID of the brand measure. -Only studies you have access to are listed, so the same measure can return a different set of studies for a different -API key. A fused study borrows the measures of the studies it was fused from, so it is only listed here for the few -computed measures that are stored on the fused study itself. +The endpoint lists only the studies that you have access to. For this reason, the same measure can return a different +set of studies for a different API key. A fused study borrows the measures of the studies that it was fused from. For +this reason, the endpoint lists a fused study only for the few computed measures that are stored on the fused study +itself. -The results are sorted by `study_id` by default. You may also sort by `id`, `created_at` and `updated_at`. +By default, the results are sorted by `study_id`. You can also sort by `id`, `created_at` and `updated_at`. | Key | Type | Description | |--------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------| diff --git a/docs/measures/index.md b/docs/measures/index.md index 2448324..487905a 100644 --- a/docs/measures/index.md +++ b/docs/measures/index.md @@ -4,8 +4,8 @@ sidebar_label: Overview # Measures & Questions -When BAV studies brands it asks respondents a set of questions. The API exposes these in a few different ways depending -on what you need: +When BAV studies brands, it asks respondents a set of questions. The API exposes these questions in different ways. +Select the one that you need: - **[Brand metrics](../metrics/metrics.md).** The calculated metrics that make up the BAV data, such as Differentiation and Esteem. These are the columns in the [brandscape data](../brand-data/brandscape-data.md). @@ -24,6 +24,6 @@ All of the endpoints in this section require the `bav:brand-data` scope. ## Building audiences -Brand measures and BAV questions can both be used as conditions when +You can use brand measures and BAV questions as conditions when [building your own audiences](../audiences/managing-audiences.md). Use the `bav-study-measure` metric type for a brand measure and `bav-study-question` for a BAV question. diff --git a/docs/measures/study-catalog.md b/docs/measures/study-catalog.md index d478067..3ad93ee 100644 --- a/docs/measures/study-catalog.md +++ b/docs/measures/study-catalog.md @@ -28,8 +28,8 @@ GET /api/v2/studies/123/brand-metrics Where `123` is the system ID of the study. -Only active metrics that you have access to are returned. The results are sorted by `sort_order` and `name` by -default. +The endpoint returns only the active metrics that you have access to. By default, the results are sorted by +`sort_order` and `name`. | Key | Type | Filterable | Sortable | Description | |------------------------|---------|:--------------------------:|:------------------:|----------------------------------------------------------------------------------------------| @@ -93,8 +93,8 @@ GET /api/v2/studies/123/audience-questions Where `123` is the system ID of the study. -Only [BAV questions](bav-questions.md) that belong to a [question group](bav-question-groups.md) are listed. Use -the [BAV questions in a study](#bav-questions-in-a-study) endpoint to list all questions. +The endpoint lists only the [BAV questions](bav-questions.md) that belong to a [question group](bav-question-groups.md). +Use the [BAV questions in a study](#bav-questions-in-a-study) endpoint to list all questions. | Key | Type | Filterable | Sortable | Description | |---------------------------|---------|:--------------------------:|:------------------:|-------------------------------------------------------------------------------------| @@ -127,7 +127,7 @@ Each option has a `value` (what appears in the data) and a `label` (what the val ``` The same measure or question can have different answer options in different studies, so always read the options for -the study you are working with. Boolean measures and questions without stored options use `1` (Yes) and `0` (No). +the study that you use. Boolean measures and questions without stored options use `1` (Yes) and `0` (No). ## BAV questions in a study @@ -140,12 +140,12 @@ GET /api/v2/studies/123/bav-questions Where `123` is the system ID of the study. Unlike the [audience questions](#audience-questions-in-a-study) endpoint, this also lists questions that are not in a -question group, and leaves out each question's group and answer options. +question group, and does not include the group and answer options of each question. For a fused study, the questions come from the studies it was fused from. Each row names the study that asked the -question, and only studies you have access to are listed. +question. The endpoint lists only the studies that you have access to. -The results are sorted by `measurable_id` (the question ID) by default. You may also sort by `id`, `created_at` and +By default, the results are sorted by `measurable_id` (the question ID). You can also sort by `id`, `created_at` and `updated_at`. | Key | Type | Description | diff --git a/docs/metadata/cities.md b/docs/metadata/cities.md index de20353..4dc71fb 100644 --- a/docs/metadata/cities.md +++ b/docs/metadata/cities.md @@ -2,12 +2,12 @@ ## What are cities? -Some BAV resources rely on segmenting data by cities. This resource contains a list of all the cities in -the world with a population over 500 with additional metadata for system use. +Some BAV resources segment data by cities. This resource contains a list of all the cities in the world with a +population over 500. It also contains additional metadata for system use. ## List all cities -To list all of the cities and browse them via the API, use the list endpoint: +To list all of the cities and browse them through the API, use the list endpoint: ```http request GET /api/v2/cities @@ -15,7 +15,7 @@ GET /api/v2/cities ## Get a city -You may also directly retrieve a city's details if you already have its system ID. +If you already have the system ID of a city, you can also get its details directly. ```http request GET /api/v2/cities/123 @@ -38,7 +38,7 @@ Where `123` is the system ID of the city. | `population` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The population of the city. | | `elevation` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The city's elevation in meters, where GeoNames has a surveyed value. Also see `digital_elevation_model` which is available for more cities. | | `digital_elevation_model` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The city's elevation in meters from the GeoNames digital elevation model. | -| `geonames_feature_code` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The [feature code](http://www.geonames.org/export/codes.html) from GeoNames, allowing you to filter on type of city. `PPLC` is a capital city. | +| `geonames_feature_code` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The [feature code](http://www.geonames.org/export/codes.html) from GeoNames. You can use it to filter on the type of city. `PPLC` is a capital city. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this city was first created in the system. | | `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this city was last updated in the system. | @@ -46,7 +46,7 @@ You can also sort the cities by `country_id`. To get the country for each city, ## Additional Filters -For convenience, we have a set of additional filters that are not available in +For convenience, there are some additional filters that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: - `capitals` - Set to `1` to only return capital cities. diff --git a/docs/metadata/countries.md b/docs/metadata/countries.md index 9914ce5..457147d 100644 --- a/docs/metadata/countries.md +++ b/docs/metadata/countries.md @@ -2,14 +2,14 @@ ## What are countries? -Many of the BAV resources rely on segmenting data by countries. This resource contains a list of all the countries in +Many of the BAV resources segment data by countries. This resource contains a list of all the countries in the world, with additional ISO codes and metadata for system use. -We suggest that you use the term `Market` instead of country when showing this in an interface. +We recommend that you use the term `Market` instead of country when you show this in an interface. ## List all countries -To list all of the countries and browse them via the API, use the list endpoint: +To list all of the countries and browse them through the API, use the list endpoint: ```http request GET /api/v2/countries @@ -17,7 +17,7 @@ GET /api/v2/countries ## Get a country -You may also directly retrieve a country's details if you already have its system ID. +If you already have the system ID of a country, you can also get its details directly. ```http request GET /api/v2/countries/123 @@ -32,7 +32,7 @@ Where `123` is the system ID of the country. | Key | Type | Filterable | Sortable | Configurable | Description | |----------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-------------------------------------------------------------------------------------| | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID for the country. Always returned. | -| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the market should be used/shown or not. | +| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether you can use and show the market. | | `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the country in English. | | `native_name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the country in its native language. | | `code` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The two-letter code (ISO 3166-1 alpha-2) for the country. | @@ -48,7 +48,7 @@ Where `123` is the system ID of the country. ### Relationship Response Schema -The slim relationship schema is used when the country is used as part of an include in another resource. +The API uses the slim relationship schema when the country is part of an include in another resource. | Key | Type | Description | |----------------|---------|------------------------------------------------------------------------------------------| @@ -61,7 +61,7 @@ The slim relationship schema is used when the country is used as part of an incl ## Additional Filters -For convenience, we have a set of additional filters that are not available in +For convenience, there are some additional filters that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: - `active` - Set to `1` to only return active countries. @@ -69,8 +69,8 @@ the [default filters](../customizing/filters.md) or are part of the columns. The - `with_studies` - Include this parameter to only return countries that have studies (note that these can be both released and unreleased studies). - `with_recent_studies` - Set to a number (X) to only return countries that have an available syndicated BAV study in - the last X calendar years. For example: When set to 0 it will return countries that have studies in the current year. - When set to 1 it will return countries that have studies in the current or past calendar year. + the last X calendar years. For example, when you set it to 0, it returns countries that have studies in the current year. + When you set it to 1, it returns countries that have studies in the current or past calendar year. - `with_recent_studies_incl_snap` - Works like `with_recent_studies`, but also counts custom and SnapBAV studies. - `in_best_countries` - Set to a comma-separated list of year numbers (e.g. `2023,2024`) to only return countries that are included in the Best Countries ranking for those years. diff --git a/docs/metadata/country-indicators.md b/docs/metadata/country-indicators.md index 36c76f9..7aa3572 100644 --- a/docs/metadata/country-indicators.md +++ b/docs/metadata/country-indicators.md @@ -13,7 +13,7 @@ To list all years of indicators for a country, use the list endpoint: GET /api/v2/countries/123/indicators ``` -Where `123` is the system ID of the country. You may also use the country's two-letter (ISO 3166-1 alpha-2) or +Where `123` is the system ID of the country. You can also use the country's two-letter (ISO 3166-1 alpha-2) or three-letter (ISO 3166-1 alpha-3) code instead of the ID: ```http request @@ -22,8 +22,8 @@ GET /api/v2/countries/GB/indicators ## Get the indicators for a year -You may also directly retrieve a country's indicators for a single year if you already have the system ID of -the [year](years.md). +If you already have the system ID of the [year](years.md), you can also get the indicators of a country for a single +year directly. ```http request GET /api/v2/countries/123/indicators/45 @@ -45,7 +45,7 @@ Each item in `indicators` contains: - `key` - The key of the indicator. See the list below. - `value` - The value of the indicator. Null if the figure is not available. -- `detailed_description` - A detailed description of the indicator, including its unit. +- `detailed_description` - A detailed description of the indicator, with its unit. - `simple_description` - A short description of the indicator. - `axis_label` - A label to use for the indicator on a chart axis. @@ -102,7 +102,7 @@ The list endpoint supports the following filters: - `updated_since` - Only return records updated on or after this date. See [filters](../customizing/filters.md). -You may sort by `id`, `created_at`, `updated_at`, any of the indicator keys, or by the year with `year.year`. For +You can sort by `id`, `created_at`, `updated_at`, any of the indicator keys, or by the year with `year.year`. For example, to get the most recent year first: ```http request diff --git a/docs/metadata/gics-sectors.md b/docs/metadata/gics-sectors.md index 1571c1c..d8198d1 100644 --- a/docs/metadata/gics-sectors.md +++ b/docs/metadata/gics-sectors.md @@ -2,14 +2,14 @@ ## What are GICS sectors? -The Global Industry Classification Standard is an industry taxonomy developed in 1999 by MSCI and Standard & Poor's for -use by the global financial community. +The Global Industry Classification Standard is an industry taxonomy. MSCI and Standard & Poor's developed it in 1999 +for use by the global financial community. We use them to classify companies and brands according to what they objectively do on a global basis. ## List all GICS sectors -To list all of the GICS sectors and browse them via the API, use the list endpoint: +To list all of the GICS sectors and browse them through the API, use the list endpoint: ```http request GET /api/v2/gics-sectors @@ -17,7 +17,7 @@ GET /api/v2/gics-sectors ## Get a GICS sector -You may also directly retrieve a GICS sector's details if you already have its system ID. +If you already have the system ID of a GICS sector, you can also get its details directly. ```http request GET /api/v2/gics-sectors/123 @@ -39,7 +39,7 @@ Where `123` is the system ID of the GICS sector. ### Relationship Response Schema -The slim relationship schema is used when the GICS sector is used as part of an include in another resource. +The API uses the slim relationship schema when the GICS sector is part of an include in another resource. | Key | Type | Description | |--------|---------|--------------------------------------| diff --git a/docs/metadata/operating-companies.md b/docs/metadata/operating-companies.md index 86a868d..f395594 100644 --- a/docs/metadata/operating-companies.md +++ b/docs/metadata/operating-companies.md @@ -2,14 +2,14 @@ ## What are operating companies? -The WPP organization consists of many operating companies. Each user in the platform generally belongs to an operating -company. Each operating company may belong to another operating company as a hierarchy. +The WPP organization consists of many operating companies. Usually, each user in the platform belongs to an operating +company. An operating company can belong to another operating company in a hierarchy. -In some cases an operating company may also have a brand, in which case it will have a brand relationship. +In some cases, an operating company also has a brand. In that case, it has a brand relationship. ## List all operating companies -To list all of the operating companies and browse them via the API, use the list endpoint: +To list all of the operating companies and browse them through the API, use the list endpoint: ```http request GET /api/v2/operating-companies @@ -17,7 +17,7 @@ GET /api/v2/operating-companies ## Get a operating company -You may also directly retrieve a operating company's details if you already have its system ID. +If you already have the system ID of an operating company, you can also get its details directly. ```http request GET /api/v2/operating-companies/123 @@ -38,11 +38,11 @@ Where `123` is the system ID of the operating company. ### Relationship Response Schema -The slim relationship schema is used when the operating company is used as part of an include in another resource. +The API uses the slim relationship schema when the operating company is part of an include in another resource. ## Additional Filters -For convenience, we have a set of additional filters that are not available in +For convenience, there are some additional filters that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: - `parents` - Set to a comma-separated list of operating company IDs to only return countries owned by those operating diff --git a/docs/metadata/regions.md b/docs/metadata/regions.md index 870a118..81b3675 100644 --- a/docs/metadata/regions.md +++ b/docs/metadata/regions.md @@ -2,7 +2,7 @@ ## What are regions? -Many of the BAV resources rely on segmenting data by country. Countries in turn belong to different geographical +Many of the BAV resources segment data by country. Countries in turn belong to different geographical regions. This resource contains a list of all the regions. These regions are world geographical regions according to @@ -10,7 +10,7 @@ the [United Nations geoscheme](https://en.wikipedia.org/wiki/United_Nations_geos ## List all regions -To list all of the regions and browse them via the API, use the list endpoint: +To list all of the regions and browse them through the API, use the list endpoint: ```http request GET /api/v2/regions @@ -18,7 +18,7 @@ GET /api/v2/regions ## Get a region -You may also directly retrieve a region's details if you already have its system ID. +If you already have the system ID of a region, you can also get its details directly. ```http request GET /api/v2/regions/123 @@ -39,7 +39,7 @@ Where `123` is the system ID of the region. ### Relationship Response Schema -The slim relationship schema is used when the region is used as part of an include in another resource. +The API uses the slim relationship schema when the region is part of an include in another resource. ## Relationships & includes @@ -47,7 +47,7 @@ By default, relationships apart from the sector are not included. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: -- `countries` - The [countries](countries.md) countries that are part of the region. +- `countries` - The [countries](countries.md) that are part of the region. ## Searching diff --git a/docs/metadata/sectors.md b/docs/metadata/sectors.md index e057a41..bed8c33 100644 --- a/docs/metadata/sectors.md +++ b/docs/metadata/sectors.md @@ -2,15 +2,15 @@ ## What are sectors? -When doing a BAV study, some questions are asked that relate sectors to one or more [categories](../studies/categories.md). You -can read more about the categories and what they represent on the [categories endpoint](../studies/categories.md). +In a BAV study, some questions relate sectors to one or more [categories](../studies/categories.md). For more +information about the categories and what they represent, see the [categories endpoint](../studies/categories.md). Each category belongs to a sector, which is a broader classification of categories. The benefit of a sector is that it is easier to compare across countries and years. ## List all sectors -To list all of the sectors and browse them via the API, use the list endpoint: +To list all of the sectors and browse them through the API, use the list endpoint: ```http request GET /api/v2/sectors @@ -18,7 +18,7 @@ GET /api/v2/sectors ## Get a sector -You may also directly retrieve a sector's details if you already have its system ID. +If you already have the system ID of a sector, you can also get its details directly. ```http request GET /api/v2/sectors/123 @@ -33,7 +33,7 @@ Where `123` is the system ID of the sector. | Key | Type | Filterable | Sortable | Configurable | Description | |---------------------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|--------------------------------------------------------------------------------| | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | -| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the sector should be seen and used. | +| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether you can see and use the sector. | | `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the sector. | | `excluded_for_most_influential` | - | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the sector should be part of the Most Influential brands lists or not. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this sector was first created. | @@ -41,7 +41,7 @@ Where `123` is the system ID of the sector. ### Relationship Response Schema -The slim relationship schema is used when the sector is used as part of an include in another resource. +The API uses the slim relationship schema when the sector is part of an include in another resource. | Key | Type | Description | |--------|---------|---------------------------------| @@ -50,7 +50,7 @@ The slim relationship schema is used when the sector is used as part of an inclu ## Additional Filters -For convenience, we have a set of additional filters that are not available in +For convenience, there are some additional filters that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: - `in_most_influential` - Set to `1` to only return sectors that are part of the Most Influential lists. diff --git a/docs/metadata/stock-exchanges.md b/docs/metadata/stock-exchanges.md index fdb104d..0fbc7bf 100644 --- a/docs/metadata/stock-exchanges.md +++ b/docs/metadata/stock-exchanges.md @@ -6,7 +6,7 @@ Stock Exchanges are the entities where public [companies](../company-data/compan ## List all stock exchanges -To list all of the stock exchanges and browse them via the API, use the list endpoint: +To list all of the stock exchanges and browse them through the API, use the list endpoint: ```http request GET /api/v2/stock-exchanges @@ -14,7 +14,7 @@ GET /api/v2/stock-exchanges ## Get a stock exchange -You may also directly retrieve a stock exchange's details if you already have its system ID. +If you already have the system ID of a stock exchange, you can also get its details directly. ```http request GET /api/v2/stock-exchanges/123 @@ -31,7 +31,7 @@ Where `123` is the system ID of the stock exchange. | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | | `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the stock exchange. | | `code` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The code for the stock exchange. | -| `suffix` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The stock suffix when part of this stock exchange. | +| `suffix` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The stock suffix for stocks on this stock exchange. | | `operating_mic` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The operating Market Identifier Code for the stock exchange. | | `currency` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The reporting currency used by the exchange. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this stock exchange was first created. | @@ -39,19 +39,19 @@ Where `123` is the system ID of the stock exchange. ### Relationship Response Schema -The slim relationship schema is used when the stock exchange is used as part of an include in another resource. +The API uses the slim relationship schema when the stock exchange is part of an include in another resource. | Key | Type | Description | |-----------------|---------|--------------------------------------------------------------| | `id` | integer | The system ID for the stock exchange. | | `name` | string | The name of the stock exchange. | | `code` | string | The code for the stock exchange. | -| `suffix` | string | The stock suffix when part of this stock exchange. | +| `suffix` | string | The stock suffix for stocks on this stock exchange. | | `operating_mic` | string | The operating Market Identifier Code for the stock exchange. | ## Additional Filters -For convenience, we have a set of additional filters that are not available in +For convenience, there are some additional filters that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: - `countries` - A comma-separated list of country IDs to only return stock exchanges in those countries. diff --git a/docs/metadata/tools.md b/docs/metadata/tools.md index 756bb72..008e169 100644 --- a/docs/metadata/tools.md +++ b/docs/metadata/tools.md @@ -2,13 +2,13 @@ ## What are tools? -The tools endpoint provides a list of all the available tools in the system and the parameters they expect. It can -be used for various integrations as it provides the metadata for each tool. You can then use the specific tools +The tools endpoint gives a list of all the available tools in the system and the parameters that they expect. You +can use it for different integrations, because it gives the metadata for each tool. You can then use the specific tools endpoints to get the data for most tools. ## List all tools -To list all of the tools and browse them via the API, use the list endpoint: +To list all of the tools and browse them through the API, use the list endpoint: ```http request GET /api/v2/tools @@ -16,7 +16,7 @@ GET /api/v2/tools ## Get a year -You may also directly retrieve a year's details if you already have its system ID. +If you already have the system ID of a year, you can also get its details directly. ```http request GET /api/v2/tools/123 @@ -40,8 +40,8 @@ Where `123` is the system ID of the year. | `api_endpoint_url` | string | :x: | :x: | :white_check_mark: | The URL to the API endpoint for the tool, if available. | | `supported_parameters` | object | :x: | :x: | :white_check_mark: | The filter parameters that the tool supports. The object key is the parameter name, and the value is true/false. | | `required_parameters` | object | :x: | :x: | :white_check_mark: | The required parameters for the tool. The object key is the parameter name, and the value is true/false. | -| `multiple_choice_parameters` | object | :x: | :x: | :white_check_mark: | The parameters which allow for more than one selection. The object key is the parameter name, and the value is true/false. | -| `extra_parameters` | object | :x: | :x: | :white_check_mark: | Additional configuration parameters to control the querying experience. | +| `multiple_choice_parameters` | object | :x: | :x: | :white_check_mark: | The parameters that allow more than one selection. The object key is the parameter name, and the value is true/false. | +| `extra_parameters` | object | :x: | :x: | :white_check_mark: | Additional configuration parameters that control the query experience. | | `export_formats` | object | :x: | :x: | :white_check_mark: | The available exports in the interface. The object key is the parameter name, and the value is true/false. Only available exports are listed. | | `is_in_preview` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | If true, the tool is currently unreleased but the user still has access to it under a "preview access" scheme. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this year was first created. | diff --git a/docs/metadata/years.md b/docs/metadata/years.md index d4eded6..124c62b 100644 --- a/docs/metadata/years.md +++ b/docs/metadata/years.md @@ -2,11 +2,11 @@ ## What are years? -We use a years resource to tie together all of the data that we have for a given year and to make it easily queryable. +We use a years resource to connect all of the data that we have for a given year. It also makes this data easy to query. ## List all years -To list all of the years and browse them via the API, use the list endpoint: +To list all of the years and browse them through the API, use the list endpoint: ```http request GET /api/v2/years @@ -14,7 +14,7 @@ GET /api/v2/years ## Get a year -You may also directly retrieve a year's details if you already have its system ID. +If you already have the system ID of a year, you can also get its details directly. ```http request GET /api/v2/years/123 @@ -36,7 +36,7 @@ Where `123` is the system ID of the year. ### Relationship Response Schema -The slim relationship schema is used when the year is used as part of an include in another resource. +The API uses the slim relationship schema when the year is part of an include in another resource. | Key | Type | Description | |--------|---------|-----------------------------| diff --git a/docs/metrics/metric-groups.md b/docs/metrics/metric-groups.md index b1cbe83..5bee333 100644 --- a/docs/metrics/metric-groups.md +++ b/docs/metrics/metric-groups.md @@ -2,12 +2,12 @@ ## What are brand metric groups? -When BAV studies a brand it does so on a variety of [metrics](metrics.md). These metrics are divided into groups. Each +When BAV studies a brand, it uses many different [metrics](metrics.md). BAV divides these metrics into groups. Each group relates to a specific way to look at a brand, or to a BAV model. ## List all brand metric groups -To list all of the brand metric groups and browse them via the API, use the list endpoint: +To list all of the brand metric groups and browse them through the API, use the list endpoint: ```http request GET /api/v2/brand-metric-groups @@ -15,7 +15,7 @@ GET /api/v2/brand-metric-groups ## Get a brand metric group -You may also directly retrieve a brand metric group's details if you already have its system ID. +If you already have the system ID of a brand metric group, you can also get its details directly. ```http request GET /api/v2/brand-metric-groups/123 @@ -32,14 +32,14 @@ Where `123` is the system ID of the brand metric group. | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | | `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The primary name of the group. | | `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A machine-readable name for the group. Used by the `metric_group_keys` parameter on [brandscape data](../brand-data/brandscape-data.md). | -| `description` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A short description on what this group is about. | +| `description` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A short description of what this group is about. | | `is_public` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the group is publicly available for all users. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this group was first created. | | `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this group was last updated. | ### Relationship Response Schema -The slim relationship schema is used when the brand metric group is used as part of an include in another resource. +The API uses the slim relationship schema when the brand metric group is part of an include in another resource. | Key | Type | Description | |--------|---------|--------------------------------| @@ -48,7 +48,7 @@ The slim relationship schema is used when the brand metric group is used as part ## Additional Filters -For convenience, we have a set of additional filters for brand metric groups that are not available in +For convenience, there are some additional filters for brand metric groups that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: - `public` - Set to `1` to only return public groups. diff --git a/docs/metrics/metrics.md b/docs/metrics/metrics.md index eea9de4..c184566 100644 --- a/docs/metrics/metrics.md +++ b/docs/metrics/metrics.md @@ -2,12 +2,12 @@ ## What are brand metrics? -When BAV studies a brand it does so on a variety of metrics. These metrics are divided +When BAV studies a brand, it uses many different metrics. BAV divides these metrics into [groups](metric-groups.md). Each group relates to a specific way to look at a brand, or to a BAV model. ## List all brand metrics -To list all of the brand metrics and browse them via the API, use the list endpoint: +To list all of the brand metrics and browse them through the API, use the list endpoint: ```http request GET /api/v2/brand-metrics @@ -15,7 +15,7 @@ GET /api/v2/brand-metrics ## Get a brand metric -You may also directly retrieve a brand metric's details if you already have its system ID. +If you already have the system ID of a brand metric, you can also get its details directly. ```http request GET /api/v2/brand-metrics/123 @@ -32,11 +32,11 @@ Where `123` is the system ID of the brand metric. | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | | `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A machine-readable key for the metric. Brandscape data fields are named after it. | | `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The primary name of the metric. | -| `description` | string | :x: | :x: | :white_check_mark: | A short description on what this metric is about. | +| `description` | string | :x: | :x: | :white_check_mark: | A short description of what this metric is about. | | `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | If the metric is active or deprecated. | | `is_public` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric is publicly available for all users. | | `is_core` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric is part of the core set of BAV metrics. | -| `is_legacy` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric has been discontinued and will not available in new studies. | +| `is_legacy` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric has been discontinued and will not be available in new studies. | | `has_construct_score` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric has a construct score available. | | `has_percentile_rank_score` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric has a percentile rank score available. | | `has_percentage_score` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the metric has a percentage score available. | @@ -48,7 +48,7 @@ Where `123` is the system ID of the brand metric. ### Relationship Response Schema -The slim relationship schema is used when the brand metric is used as part of an include in another resource. +The API uses the slim relationship schema when the brand metric is part of an include in another resource. | Key | Type | Description | |-------------|---------|----------------------------------------| @@ -58,14 +58,14 @@ The slim relationship schema is used when the brand metric is used as part of an ## Additional Filters -For convenience, we have a set of additional filters for brand metrics that are not available in +For convenience, there are some additional filters for brand metrics that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: - `active` - Set to `1` to only return active metrics. - `inactive` - Set to `1` to only return inactive metrics. - `public` - Set to `1` to only return public metrics. - `private` - Set to `1` to only return private metrics. -- `group` - A comma-separated list of [brand metric group](metric-groups.md) IDs. This will only return metrics that +- `group` - A comma-separated list of [brand metric group](metric-groups.md) IDs. The API returns only the metrics that belong to the specified groups. - `current` - Set to `1` to only return metrics that are in use in studies today. - `legacy` - Set to `1` to only return legacy metrics. diff --git a/docs/studies/categories.md b/docs/studies/categories.md index 4e04729..981517c 100644 --- a/docs/studies/categories.md +++ b/docs/studies/categories.md @@ -6,7 +6,8 @@ split: true ## What are categories? -Categories in BAV are related to how the respondent is asked their relationship to a brand in three sections only: +In BAV, categories relate only to the three sections where the survey asks respondents about their relationship to a +brand: - Usage - Preference @@ -14,11 +15,11 @@ Categories in BAV are related to how the respondent is asked their relationship All other BAV scores are the same across categories, which is a fundamental part of BAV's category-agnostic model. -These categories are therefore, a way to relate a brand to usage and not a way to define what a brand is. For example, -you might be interested to know how respondents see and use Google as both a search engine and advertiser, which would -be two distinct categories, yet does not attempt to classify what Google objectively is. +For this reason, these categories are a way to relate a brand to usage. They are not a way to define what a brand is. +For example, you want to know how respondents see and use Google as a search engine and as an advertiser. These are two +distinct categories, but they do not try to classify what Google objectively is. -This also means that the amount of brands in a category may change slightly across years and greatly across markets. +This also means that the number of brands in a category can change slightly across years and greatly across markets. Not all categories are available in all years and markets. ## List Categories @@ -31,7 +32,7 @@ GET /api/v2/categories ## Get a Category -You may also directly retrieve a category's details if you already have its system ID. +If you already have the system ID of a category, you can also get its details directly. ```http request GET /api/v2/categories/123 @@ -54,7 +55,7 @@ The categories endpoints are read-only and require a token with the `bav:brand-d ### Relationship Response Schema -The slim relationship schema is used when the category is used as part of an include in another resource. +The API uses the slim relationship schema when the category is part of an include in another resource. | Key | Type | Description | |--------|---------|-----------------------------------| @@ -66,10 +67,10 @@ also contains a `sector` object. ## Additional Filters -For convenience, we have a set of additional filters for categories that are not available in +For convenience, there are some additional filters for categories that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: -- `sectors` - A comma-separated list of sector IDs. This will filter the categories to only those in the given sectors. +- `sectors` - A comma-separated list of sector IDs. The API filters the categories to only those in the given sectors. ## Relationships & includes diff --git a/docs/studies/studies.md b/docs/studies/studies.md index 6c1e77d..6308a55 100644 --- a/docs/studies/studies.md +++ b/docs/studies/studies.md @@ -2,18 +2,18 @@ ## What are studies? -A fundamental element of our datasets are studies. A study is a collection of data from respondents in one market at a -specific point in time. Most markets in BAV are for example covered at most once a year with the exception of the US -which is done quarterly. +Studies are a fundamental element of our datasets. A study is a collection of data from respondents in one market at a +specific point in time. For example, BAV covers most markets at most once a year. The exception is the US, which BAV +covers quarterly. -Studies are a primary way of filtering our [brandscape data](../brand-data/brandscape-data.md) and also contains +Studies are a primary way to filter our [brandscape data](../brand-data/brandscape-data.md). A study also contains information about the study itself, such as when it was conducted and how many respondents it had. -You only see the studies you have access to. The studies endpoints are read-only. +You see only the studies that you have access to. The studies endpoints are read-only. ## List all studies -To list all of the studies and browse them via the API, use the list endpoint: +To list all of the studies and browse them through the API, use the list endpoint: ```http request GET /api/v2/studies @@ -21,7 +21,7 @@ GET /api/v2/studies ## Get a study -You may also directly retrieve a study's details if you already have its system ID. +If you already have the system ID of a study, you can also get its details directly. ```http request GET /api/v2/studies/123 @@ -31,19 +31,19 @@ Where `123` is the system ID of the study. ## Get brands in a study -You may get a list of all brands in a study by using the following endpoint: +To get a list of all brands in a study, use the following endpoint: ```http request GET /api/v2/studies/123/brands ``` -Where `123` is the system ID of the study. A brand measured in several categories appears once per category. Returns -`404` if the study does not exist or you do not have access to it. This endpoint requires a token with the `bav:brand-data` +Where `123` is the system ID of the study. A brand measured in several categories appears once per category. If the +study does not exist or you do not have access to it, the endpoint returns `404`. This endpoint requires a token with the `bav:brand-data` scope. ## Get categories in a study -You may get a list of the categories in a study by using the following endpoint: +To get a list of the categories in a study, use the following endpoint: ```http request GET /api/v2/studies/123/categories @@ -71,18 +71,18 @@ relationship schema) describe it. :::note The standard BAV study was previously labelled "Syndicated". Its label is now "BAV (Standard)", but its slug is still -`syndicated`, so existing `study_types` filters keep working. +`syndicated`, so existing `study_types` filters continue to work. ::: ## Methodologies Each study is run on a methodology, the version of the BAV model that decides how its metrics are calculated. Use the -`methodology` include to get it. Metrics are calculated differently between methodologies, so take care when comparing +`methodology` include to get it. Metrics are calculated differently between methodologies. Be careful when you compare studies that were run on different ones. -Methodologies have a stable `key` and a display `name`. The names were changed in October 2026; the keys did not -change, so use the `key` rather than the name to tell methodologies apart. +Methodologies have a stable `key` and a display `name`. The names changed in October 2026. The keys did not +change, so use the `key` and not the name to identify a methodology. | `key` | Name | Previous name | |-------------------|----------------------|---------------| @@ -122,7 +122,7 @@ change, so use the `key` rather than the name to tell methodologies apart. ### Relationship Response Schema -The slim relationship schema is used when the study is used as part of an include in another resource. +The API uses the slim relationship schema when the study is part of an include in another resource. | Key | Type | Description | |--------------------|---------|------------------------------------------------------------------------------------------| @@ -142,13 +142,13 @@ The schema used for the `methodology` include. | Key | Type | Description | |---------------|---------|----------------------------------------------------------------------------------------------| | `id` | integer | The system ID for the methodology. | -| `key` | string | The stable methodology key, e.g. `v2025-2`. Use this rather than the name to tell them apart. | +| `key` | string | The stable methodology key, e.g. `v2025-2`. Use this and not the name to identify a methodology. | | `name` | string | The methodology name, e.g. `BAV 3 (Default)`. | | `description` | string | What the methodology is and how it differs from the other versions. | ### Brands in Study Schema -When getting the brands included in a study, the following schema is used: +When you get the brands in a study, the API uses the following schema: | Key | Type | Filterable | Sortable | Configurable | Description | |--------------|---------|:-----------------------------------------:|:------------------:|:------------------:|---------------------------------------------------------| @@ -159,7 +159,7 @@ When getting the brands included in a study, the following schema is used: ### Categories in Study Schema -When getting the categories included in a study, the following schema is used: +When you get the categories in a study, the API uses the following schema: | Key | Type | Filterable | Sortable | Configurable | Description | |--------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-------------------------------------------------------------------------------------| @@ -200,13 +200,13 @@ The category is always included. The following additional relationships are avai ## Additional filters -For convenience, we have a set of additional filters for studies that are not available in +For convenience, there are some additional filters for studies that are not available in the [default filters](../customizing/filters.md) or are part of the columns. These are: - `study_types` - A comma-separated list of study type slugs: `syndicated` (BAV Standard), `custom` (Kaleidoscope and - Consumer Eye), `snap` (SnapBAV) or `fused` (AO+BAV Fused). Unknown slugs are ignored. Use the `type` filter to filter + Consumer Eye), `snap` (SnapBAV) or `fused` (AO+BAV Fused). The API ignores unknown slugs. Use the `type` filter to filter by type number instead. -- `data_updated_since` - A date string. This will filter the studies to only those that have had their data updated +- `data_updated_since` - A date string. The API filters the studies to only those that have had their data updated since the given date. Unlike `updated_since`, this ignores changes to the study's details. - `active` - Set to `1` to only return active studies. - `inactive` - Set to `1` to only return inactive studies. @@ -215,14 +215,14 @@ the [default filters](../customizing/filters.md) or are part of the columns. The - `unreleased` - Set to `1` to only return active studies that have not been released yet. - `full_year` - Set to `1` to only return full year studies (period `1`, excludes US quarterly waves). - `open_survey` - Set to `1` to only return studies with an open brand selection survey. -- `regions` - A comma-separated list of region IDs. This will filter the studies to only those that are in the given +- `regions` - A comma-separated list of region IDs. The API filters the studies to only those that are in the given regions. -- `countries` - A comma-separated list of country IDs. This will filter the studies to only those that are in the given +- `countries` - A comma-separated list of country IDs. The API filters the studies to only those that are in the given countries. -- `country_codes` - A comma-separated list of two-letter ISO country codes. This will filter the studies to only those +- `country_codes` - A comma-separated list of two-letter ISO country codes. The API filters the studies to only those that are in the given countries. -- `years` - A comma-separated list of year IDs. This will filter the studies to only those that are in the given years. -- `year_numbers` - A comma-separated list of year numbers. This will filter the studies to only those that are in the +- `years` - A comma-separated list of year IDs. The API filters the studies to only those that are in the given years. +- `year_numbers` - A comma-separated list of year numbers. The API filters the studies to only those that are in the given years. For the scope filters (`active`, `inactive`, `bav_study`, `released`, `unreleased`, `full_year` and `open_survey`), any @@ -230,27 +230,27 @@ value turns the filter on. ### For brands in a study -The following additional filters are available when fetching brands for a given study: +The following additional filters are available when you get brands for a given study: -- `categories` - A comma-separated list of category IDs. This will filter the brands to only those that are studied in +- `categories` - A comma-separated list of category IDs. The API filters the brands to only those that are studied in the specified categories. -- `brands` - A comma-separated list of brand IDs. This will filter the brands to only the ones provided. -- `brandVariations` - A comma-separated list of brand variation IDs. This will filter the brands to only those measured +- `brands` - A comma-separated list of brand IDs. The API filters the brands to only the ones provided. +- `brandVariations` - A comma-separated list of brand variation IDs. The API filters the brands to only those measured under the given variations. ### For categories in a study -The following additional filters are available when fetching categories for a given study: +The following additional filters are available when you get categories for a given study: -- `categories` - A comma-separated list of category IDs. This will filter the categories to only those given. -- `brands` - A comma-separated list of brand IDs. This will filter the categories to only those that have the given +- `categories` - A comma-separated list of category IDs. The API filters the categories to only those given. +- `brands` - A comma-separated list of brand IDs. The API filters the categories to only those that have the given brands in the study. -- `brand_variations` - A comma-separated list of brand variation IDs. This will filter the categories to only those +- `brand_variations` - A comma-separated list of brand variation IDs. The API filters the categories to only those that have the given brand variations in the study. :::caution Filter naming -The brand variation filter is named differently on the two endpoints: it is `filter[brandVariations]` (camelCase) on +The brand variation filter has a different name on the two endpoints. It is `filter[brandVariations]` (camelCase) on `/studies/{id}/brands` and `filter[brand_variations]` (snake_case) on `/studies/{id}/categories`. Likewise, the include for the brand variation on `/studies/{id}/brands` is `brandVariation`. From b5979aabb173f1dffb514baa5233e7fa0169c822 Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sun, 25 Oct 2026 10:33:34 +0100 Subject: [PATCH 18/23] Rewrite AI and MCP docs in Simplified Technical English Co-Authored-By: Claude Opus 5.5 --- docs/ai/agents.md | 28 +- docs/ai/intro.md | 25 +- docs/ai/mcp/access-authorization.md | 93 +++--- docs/ai/mcp/bav.md | 188 ++++++------ docs/ai/mcp/best-countries.md | 68 ++--- docs/ai/mcp/concepts.md | 117 ++++---- docs/ai/mcp/connecting-clients.md | 135 +++++---- docs/ai/mcp/financial-data.md | 66 +++-- docs/ai/mcp/intro.md | 40 ++- docs/ai/mcp/market-share.md | 115 ++++---- docs/ai/mcp/mcp-apps.md | 54 ++-- docs/ai/mcp/social.md | 438 ++++++++++++++-------------- 12 files changed, 694 insertions(+), 673 deletions(-) diff --git a/docs/ai/agents.md b/docs/ai/agents.md index ed81c47..b3b39b0 100644 --- a/docs/ai/agents.md +++ b/docs/ai/agents.md @@ -4,27 +4,25 @@ sidebar_label: Agents # BAV Agents -BAV Agents are specialized AI agents designed to assist users in various tasks by leveraging advanced natural language -processing capabilities. These agents can understand user queries, provide relevant information, and perform actions -based on user instructions. +BAV Agents are specialized AI agents that help users with different tasks. They use advanced natural language +processing. These agents can understand user queries, give relevant information, and do actions from user instructions. ## WPP Open & Creative Studio -Our set of pre-made BAV agents are available in WPP Open and the Agent Hub. These agents can be run standalone or be -combined into more complex workflows and other data sources to create powerful AI-driven analysis. +Our set of pre-made BAV agents is available in WPP Open and the Agent Hub. You can run these agents standalone. You can +also combine them into more complex workflows, and with other data sources, to make powerful AI-driven analysis. -Our core agent, the Brand Analytics Agent, is a free chat agent that allows users to interact with the BAV dataset in a -natural language format. Users can ask questions about brand performance, consumer insights, and market trends, and -receive detailed responses based on the BAV data. +Our core agent, the Brand Analytics Agent, is a free chat agent. Users can use it to ask about the BAV dataset in +natural language. Users can ask about brand performance, consumer insights, and market trends. The agent gives detailed +responses from the BAV data. -In addition to the Brand Analytics Agent, we offer a variety of specialized agents that focus on specific aspects of brand -analysis. These agents can help users with tasks such as competitive analysis, consumer sentiment analysis, and -market segmentation. +We also have a range of specialized agents for specific parts of brand analysis. These agents can help users with tasks +such as competitive analysis, consumer sentiment analysis, and market segmentation. -Please [get in touch with us](mailto:bavsupport@wpp.com) for access to these agents. +To get access to these agents, [contact us](mailto:bavsupport@wpp.com). ## Building your own agents -If you want to build your own agents, you can connect them directly to BAV data using our -[MCP servers](mcp/intro.md). In WPP Open, the MCP servers are available as tools in the Creative Studio agent builder, -see [connecting clients](mcp/connecting-clients.md#wpp-open). +If you want to build your own agents, you can connect them directly to BAV data with our +[MCP servers](mcp/intro.md). In WPP Open, the MCP servers are available as tools in the Creative Studio agent builder. +Refer to [connecting clients](mcp/connecting-clients.md#wpp-open). diff --git a/docs/ai/intro.md b/docs/ai/intro.md index 7df887d..37347c6 100644 --- a/docs/ai/intro.md +++ b/docs/ai/intro.md @@ -4,22 +4,19 @@ sidebar_label: Introduction # BAV in an Agentic World -At WPP BAV we are committed to building the infrastructure to support the next generation of applications powered by AI. -Our goal is to create a platform that empowers developers across the group to come up with innovative solutions that -leverage the power of AI through our bespoke data and models. +At WPP BAV, we build the infrastructure for the next generation of applications that use AI. Our goal is a platform +that helps developers across the group to make new solutions with AI and our bespoke data and models. -A new era requires new tools. While our existing API is great, we recognize that it may not be the best fit for -all agentic applications. That's why we are committed to improving it and making it suitable for the next -generation of use cases. +A new era needs new tools. Our current API works well, but it is possibly not the best fit for all agentic +applications. Thus, we will continue to improve it for the next generation of use cases. -If you are building an AI application and using our APIs, don't hesitate to reach out so that we can -collaborate on improvements and additions that will benefit the entire group. +If you build an AI application with our APIs, contact us. We can then work together on improvements and additions +that help the full group. ## BAV Agents -Our BAV agents powered by Creative Studio and WPP Open enable you to easily integrate BAV data into your own agent -workflows. This offers a quick way to leverage BAV expertise and insights without the overhead of managing requests to -an MCP server. +Our BAV agents use Creative Studio and WPP Open. With these agents, you can add BAV data to your own agent workflows. +They give you fast access to BAV expertise and insights, and you do not have to manage requests to an MCP server. You can use the agents standalone or as part of a larger agentic team. @@ -27,8 +24,8 @@ You can use the agents standalone or as part of a larger agentic team. ## MCP Servers -Your AI models and agents can use the official BAV MCP servers to access BAV data, Best Countries, financial data and -Euromonitor market share data in both a simple and secure way. The servers work with any MCP client that supports -remote servers, including Claude, ChatGPT, Copilot and the agent builder in WPP Open. +Your AI models and agents can use the official BAV MCP servers to get BAV data, Best Countries data, financial data and +Euromonitor market share data. The servers are simple and secure. They work with all MCP clients that support remote +servers, for example Claude, ChatGPT, Copilot and the agent builder in WPP Open. [Read more](mcp/intro.md) diff --git a/docs/ai/mcp/access-authorization.md b/docs/ai/mcp/access-authorization.md index 86dc27b..b87699a 100644 --- a/docs/ai/mcp/access-authorization.md +++ b/docs/ai/mcp/access-authorization.md @@ -6,59 +6,59 @@ sidebar_label: Access & Authorization ## Access (as a user) -Everyone with a WPP Okta account has access to the MCP servers. When you connect to it you will be asked to sign in and -authorize your AI application to access the data on your behalf. +All users with a WPP Okta account have access to the MCP servers. When you connect to a server, you must sign in. You +must then authorize your AI application to get the data on your behalf. :::warning Authorized Agent Environments -Please note that you may only connect to the BAV MCP server from authorized agent environments that have been -vetted by WPP legal. This is to ensure the data security and compliance around our proprietary data. If you are -not sure whether your environment is authorized, please reach out. +Connect to the BAV MCP server only from authorized agent environments that WPP legal approved. This makes sure of the +data security and compliance of our proprietary data. If you are not sure that your environment is authorized, contact +us. ::: ### Tools depend on your permissions -The tools on each server are permission-gated per user. When your AI application lists the tools on a server, it only -sees the tools that you have access to. This means that two users connecting to the same server may see different tool -lists. For example, the [Market Share server](./market-share.md) requires access to Euromonitor data, and the city tools -on the [Best Countries server](./best-countries.md) require access to Best Countries city data. +Each server controls access to its tools with the permissions of each user. When your AI application lists the tools +on a server, it sees only the tools that you have access to. Thus, two users who connect to the same server can see +different tool lists. For example, the [Market Share server](./market-share.md) requires access to Euromonitor data. The +city tools on the [Best Countries server](./best-countries.md) require access to Best Countries city data. -If you are missing a tool you expected to see, please [get in touch with us](mailto:bavsupport@wpp.com). +If you do not see a tool that you expected, [contact us](mailto:bavsupport@wpp.com). ## Authorization (for developers) -These instructions cover how authorization works and is geared towards a developer integrating an AI model or agent with -our MCP servers. +These instructions explain how authorization works. They are for developers who connect an AI model or agent to our +MCP servers. ### OAuth -All our MCP servers work with OAuth 2.0 using the +All our MCP servers work with OAuth 2.0 and the standard [MCP authorization flow](https://modelcontextprotocol.io/docs/tutorials/security/authorization). Most MCP -clients handle this flow for you automatically, so you only need to provide the server URL. +clients do this flow for you automatically. Thus, you only need to give the server URL. -We highly recommend OAuth as the authorization mechanism as it allows you to act as the user and access data on their +We strongly recommend OAuth as the authorization mechanism. With OAuth, you can act as the user and get data on their behalf. The servers support the discovery and registration mechanisms in the MCP specification: -- **Protected resource metadata:** An unauthenticated request returns a `401` with a `WWW-Authenticate` header that - points to the protected resource metadata at `/.well-known/oauth-protected-resource`. -- **Authorization server metadata:** The authorization, token and registration endpoints are published at +- **Protected resource metadata:** An unauthenticated request returns a `401` with a `WWW-Authenticate` header. This + header points to the protected resource metadata at `/.well-known/oauth-protected-resource`. +- **Authorization server metadata:** The authorization, token and registration endpoints are available at `/.well-known/oauth-authorization-server`. -- **Dynamic client registration:** Clients can register themselves using the registration endpoint, so you do not need - to create an OAuth client up front. +- **Dynamic client registration:** Clients can register themselves with the registration endpoint. Thus, you do not + need to create an OAuth client before you start. -MCP clients use the authorization code grant with PKCE (`S256`), and refresh tokens are supported. Dynamic client -registration is only available to MCP clients. OAuth clients that you create for an application in The Fount are -confidential clients with a client secret, see [OAuth 2](../../authentication.md#oauth-2). +MCP clients use the authorization code grant with PKCE (`S256`). The servers support refresh tokens. Dynamic client +registration is available only to MCP clients. The OAuth clients that you create for an application in The Fount are +confidential clients with a client secret. Refer to [OAuth 2](../../authentication.md#oauth-2). ### Personal Access Tokens -You may also use personal access tokens, but please note that they are tied to a specific user and do not allow -your application to act on behalf of other users. Personal access tokens can be created from +You can also use personal access tokens. But a personal access token is tied to one specific user. Your application +cannot use it to act on behalf of other users. You can create personal access tokens in the [API section in The Fount](https://fount.wppbav.com/api). -If you are using a personal access token, just pass it as a Bearer token in the Authorization header when making -requests to the MCP server: +If you use a personal access token, send it as a Bearer token in the Authorization header of your requests to the MCP +server: ``` Authorization: Bearer YOUR_API_KEY @@ -66,19 +66,20 @@ Authorization: Bearer YOUR_API_KEY ### Applications -If you are building an application, you can create one yourself under **Applications** in the -[API section in The Fount](https://fount.wppbav.com/api). Applications can authenticate in a few different ways: +If you build an application, you can create it yourself under **Applications** in the +[API section in The Fount](https://fount.wppbav.com/api). Applications can authenticate in some different ways: -- **OAuth on behalf of a user:** Users authorize your application through the OAuth flow, and your application acts on +- **OAuth on behalf of a user:** Users authorize your application through the OAuth flow. Your application then acts on their behalf with their permissions. -- **Application API keys:** An API key belonging to the application itself. Requests are made as the application, with - the access that has been set up for it. -- **Client credentials:** A token requested with the OAuth client credentials grant. It works like an application API - key, is limited to the client's scopes and lasts one hour. +- **Application API keys:** An API key that belongs to the application. The application sends requests as itself, with + the access that we set up for it. +- **Client credentials:** A token that you request with the OAuth client credentials grant. It works like an + application API key. It is limited to the scopes of the client and is valid for one hour. -Applications that we have marked as trusted and approved to act on behalf of users can pass the e-mail address of a -user in the `X-Act-As-User` header, together with an application API key or a client credentials token. The token must -explicitly include the `act-as-user` scope. The request is then made as that user, with their permissions. +Some applications have our trusted mark and our approval to act on behalf of users. These applications can send the +e-mail address of a user in the `X-Act-As-User` header, with an application API key or a client credentials token. The +token must explicitly include the `act-as-user` scope. The request then occurs as that user, with the permissions of +that user. ``` Authorization: Bearer YOUR_APPLICATION_TOKEN @@ -86,16 +87,18 @@ X-Act-As-User: jane.doe@wpp.com ``` :::note -Tokens issued to a user, whether through OAuth or as a personal access token, can't act as another user. +A token that belongs to a user cannot act as another user. This applies to OAuth tokens and personal access tokens. ::: Applications can use two separate IP lists: -- **Allowed API IP addresses** restrict where API and MCP calls can come from. When set, every request the application - makes, whether as itself or on behalf of a user, must come from one of those addresses. This also applies when - requesting a token with the client credentials grant. -- **Trusted IP addresses** are used for trusted internal applications to skip the consent screen. Consent is only - skipped when the user's browser is on one of these addresses. We recommend this for internal tools as it gives a - smoother experience. Please reach out if you would like your application to be trusted. +- **Allowed API IP addresses** limit the locations that API and MCP calls can come from. If you set this list, all + requests from the application must come from one of those addresses. This applies to requests that the application + sends as itself and on behalf of a user. It also applies when the application requests a token with the client + credentials grant. +- **Trusted IP addresses** let trusted internal applications skip the consent screen. The consent screen is skipped + only when the browser of the user is on one of these addresses. We recommend this for internal tools because it gives + a better user experience. If you want us to make your application trusted, contact us. -See the [authentication documentation](../../authentication.md) for more information on applications and tokens. +For more information about applications and tokens, refer to the +[authentication documentation](../../authentication.md). diff --git a/docs/ai/mcp/bav.md b/docs/ai/mcp/bav.md index 11a736b..9da301f 100644 --- a/docs/ai/mcp/bav.md +++ b/docs/ai/mcp/bav.md @@ -4,65 +4,65 @@ sidebar_label: BAV Server # BAV MCP Server -The BAV MCP Server provides access to the WPP BAV proprietary brand data through a set of tools that can be -called by AI agents. This allows you to build AI applications that can leverage the rich brand data collected -by BAV to provide insights, recommendations, and analysis. +The BAV MCP Server gives access to the WPP BAV proprietary brand data through a set of tools that AI agents can call. +With these tools, you can build AI applications that use the large set of BAV brand data. These applications can give +insights, recommendations, and analysis. -The tools (see below) span research data on brands, metadata around coverage and taxonomy, audiences, collections, -AURA (AI brand research), media performance and interactive charts. +The tools (refer to the sections below) include research data on brands, metadata about coverage and taxonomy, +audiences, collections, AURA (AI brand research), media performance and interactive charts. ## Connecting to the server -Our remote MCP server supports Streamable HTTP. To connect to the BAV MCP server, you need to use the following URL: +Our remote MCP server supports Streamable HTTP. To connect to the BAV MCP server, use this URL: ``` https://mcp-beta.wppbav.com/v1/bav ``` :::note -The domain will change to `mcp.wppbav.com` in the future. We'll communicate this change in advance with a good notice -period so you can update your applications accordingly. +The domain will change to `mcp.wppbav.com` in the future. We will tell you about this change a sufficient time before +it occurs, so that you can update your applications. ::: -For authorization, please see the [access and authorization](./access-authorization.md) section. +For authorization, refer to the [access and authorization](./access-authorization.md) section. -If you are building an agent on top of the server, we recommend reading [Concepts for agents](./concepts.md) as well. It -explains how studies, score types and data generation work, which is what most agents trip over. +If you build an agent on the server, we also recommend that you read [Concepts for agents](./concepts.md). It explains +how studies, score types and data generation work. Most agents have problems with these concepts. ## Available Tools -The tools are grouped by the job they do: +The tools are in groups by their function: - **Metadata and lookup tools:** Find brands, markets, studies, sectors, categories, audiences and metric definitions. -- **Brand data tools:** Fetch the BAV brand data itself, one data model per tool. +- **Brand data tools:** Get the BAV brand data, one data model for each tool. - **Collection tools:** Create, update and share brand collections. -- **Audience tools:** Build, deploy and size audiences, and read how a population answered survey questions. -- **AURA tools:** How large language models perceive brands, and how that differs from consumers. +- **Audience tools:** Build, deploy and find the size of audiences. Read how a population answered survey questions. +- **AURA tools:** How large language models perceive brands, and how this is different from consumers. - **Media performance tools:** Campaign performance data and benchmarks. -- **Display tools:** Render interactive charts in clients that support [MCP Apps](./mcp-apps.md). +- **Display tools:** Show interactive charts in clients that support [MCP Apps](./mcp-apps.md). ### Which tools you will see -Each tool is only registered for users who have permission to use it. Two people connecting to the same server can -therefore see a different list of tools. If a tool below is missing from your client, the signed-in user does not have -access to that part of the platform. Most tools are available to every BAV user, while some data models and products -need additional access. The access column in the tables below describes what each tool requires. +The server registers each tool only for users who have permission to use it. Thus, two people who connect to the same +server can see different lists of tools. If your client does not show a tool from the tables below, the signed-in user +does not have access to that part of the platform. Most tools are available to all BAV users. Some data models and +products need more access. The access column in the tables below tells what each tool requires. -**Tip:** You can always ask the agent to list the available tools interactively, or you can use -the [list tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#listing-tools) mechanism as -defined in the MCP specification. This will return the full tool definitions including parameters and descriptions. +**Tip:** You can ask the agent to list the available tools. You can also use +the [list tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#listing-tools) mechanism from +the MCP specification. This mechanism returns the full tool definitions, with parameters and descriptions. ### Metadata and Lookup Tools | Tool | What it does | Access | |-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------| -| `get-markets` | Lists the markets and years with BAV data, and the **study IDs** you need to request data. Each study is labelled with its type, and the recommended one is marked. | Users who can view studies. | -| `get-brands` | Searches brands and returns their details (website, social links, sector, company, tags) and a summary of the markets and years each brand was studied in. | Users who can view brands. | +| `get-markets` | Lists the markets and years with BAV data, and the **study IDs** you need to request data. Each study shows its type, and the recommended study has a mark. | Users who can view studies. | +| `get-brands` | Searches brands and returns their details (website, social links, sector, company, tags) and a summary of the markets and years in the studies of each brand. | Users who can view brands. | | `list-brand-tags` | Lists the brand tags (such as luxury, direct-to-consumer or family owned) and their keys, for use with the `tags` filter on `get-brands`. | Users who can view brands. | | `get-sectors` | Lists the sectors in the BAV taxonomy. | Users who can view BAV categories. | -| `get-categories` | Lists the categories in the BAV taxonomy, optionally filtered by search, sector, study, country or year. | Users who can view BAV categories. | +| `get-categories` | Lists the categories in the BAV taxonomy. You can filter them by search, sector, study, country or year. | Users who can view BAV categories. | | `get-audiences` | Lists the audiences you can segment brand data by. The default audience is "All Adults". | Users who can view brand data. | -| `get-glossary` | Returns definitions of brand metrics, brand measures or audience questions (`type` is required), optionally limited to what was measured in given studies. | Users who can view at least one of metrics, measures or questions. Each `type` needs its own access. | +| `get-glossary` | Returns definitions of brand metrics, brand measures or audience questions (`type` is required). You can limit them to the items that given studies measured. | Users who can view at least one of metrics, measures or questions. Each `type` needs its own access. | #### Finding brands with `get-brands` @@ -71,32 +71,33 @@ defined in the MCP specification. This will return the full tool definitions inc - `search` - Free text search on the brand name. This is the best way to find a brand by name. - `brands` - A list of brand IDs. - `sectors` - A list of sector names or IDs. -- `countries` - A list of country codes (ISO 3166-1 alpha-2) or IDs. Only returns brands with data in these markets. -- `years` - A list of years or IDs. Only returns brands with data in these years. -- `studies` - A list of study names or IDs. Only returns brands included in these studies. -- `tags` - A list of brand tag keys or IDs from `list-brand-tags`. Passing several tags returns brands carrying *any* - of them, not all of them. -- `include_study_history` - Set to `true` to list every study each brand appears in. By default each brand only - carries a `study_coverage` summary (years, and per market the number of studies, first and latest year and the latest - study), because long-running brands are in over a thousand studies. -- `page` - The page number. Results are returned 50 brands per page. +- `countries` - A list of country codes (ISO 3166-1 alpha-2) or IDs. Returns only brands with data in these markets. +- `years` - A list of years or IDs. Returns only brands with data in these years. +- `studies` - A list of study names or IDs. Returns only brands that these studies include. +- `tags` - A list of brand tag keys or IDs from `list-brand-tags`. If you send several tags, the tool returns brands + that have *any* of them, not all of them. +- `include_study_history` - Set to `true` to list all studies for each brand. By default, each brand has only a + `study_coverage` summary. This summary gives the years and, for each market, the number of studies, the first and + latest year and the latest study. The reason is that some brands with a long history are in more than a thousand + studies. +- `page` - The page number. Each page contains 50 brands. ### Brand Data Tools -These tools return the BAV brand data, each for one data model. Every one of them takes the shared -[data selection parameters](#selecting-data) below, and some take a few extra parameters of their own. +These tools return the BAV brand data, each for one data model. All of them use the shared +[data selection parameters](#selecting-data) below. Some of them also have their own parameters. | Tool | What it does | Extra parameters | Access | |---------------------------------|------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|----------------------------------------------| | `get-pillar-data` | The four pillars of brand equity: Differentiation, Relevance, Esteem and Knowledge. | `metrics` | BAV users. | | `get-powergrid-data` | Brand Strength and Brand Stature, the PowerGrid position. | `metrics` | BAV users. | -| `get-imagery-data` | Imagery (perception) attributes describing how people see a brand. | `metrics`, `score_type` | BAV users. | +| `get-imagery-data` | Imagery (perception) attributes that describe how people see a brand. | `metrics`, `score_type` | BAV users. | | `get-personality-data` | Personality, a higher-level summary built from the imagery attributes. | `metrics`, `score_type` | BAV users. | | `get-archetypes-data` | The twelve brand archetypes. Supports a competitive mode. | `comparison_categories`, `comparison_collections` | BAV users. | | `get-commitment-funnel-data` | The Commitment Funnel: the behavioural and emotional relationship between brands and consumers. | - | BAV users. | | `get-usage-data` | Usage on a scale from Never Used to Regularly Use. | `metrics`, `score_type` | BAV users. | | `get-preferences-data` | Preference on a scale from Would Never Use to One I Prefer. | `metrics`, `score_type` | BAV users. | -| `get-recommendation-data` | Whether consumers would recommend the brand to a friend. | `metrics`, `score_type` | BAV users. | +| `get-recommendation-data` | The share of consumers who would recommend the brand to a friend. | `metrics`, `score_type` | BAV users. | | `get-brand-worth-data` | The Brand Worth Map: "worth paying more for" versus "providing good value". | - | BAV users. | | `get-perception-swot-data` | A Brand Perception SWOT of the brand against its category or a collection, across imagery attributes. Requires `brands`. | `comparison_categories`, `comparison_collections`, `enable_drivers`, `x_axis_driver`, `y_axis_driver` | BAV users. | | `get-category-drivers-data` | Which imagery attributes drive the equity pillars within a category or collection. | `categories`, `collections`, `driver_metrics`, `x_axis_metric`, `y_axis_metric` | BAV users. | @@ -105,37 +106,38 @@ These tools return the BAV brand data, each for one data model. Every one of the | `get-influence-data` | How influential a brand is and what makes it influential. | `metrics` | Users with access to Influence. | | `get-customer-experience-data` | Perceived customer experience through the Super CX analysis. | - | Users with access to Super CX. | | `get-creative-premium-data` | The Creative Premium rank, creativity and influence scores. | - | Users with access to Creative Premium. | -| `get-partnership-exchange-data` | Compares the imagery of a brand and a potential partner to find partnership opportunities. | Takes a single `brand` and `partner` (both required) instead of `brands`. | Users with access to the Imagery Exchange Map. | +| `get-partnership-exchange-data` | Compares the imagery of a brand and a potential partner to find partnership opportunities. | Takes one `brand` and one `partner` (both required) in place of `brands`. | Users with access to the Imagery Exchange Map. | #### Selecting data The brand data tools share these parameters: -- `studies` - A list of study IDs. **This is how data is selected, and it is required to get data back.** A study is +- `studies` - A list of study IDs. **This parameter selects the data, and you must send it to get data.** A study is one market and year of one study type. Get the study IDs from `get-markets`. - `brands` - A list of brand names or IDs. -- `audiences` - A list of audience names or IDs to segment the data by. If left out, the "All Adults" audience is used, - and the response says that it was assumed. +- `audiences` - A list of audience names or IDs to segment the data by. If you do not send it, the tool uses the + "All Adults" audience. The response then tells that the tool assumed this audience. - `countries` - A list of country names or codes (e.g. `GB`). - `years` - A list of years (e.g. `2025`). -`countries` and `years` do **not** return data on their own. A market and year can be covered by more than one type of -study (for example the standard BAV study and a SnapBAV study), and these are not interchangeable. Rather than guess, -the tool responds with the matching studies, the recommended one marked, and asks the agent to call it again with an -explicit `studies` value. If `studies` is given, any `countries` and `years` are ignored. The server never picks a -study on the agent's behalf. See [studies](./concepts.md#studies-not-markets-and-years) for more on how this works. +`countries` and `years` alone do **not** return data. More than one type of study can include the same market and +year (for example the standard BAV study and a SnapBAV study). You cannot use one type in place of another. The tool +does not guess. It responds with the applicable studies and marks the recommended study. It then tells the agent to call +it again with an explicit `studies` value. If you send `studies`, the tool ignores `countries` and `years`. The server +never selects a study on behalf of the agent. For more information, refer to +[studies](./concepts.md#studies-not-markets-and-years). -Studies the user does not have access to are dropped from the request. If none are left, the tool responds as if no -study had been given. +The tool removes the studies that the user does not have access to from the request. If no studies remain, the tool +responds as if the request had no study. #### Limiting metrics with `metrics` -Many brand data tools accept an optional `metrics` parameter, a list of metric keys that limits the response to a -subset of the model's metrics. If it is left out, all of the model's metrics are returned. The allowed keys are listed in -each tool's definition, so your agent can see them without another call. `get-glossary` with `type` set to `metrics` -explains what each key means. +Many brand data tools accept an optional `metrics` parameter. It is a list of metric keys that limits the response to +some of the metrics of the model. If you do not send it, the tool returns all metrics of the model. The definition of +each tool lists the permitted keys. Thus, your agent can see them without another call. `get-glossary` with `type` set +to `metrics` explains the meaning of each key. -For `get-toplist-data`, `metrics` is required and decides which metrics the brands are ranked on. +For `get-toplist-data`, `metrics` is required. It sets the metrics that the tool uses to rank the brands. #### Choosing scores with `score_type` @@ -145,58 +147,59 @@ accept an optional `score_type`: - `rank` - Percentile rank scores from 0 to 100, ranked against all brands in the study. - `percentage` - The percentage of respondents. -Imagery and personality default to `rank`. Usage, preferences and recommendation default to `percentage`. The default -is stated in each tool's definition. See [rank vs percentage](./concepts.md#rank-vs-percentage-scores) for how to read -the two. +Imagery and personality use `rank` by default. Usage, preferences and recommendation use `percentage` by default. The +definition of each tool gives the default. To learn how to read the two types, refer to +[rank vs percentage](./concepts.md#rank-vs-percentage-scores). #### Data that is still generating -Brand data is aggregated on demand. The first time anyone asks for a particular study and audience combination, the -data may not exist yet. Instead of returning an empty result, the tool starts generating it and replies with a -message starting `DATA GENERATING`, asking the agent to tell the user and call the tool again shortly with the same -parameters. This usually takes a minute or two. +The system aggregates brand data on demand. When a user asks for a study and audience combination for the first +time, the data possibly does not exist yet. The tool does not return an empty result. It starts to generate the data. It +replies with a message that starts with `DATA GENERATING`. This message tells the agent to inform the user and to call +the tool again soon with the same parameters. This usually takes one or two minutes. -If only part of a request is still generating, the tool returns the data it has and prepends a notice listing what is -still being prepared. See [data generation](./concepts.md#data-generation) for details. +If only part of a request is not ready, the tool returns the data that it has. At the start, it adds a notice that lists +the data that is not ready yet. For more information, refer to [data generation](./concepts.md#data-generation). ### Collection Tools -Collections are saved lists of brands. The collection IDs can also be used as `comparison_collections` or +Collections are saved lists of brands. You can also use the collection IDs as `comparison_collections` or `collections` in the brand data tools. | Tool | What it does | Access | |---------------------------------|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| | `create-collection` | Creates a collection from a `name` and a list of `brand_ids`. Set `is_public` to make it public (private by default). | Users who can create collections. | -| `update-collection` | Updates a collection's name and/or public status. | Users who can update collections and may edit that collection. | -| `add-brands-to-collection` | Adds brands to a collection. | Users who can update collections and may manage its brands. | -| `remove-brands-from-collection` | Removes brands from a collection. | Users who can update collections and may manage its brands. | +| `update-collection` | Updates the name, the public status, or both, of a collection. | Users who can update collections and can edit that collection. | +| `add-brands-to-collection` | Adds brands to a collection. | Users who can update collections and can manage its brands. | +| `remove-brands-from-collection` | Removes brands from a collection. | Users who can update collections and can manage its brands. | | `share-collection` | Shares a collection with up to 10 people by email, with `view` (default) or `edit` permission. | Users who can share collections and collaborate on that collection. | ### Audience Tools -These tools let an agent build audiences (custom respondent segments) and then use them to segment the brand data. -See [audiences](../../audiences/audiences.md) for more about how audiences are structured. +With these tools, an agent can build audiences (custom respondent segments). The agent can then use them to segment +the brand data. For more information about the structure of audiences, refer to +[audiences](../../audiences/audiences.md). | Tool | What it does | Access | |------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------| -| `get-audience-metrics` | Lists the metrics that can be used as audience criteria, with their IDs, types and value dictionaries. Call this before creating or updating an audience. | Users who can view audiences. | -| `get-audience-groups` | Lists the groups audiences can be organised into. | Users who can view audiences. | -| `get-audience-studies` | Lists the studies an audience is available in, with its respondent count and projected population in each, to size it before analysis. | Users who can view audiences. | +| `get-audience-metrics` | Lists the metrics that you can use as audience criteria, with their IDs, types and value dictionaries. Call this before you create or update an audience. | Users who can view audiences. | +| `get-audience-groups` | Lists the groups that you can put audiences into. | Users who can view audiences. | +| `get-audience-studies` | Lists the studies that have the audience, with its respondent count and projected population in each. Use it to find the size of the audience before analysis. | Users who can view audiences. | | `create-audience` | Creates an audience with its definitions, segments and metrics in one call. | Users who can create audiences. | -| `update-audience` | Updates an audience's name, description or group. Does not change its definitions. | Users who can build audiences. | +| `update-audience` | Updates the name, description or group of an audience. Does not change its definitions. | Users who can build audiences. | | `add-audience-definition` | Adds a definition (for example a market-specific override) to an existing audience. | Users who can build audiences. | | `update-audience-definition` | Replaces all segments and metrics of a definition with the structure provided. | Users who can build audiences. | -| `deploy-audience` | Deploys an audience (making it active and starting processing) or undeploys it. | Users who can build audiences. | +| `deploy-audience` | Deploys an audience (makes it active and starts processing) or undeploys it. | Users who can build audiences. | | `get-audience-question-data` | How a market's population answered BAV survey questions about themselves, such as demographics and attitudes. Takes up to 25 `questions` plus the shared data selection parameters (without `brands`). | Users with access to Audience 360. | ### AURA Tools -AURA is WPP Open's AI brand research, powered by WPP BAV. It fields BAV surveys to large language models instead of -human respondents, so the numbers describe how AI models perceive a brand rather than how consumers do. +AURA is the AI brand research of WPP Open, powered by WPP BAV. It sends BAV surveys to large language models, not to +human respondents. Thus, the numbers show how AI models perceive a brand, not how consumers perceive it. | Tool | What it does | |-------------------------------|----------------------------------------------------------------------------------------------------------------------| -| `get-aura-studies` | Lists the markets and waves with AURA data and their study IDs. AURA is fielded often (often monthly), so `latest_only` returns just the most recent wave per market. | +| `get-aura-studies` | Lists the markets and waves with AURA data and their study IDs. We field AURA frequently (often monthly). Thus, `latest_only` returns only the most recent wave for each market. | | `get-aura-audiences` | Lists the AI perspectives to segment by: "All LLMs" (the default), individual AI providers and individual models. | | `get-aura-pillar-data` | How AI models perceive a brand across the four pillars. | | `get-aura-powergrid-data` | How AI models position a brand on the PowerGrid. | @@ -206,29 +209,30 @@ human respondents, so the numbers describe how AI models perceive a brand rather All AURA tools require access to AURA. -The AURA data tools take the same `brands`, `countries`, `years`, `audiences`, `studies` and `metrics` parameters as the -brand data tools, with two differences: `audiences` takes AI perspectives from `get-aura-audiences`, and `studies` is -optional. If no AURA studies are given, the tool uses the latest AURA study per market (or every AURA study in the given -`years`). `get-aura-drift-data` takes `ai_audiences` and `consumer_audiences` instead of `audiences`. +The AURA data tools use the same `brands`, `countries`, `years`, `audiences`, `studies` and `metrics` parameters as the +brand data tools. There are two differences: `audiences` takes AI perspectives from `get-aura-audiences`, and `studies` +is optional. If you do not send AURA studies, the tool uses the latest AURA study for each market. If you send `years`, +it uses all AURA studies in those years. `get-aura-drift-data` uses `ai_audiences` and `consumer_audiences` in place of +`audiences`. ### Media Performance Tools | Tool | What it does | |--------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| -| `get-media-performance-funnels` | Lists the funnel stages campaigns are classified by. | +| `get-media-performance-funnels` | Lists the funnel stages that classify campaigns. | | `get-media-performance-business-units` | Lists business units (franchises), optionally for given brands. | | `get-media-performance-media-sub-types` | Lists media sub-types, optionally for given brands. | | `get-media-performance-campaign-classifications` | Lists campaign classifications, optionally for given brands. | -| `get-campaign-performance-data` | Weekly campaign performance (impressions, clicks, costs, visits, conversions, revenue) per brand, country, funnel, business unit, media sub-type and classification. Use `fields` to limit the metrics returned. Derived metrics such as CPM are not included. | +| `get-campaign-performance-data` | Weekly campaign performance (impressions, clicks, costs, visits, conversions, revenue) per brand, country, funnel, business unit, media sub-type and classification. Use `fields` to limit the returned metrics. It does not include derived metrics such as CPM. | | `get-campaign-performance-benchmarks` | Aggregated performance with derived metrics (CPM, CPC, CTR, ROI and more) already calculated. Use `group_by` to aggregate by country, funnel, business unit, media sub-type, campaign classification, month, week or in total. | -The media performance tools are only available to users who have access to media performance data for at least one -brand. +The media performance tools are available only to users who have access to media performance data for one or more +brands. ### Display Tools -The display tools render interactive charts directly in the conversation, in clients that support MCP Apps. They take -the same data selection parameters as the brand data tools. See [MCP Apps](./mcp-apps.md) for details. +In clients that support MCP Apps, the display tools show interactive charts directly in the conversation. They use +the same data selection parameters as the brand data tools. For more information, refer to [MCP Apps](./mcp-apps.md). | Tool | What it does | Access | |-------------------------------------|----------------------------------------------------------------------|------------| @@ -238,7 +242,7 @@ the same data selection parameters as the brand data tools. See [MCP Apps](./mcp | `display-brand-relationship-chart` | Preferences, recommendation and usage, with a toggle between them. | BAV users. | :::note Unstable Responses -We do not promise that MCP server responses will be stable over time, in contrast to traditional API responses. The -data may be updated, and the models may also change how they respond to user requests. If you need stable responses for -your application we suggest prompting for a structured data response after the agent has called the tools. +Traditional API responses are stable over time. We do not promise that MCP server responses will be stable. The data +can change, and the models can also change how they respond to user requests. If your application needs stable +responses, we recommend this procedure. After the agent calls the tools, ask it for a structured data response. ::: diff --git a/docs/ai/mcp/best-countries.md b/docs/ai/mcp/best-countries.md index 0d4ec3c..479819c 100644 --- a/docs/ai/mcp/best-countries.md +++ b/docs/ai/mcp/best-countries.md @@ -4,78 +4,78 @@ sidebar_label: Best Countries Server # Best Countries MCP Server -The Best Countries MCP Server provides access to the WPP BAV proprietary Best Countries data through a set of tools that -can be called by AI agents. This allows you to build AI applications that can leverage how people around the world -perceive countries and cities to provide insights, recommendations, and analysis. +The Best Countries MCP Server gives access to the WPP BAV proprietary Best Countries data through a set of tools that +AI agents can call. With these tools, you can build AI applications that use data about how people around the world +perceive countries and cities. These applications can give insights, recommendations, and analysis. ## Connecting to the server Our remote MCP server uses the Streamable HTTP transport. -To connect to the Best Countries MCP server, you need to use the following URL: +To connect to the Best Countries MCP server, use this URL: ``` https://mcp-beta.wppbav.com/v1/best-countries ``` :::note -The domain will change to `mcp.wppbav.com` in the future. We'll communicate this change in advance with a good notice -period so you can update your applications accordingly. +The domain will change to `mcp.wppbav.com` in the future. We will tell you about this change a sufficient time before +it occurs, so that you can update your applications. ::: -For authorization, please see the [access and authorization](./access-authorization.md) section. For step-by-step -instructions for your client, see [connecting clients](./connecting-clients.md). +For authorization, refer to the [access and authorization](./access-authorization.md) section. For step-by-step +instructions for your client, refer to [connecting clients](./connecting-clients.md). ## Available Tools -The Best Countries MCP server provides two sets of data tools: +The Best Countries MCP server has two sets of data tools: -- **Country Data**: Tools that provide insights into how countries are perceived. -- **City Data**: Tools that provide insights into how cities are perceived. +- **Country Data**: Tools that give insights into how people perceive countries. +- **City Data**: Tools that give insights into how people perceive cities. -Which tools you see depends on your permissions. Each group of tools is enabled separately, so a user without access to -city data will not see the city tools at all. +The tools that you see depend on your permissions. Each group of tools has a separate permission. Thus, a user without +access to city data does not see the city tools. -**Tip:** You can ask the agent to list the available tools interactively, or you can use -the [list tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#listing-tools) mechanism as -defined in the MCP specification. This will return the full tool definitions including parameters and descriptions. +**Tip:** You can ask the agent to list the available tools. You can also use +the [list tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#listing-tools) mechanism from +the MCP specification. This mechanism returns the full tool definitions, with parameters and descriptions. ### Country Data Tools | Tool | Description | Requires access to | |----------------------------------------|------------------------------------------------------------------------------------------------------------------------------|--------------------| -| `get-country-factors-data` | How people perceive countries across the 10 high-level factors that correlate with GDP growth, including the overall Best Country rank. | Country data | +| `get-country-factors-data` | How people perceive countries on the 10 high-level factors that correlate with GDP growth, with the overall Best Country rank. | Country data | | `get-country-perception-data` | How people perceive countries on a wide range of imagery attributes. | Country data | -| `get-country-doing-business-data` | Whether business decision makers would consider doing business in countries. | Country data | -| `get-country-education-data` | Whether people would consider going to university in countries. | Country data | -| `get-country-visit-consideration-data` | Whether people would consider visiting countries for vacation. | Country data | -| `get-product-origin-data` | Whether people would consider buying products from countries across various product categories. | Origin Index data | +| `get-country-doing-business-data` | If business decision makers would consider business in countries. | Country data | +| `get-country-education-data` | If people would consider a university education in countries. | Country data | +| `get-country-visit-consideration-data` | If people would consider a vacation visit to countries. | Country data | +| `get-product-origin-data` | If people would consider the purchase of products from countries, in different product categories. | Origin Index data | ### City Data Tools | Tool | Description | Requires access to | |-------------------------------------|-----------------------------------------------------------------------------|--------------------| | `get-city-perception-data` | How people perceive cities on a wide range of imagery attributes. | City data | -| `get-city-doing-business-data` | Whether business decision makers would consider doing business in cities. | City data | -| `get-city-visit-consideration-data` | Whether people would consider visiting cities for vacation. | City data | +| `get-city-doing-business-data` | If business decision makers would consider business in cities. | City data | +| `get-city-visit-consideration-data` | If people would consider a vacation visit to cities. | City data | ### Tool Parameters -All tools accept the same set of optional parameters, which your agent will try to extract from the user input: +All tools accept the same set of optional parameters. Your agent tries to find the values in the user input: -- `countries` (country tools) - ISO 3166-1 alpha-2 country codes or country IDs. When left empty, all studied countries - are returned. -- `cities` (city tools) - Complete city names or city IDs. When left empty, all studied cities are returned. -- `years` - Year numbers or year IDs. Data from 2022 onwards is supported. +- `countries` (country tools) - ISO 3166-1 alpha-2 country codes or country IDs. If it is empty, the tool returns all + studied countries. +- `cities` (city tools) - Complete city names or city IDs. If it is empty, the tool returns all studied cities. +- `years` - Year numbers or year IDs. The tools support data from 2022 and later. - `audiences` - Audience names or IDs. - `scoreType` - Either `rank` (how the country or city ranks against all others) or `score` (a 100-point score from worst to best against all others). -Behind the scenes the BAV systems will automatically handle fallbacks should a parameter not be provided. If neither -countries nor years are given, the latest year of Best Countries data is used. If no audience is given, the default -audience is used. +If a request does not include a parameter, the BAV systems automatically use a fallback value. If the request has no +countries and no years, the tool uses the latest year of Best Countries data. If the request has no audience, the tool +uses the default audience. :::note Unstable Responses -We do not promise that MCP server responses will be stable over time, in contrast to traditional API responses. The -data may be updated, and the models may also change how they respond to user requests. If you need stable responses for -your application we suggest prompting for a structured data response after the agent has called the tools. +Traditional API responses are stable over time. We do not promise that MCP server responses will be stable. The data +can change, and the models can also change how they respond to user requests. If your application needs stable +responses, we recommend this procedure. After the agent calls the tools, ask it for a structured data response. ::: diff --git a/docs/ai/mcp/concepts.md b/docs/ai/mcp/concepts.md index 0fa391a..7f74eb9 100644 --- a/docs/ai/mcp/concepts.md +++ b/docs/ai/mcp/concepts.md @@ -4,115 +4,118 @@ sidebar_label: Concepts for Agents # Concepts for Agents -This page explains the handful of BAV concepts that matter most when you build an agent on top of the -[BAV MCP server](./bav.md). The tool descriptions and responses already explain most of this to the model, but knowing -it yourself makes it much easier to write good system prompts and to understand why an agent behaves the way it does. +This page explains the BAV concepts that are most important when you build an agent on the +[BAV MCP server](./bav.md). The tool descriptions and responses already explain most of this to the model. But if you +know these concepts, you can write better system prompts. You can also understand why an agent does what it does. ## Studies, not markets and years -In BAV, data is collected in **studies**. A study is one market and one year (or period) of one **study type**. Most -markets are surveyed at most once a year, the US is generally surveyed three times a year, and some markets less often -than yearly. +In BAV, we collect data in **studies**. A study is one market and one year (or period) of one **study type**. We +survey most markets one time a year at most. We usually survey the US three times a year. We survey some markets less +than one time a year. -A market and year can be covered by more than one study type, and they are not interchangeable: +More than one study type can include the same market and year. You cannot use one study type in place of another: | Type | What it is | |--------------|-------------------------------------------------------------------------------------------------------------| -| `syndicated` | The full, standard BAV study. Marked as `recommended`, and the one to use unless the user asks for something else. | +| `syndicated` | The full, standard BAV study. It has the `recommended` mark. Use it unless the user asks for a different type. | | `snap` | SnapBAV. Covers fewer brands and is more volatile between waves. | -| `fused` | AO+BAV. Probabilistically modelled to enable Audience Origin audience targeting. Not comparable to the standard study. | +| `fused` | AO+BAV. A probabilistic model that makes Audience Origin audience targeting possible. You cannot compare it to the standard study. | | `custom` | A bespoke study with a tailored sample, brand set or questions. | -Because of this, the brand data tools select data by **study ID**, not by market and year. The typical flow is: +Thus, the brand data tools select data by **study ID**, not by market and year. The usual procedure is: -1. Call `get-markets` (optionally with `countries` and `years`) to list the available studies. -2. Pick the study marked `recommended`, unless the user asked for a different kind. +1. Call `get-markets` to list the available studies. You can also give `countries` and `years`. +2. Select the study with the `recommended` mark, unless the user asked for a different type. 3. Call the data tool with that study ID in `studies`. If an agent calls a data tool with only `countries` and `years`, the tool does not guess. It replies with a message -starting `NEEDS SELECTION`, listing the matching studies, and the agent calls the tool again with the study it chose. -This is a normal, successful response rather than an error, so the agent keeps going instead of giving up. +that starts with `NEEDS SELECTION` and lists the applicable studies. The agent then calls the tool again with the study +that it selected. This is a normal, successful response, not an error. Thus, the agent continues and does not stop. -A few more things to keep in mind: +Also remember these points: -- If a study carries a `caveat`, the agent should tell the user which study was used and relay the caveat. -- Each study has a `methodology` (the version of the BAV model, such as BAV 3). Metrics are calculated differently - between versions, so comparisons across methodologies should be flagged. -- Every data response starts with a `request` block that echoes the filters used, including `studies_used` and an - `assumed` list of anything that was defaulted (such as the "All Adults" audience). -- AURA studies are kept separate. The brand data tools never return AURA data, and the AURA tools never return consumer - data. AURA studies are listed by `get-aura-studies`, not `get-markets`. +- If a study has a `caveat`, the agent must tell the user which study it used. The agent must also give the caveat to + the user. +- Each study has a `methodology` (the version of the BAV model, such as BAV 3). The calculation of metrics is different + between versions. Thus, the agent must tell the user about comparisons across methodologies. +- Each data response starts with a `request` block that repeats the filters that the tool used. This block includes + `studies_used` and an `assumed` list of all default values (such as the "All Adults" audience). +- AURA studies are separate. The brand data tools never return AURA data, and the AURA tools never return consumer + data. `get-aura-studies` lists the AURA studies, not `get-markets`. ## Rank vs percentage scores -Most BAV metrics can be reported as more than one score type. The two an agent will meet most often are: +Most BAV metrics are available as more than one score type. The two types that an agent sees most frequently are: -- **Percentile rank** - A score from 0 to 100 (where 100 is best) showing where the brand sits among all brands in the - study. It is **not** a percentage and should never be shown with a `%` sign. In responses, these keys end in +- **Percentile rank** - A score from 0 to 100 (where 100 is best). It shows the position of the brand among all brands + in the study. It is **not** a percentage. Never show it with a `%` sign. In responses, these keys end in `_percentile_rank`. - **Percentage** - The percentage of respondents who rated the brand a certain way. -Some guidance worth passing on to your agent when it reads ranks: +Give this guidance to your agent for ranks: -- A change in rank can come from the brand changing, from other brands changing, or both. -- Ranks are evenly distributed, so year-to-year moves are often bigger in the mid-range (30-70). A change of around 20 - ranks is noteworthy but not dramatic. +- A change in rank can occur because the brand changed, because other brands changed, or both. +- Ranks have an even distribution. Thus, changes from one year to the next are frequently larger in the mid-range + (30-70). A change of about 20 ranks is important but not dramatic. - As a rule of thumb, 75+ is great, 50-75 is good, 25-50 is not great and below 25 is very poor. Tools that support both score types take a `score_type` parameter (`rank` or `percentage`). The default depends on the data model and is stated in the tool's definition. -Some data models are **category-specific**: respondents saw both the brand and the category it was surveyed in, so the -category should be part of any analysis, and a brand can appear once per category in a study. Others are -**category-agnostic**: respondents only saw the brand name, which lets you look at the brand in culture as a whole -rather than within a narrow category. Each data response includes instructions that say which kind it is. +Some data models are **category-specific**. In these models, respondents saw the brand and the category of the +survey. Thus, include the category in all analysis. A brand can occur one time for each category in a study. Other data +models are **category-agnostic**. In these models, respondents saw only the brand name. Thus, you can examine the brand +in the full culture, not only in a narrow category. Each data response includes instructions that tell which type it is. ## Data generation -Brand data is aggregated on demand for each combination of study and audience. The first time anyone asks for a -combination, it may not have been built yet. When that happens the tool starts generating it and replies with a -message starting `DATA GENERATING`, telling the agent to let the user know and to call the tool again shortly with the -same parameters. Generation usually takes a minute or two. +The system aggregates brand data on demand for each combination of study and audience. When a user asks for a +combination for the first time, the combination is possibly not available yet. In this case, the tool starts to +generate it. The tool replies with a message that starts with `DATA GENERATING`. This message tells the agent to inform +the user and to call the tool again soon with the same parameters. Generation usually takes one or two minutes. There are two variants: -- **Pending** - Nothing that was asked for is ready yet. The response only contains the generating notice. -- **Partial** - Some combinations are ready and some are not. The response contains the data that is ready, with a - notice in front listing the combinations that are still generating. +- **Pending** - No requested data is ready yet. The response contains only the generation notice. +- **Partial** - Some combinations are ready and some are not. The response contains the data that is ready. A notice + at the start lists the combinations that are not ready yet. -Neither is an error, and the agent should not tell the user that the data does not exist. This is different from a row -with a `message` such as "No data available for Brand X in Germany 2025", which means the brand was not covered in that -study. +Neither variant is an error. The agent must not tell the user that the data does not exist. A row with a `message` such +as "No data available for Brand X in Germany 2025" is different. That message means that the study did not include the +brand. -If your agent runs unattended, make sure it retries after a short wait rather than ending the task. +If your agent runs unattended, make sure that it tries again after a short wait and does not end the task. ## Brand names and variations -A brand can be known by different names, for example in different markets or languages. The brand data responses -include several name fields: +A brand can have different names, for example in different markets or languages. The brand data responses include +several name fields: - `brand` - The brand's global name. -- `brand_variation` - The name variation the brand was surveyed under in that study. +- `brand_variation` - The name variation that the study used for the brand. - `local_name` - The brand's local name in that market, where there is one. - `brand_name` - The name to show: the global, local or translated name depending on the user's brand name display setting, without qualifiers. -Empty fields are left out of the response, so not every row carries all of these. +The response does not include empty fields. Thus, some rows do not have all of these fields. -When searching with `get-brands`, names may not match exactly. A good agent offers close matches and asks the user -before including them. When two different brands share a name, the `qualifier` field tells them apart. +When you search with `get-brands`, the names possibly do not match exactly. A good agent shows close matches and asks +the user before it includes them. When two different brands have the same name, the `qualifier` field identifies each +brand. ## Using the glossary `get-glossary` returns definitions for three kinds of items, chosen with `type`: - `metrics` - The computed brand metrics the data tools return, with their keys, groups and available score types. -- `measures` - The core survey questions respondents answer about brands. Used to build audiences. -- `questions` - The survey questions respondents answer about themselves. Used to build audiences and with - `get-audience-question-data`. +- `measures` - The core survey questions that respondents answer about brands. You use them to build audiences. +- `questions` - The survey questions that respondents answer about themselves. You use them to build audiences and + with `get-audience-question-data`. -Pass `studies` whenever you can, so the agent only sees what was actually measured in the studies it is working with. +Send `studies` when possible. Then the agent sees only the items that its studies measured. -The metric keys from the glossary are what the other tools expect, for example in `metrics` on the brand data tools, -the required `metrics` on `get-toplist-data` and `driver_metrics` on `get-category-drivers-data`. Encourage your agent to -look up a definition before interpreting an unfamiliar metric, rather than inferring its meaning from the key. +The other tools use the metric keys from the glossary. For example, `metrics` on the brand data tools, the required +`metrics` on `get-toplist-data` and `driver_metrics` on `get-category-drivers-data` use these keys. Tell your agent to +find the definition of an unknown metric before it interprets the metric. The agent must not guess the meaning from +the key. diff --git a/docs/ai/mcp/connecting-clients.md b/docs/ai/mcp/connecting-clients.md index cb674ed..af5af6b 100644 --- a/docs/ai/mcp/connecting-clients.md +++ b/docs/ai/mcp/connecting-clients.md @@ -4,15 +4,15 @@ sidebar_label: Connecting Clients # Connecting Clients -Our MCP servers are remote servers that work with any MCP client that supports the Streamable HTTP transport and the -standard MCP authorization flow. In most clients, all you need to provide is the server URL. The client will then -open a browser window where you sign in with your WPP Okta account and authorize the client to access data on your +Our MCP servers are remote servers. They work with all MCP clients that support the Streamable HTTP transport and the +standard MCP authorization flow. In most clients, you only need to give the server URL. The client then opens a browser +window. In this window, you sign in with your WPP Okta account. You then authorize the client to get data on your behalf. :::warning Authorized Agent Environments -Please note that you may only connect to the BAV MCP servers from authorized agent environments that have been -vetted by WPP legal. If you are not sure whether your environment is authorized, please reach out. See -[access and authorization](./access-authorization.md) for more information. +Connect to the BAV MCP servers only from authorized agent environments that WPP legal approved. If you are not sure +that your environment is authorized, contact us. For more information, refer to +[access and authorization](./access-authorization.md). ::: ## Server URLs @@ -25,48 +25,53 @@ vetted by WPP legal. If you are not sure whether your environment is authorized, | [Market Share](./market-share.md) | `https://mcp-beta.wppbav.com/v1/market-share` | :::note -The domain will change to `mcp.wppbav.com` in the future. We'll communicate this change in advance with a good notice -period so you can update your applications accordingly. +The domain will change to `mcp.wppbav.com` in the future. We will tell you about this change a sufficient time before +it occurs, so that you can update your applications. ::: -Each server is added to your client separately, so you can choose to only connect the servers you need. +You add each server to your client separately. Thus, you can connect only the servers that you need. ## WPP Open -All of the BAV MCP servers are available in WPP Open via Creative Studio and its agent builder. +All of the BAV MCP servers are available in WPP Open through Creative Studio and its agent builder. -This allows you to build agents that can access the BAV MCP servers directly from within WPP Open, -and leverage the capabilities of the agent builder to create custom workflows and integrations. +Thus, you can build agents that use the BAV MCP servers directly in WPP Open. You can also use the capabilities of the +agent builder to create custom workflows and integrations. -To get started with using the BAV MCP servers in WPP Open, follow these steps: +To start to use the BAV MCP servers in WPP Open, do these steps: -1. Log in to your WPP Open account and navigate to Creative Studio. -2. Open your playground or one of your existing projects. -3. Create a new agent or open an existing one in the Agent Builder. -4. In the Instructions tab, open Tools & Settings and find the server you want in the Tools list. +1. Log in to your WPP Open account. +2. Go to Creative Studio. +3. Open your playground or one of your current projects. +4. In the Agent Builder, create a new agent or open a current agent. +5. In the Instructions tab, open Tools & Settings. +6. Find the server that you want in the Tools list. -And that's it! You can now use the MCP servers in your WPP Open agents to enhance their capabilities and create more -powerful workflows. +You can now use the MCP servers in your WPP Open agents. The servers add capabilities to your agents and make more +powerful workflows possible. -The [Social Data](./social.md) connector by our partner Sightly is also available in WPP Open as a third-party -connector, and can be combined with the BAV MCP servers in the same agent. +The [Social Data](./social.md) connector from our partner Sightly is also available in WPP Open as a third-party +connector. You can use it together with the BAV MCP servers in the same agent. ### Using pre-built agents -Getting started with the BAV MCP server has a little learning curve in familiarizing yourself with BAV data, concepts -and methodology to make the most out of it. If you are building an internal tool, please do get in touch with us for -assistance. +To get the most from the BAV MCP server, you must first learn about BAV data, concepts and methodology. If you build an +internal tool, contact us for help. -To help you get started quickly, we have created some pre-built agents that create summaries and reports using key BAV -data. These can be helpful to drop in as part of a multi-step agent workflow. They are managed by BAV and make it -super-simple for you to get started with BAV data with minimal setup. See [BAV Agents](../agents.md) for more -information. +To help you start quickly, we made some pre-built agents. These agents create summaries and reports from key BAV data. +You can add them as one part of a multi-step agent workflow. BAV manages these agents. With them, you can start to use +BAV data with a minimum of setup. For more information, refer to [BAV Agents](../agents.md). ## Claude -In the Claude apps, our servers can be added as custom connectors. Add a new custom connector, give it a name and -paste the server URL. Claude will then take you through the sign-in and authorization flow. Depending on your plan, an -organization administrator may need to add the connector for your organization first. +In the Claude apps, you can add our servers as custom connectors: + +1. Add a new custom connector. +2. Give it a name. +3. Paste the server URL. + +Claude then takes you through the sign-in and authorization flow. On some plans, an organization administrator must +first add the connector for your organization. In Claude Code, you can add a server from the command line: @@ -74,42 +79,47 @@ In Claude Code, you can add a server from the command line: claude mcp add --transport http wpp-bav https://mcp-beta.wppbav.com/v1/bav ``` -Then run `/mcp` inside Claude Code to sign in and authorize the server. +Then run `/mcp` in Claude Code to sign in and authorize the server. ## ChatGPT -ChatGPT supports remote MCP servers as custom connectors, depending on your plan and workspace settings. Create a new -connector using the server URL and choose OAuth as the authentication method. ChatGPT will then take you through the -sign-in and authorization flow. Your workspace administrator may need to enable custom connectors first. +On some plans and workspace settings, ChatGPT supports remote MCP servers as custom connectors. Possibly, your +workspace administrator must first enable custom connectors. + +1. Create a new connector with the server URL. +2. Select OAuth as the authentication method. + +ChatGPT then takes you through the sign-in and authorization flow. ## Microsoft 365 Copilot To use our servers in Microsoft 365 Copilot, add them as a tool to an agent in -[Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent), and -then publish the agent to Microsoft 365 Copilot and Teams. +[Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent). Then +publish the agent to Microsoft 365 Copilot and Teams. 1. Open your agent in Copilot Studio and go to the **Tools** page. 2. Select **Add a tool**, then **New tool**, then **Model Context Protocol**. 3. Enter a **Server name**, a **Server description** and the **Server URL**, for example - `https://mcp-beta.wppbav.com/v1/bav`. Describe what the server does clearly, as the agent uses the description to - decide when to call it. For example: "WPP BAV brand equity data: brands, studies, pillars, imagery and other brand - metrics." -4. Choose **OAuth 2.0** as the authentication type and **Dynamic discovery** as the OAuth type. Our servers support - dynamic client registration, so no client ID or secret is needed. + `https://mcp-beta.wppbav.com/v1/bav`. Write a clear description of the server function. The agent uses the + description to decide when to call the server. For example: "WPP BAV brand equity data: brands, studies, pillars, + imagery and other brand metrics." +4. Select **OAuth 2.0** as the authentication type and **Dynamic discovery** as the OAuth type. Our servers support + dynamic client registration. Thus, you do not need a client ID or secret. 5. Select **Create**, then **Next**. -6. Select **Create a new connection**, sign in with your WPP account and authorize access, then select - **Add to agent**. +6. Select **Create a new connection**. +7. Sign in with your WPP account and authorize access. +8. Select **Add to agent**. -Repeat the steps for each server you want the agent to use. Each user of the agent signs in with their own account, -so they only see the tools they have access to. +Do these steps again for each server that you want the agent to use. Each user of the agent signs in with their own +account. Thus, each user sees only the tools that they have access to. -Your organization's data policies for Power Platform connectors also apply to MCP servers, so an administrator may -need to allow the connection first. +The data policies of your organization for Power Platform connectors also apply to MCP servers. Thus, possibly an +administrator must first allow the connection. ## GitHub Copilot in VS Code -In VS Code, you can add the servers to an `mcp.json` file, either in your workspace (`.vscode/mcp.json`) or in your -user configuration: +In VS Code, you can add the servers to an `mcp.json` file. This file can be in your workspace (`.vscode/mcp.json`) or +in your user configuration: ```json { @@ -126,22 +136,21 @@ user configuration: } ``` -When the server starts, VS Code will prompt you to sign in and authorize it. The tools are then available to Copilot in +When the server starts, VS Code tells you to sign in and authorize it. The tools are then available to Copilot in agent mode. ## Other clients -Any MCP client that supports remote servers over Streamable HTTP can connect to our servers. A few things to keep in -mind: - -- **Streamable HTTP only.** The servers only accept `POST` requests. The older SSE (Server-Sent Events) transport is not - supported, and `GET` and `DELETE` requests to the server URL return `405 Method Not Allowed`. -- **OAuth discovery.** Clients that support the MCP authorization flow will discover everything they need from the - `401` response and the `.well-known` metadata, including dynamic client registration. See - [access and authorization](./access-authorization.md) for details. -- **Personal access tokens.** If your client does not support OAuth but lets you set custom headers, you can pass a - personal access token as a Bearer token in the `Authorization` header instead. -- **Local-only clients.** If your client only supports local (stdio) servers, you can use a proxy such as +All MCP clients that support remote servers over Streamable HTTP can connect to our servers. Remember these points: + +- **Streamable HTTP only.** The servers accept only `POST` requests. The servers do not support the older SSE + (Server-Sent Events) transport. `GET` and `DELETE` requests to the server URL return `405 Method Not Allowed`. +- **OAuth discovery.** Clients that support the MCP authorization flow find all the data that they need in the `401` + response and the `.well-known` metadata. This includes dynamic client registration. For more information, refer to + [access and authorization](./access-authorization.md). +- **Personal access tokens.** Some clients do not support OAuth, but let you set custom headers. In these clients, send + a personal access token as a Bearer token in the `Authorization` header. +- **Local-only clients.** If your client supports only local (stdio) servers, use a proxy such as [mcp-remote](https://www.npmjs.com/package/mcp-remote) to connect it to a remote server. -If you have trouble connecting a specific client, please [get in touch with us](mailto:bavsupport@wpp.com). +If you cannot connect a specific client, [contact us](mailto:bavsupport@wpp.com). diff --git a/docs/ai/mcp/financial-data.md b/docs/ai/mcp/financial-data.md index f49d842..225d608 100644 --- a/docs/ai/mcp/financial-data.md +++ b/docs/ai/mcp/financial-data.md @@ -4,66 +4,68 @@ sidebar_label: Financial Data Server # Financial Data MCP Server -The Financial Data MCP Server provides access to the financial data via BAV Futures for listed companies around the -world through a set of tools that can be called by AI agents. It also provides daily share prices for listed companies. +The Financial Data MCP Server gives access to financial data from BAV Futures for listed companies around the world. +It has a set of tools that AI agents can call. It also gives daily share prices for listed companies. ## Connecting to the server Our remote MCP server uses the Streamable HTTP transport. -To connect to the Financial Data MCP server, you need to use the following URL: +To connect to the Financial Data MCP server, use this URL: ``` https://mcp-beta.wppbav.com/v1/futures ``` :::note -The domain will change to `mcp.wppbav.com` in the future. We'll communicate this change in advance with a good notice -period so you can update your applications accordingly. +The domain will change to `mcp.wppbav.com` in the future. We will tell you about this change a sufficient time before +it occurs, so that you can update your applications. ::: -For authorization, please see the [access and authorization](./access-authorization.md) section. For step-by-step -instructions for your client, see [connecting clients](./connecting-clients.md). +For authorization, refer to the [access and authorization](./access-authorization.md) section. For step-by-step +instructions for your client, refer to [connecting clients](./connecting-clients.md). ## Available Tools -The Financial Data MCP server provides a set of tools that you can use to access various types of data. All tools are -available to every user who can connect to the server. +The Financial Data MCP server has a set of tools that you can use to get different types of data. All tools are +available to all users who can connect to the server. -**Tip:** You can always ask the agent to list the available tools interactively, or you can use -the [list tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#listing-tools) mechanism as -defined in the MCP specification. This will return the full tool definitions including parameters and descriptions. +**Tip:** You can ask the agent to list the available tools. You can also use +the [list tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#listing-tools) mechanism from +the MCP specification. This mechanism returns the full tool definitions, with parameters and descriptions. | Tool | Description | |--------------------------|---------------------------------------------------------------------------------------------------------------| -| `get-analyst-ratings` | Analyst ratings and recommendations, including buy/sell/hold ratings and price targets. | -| `get-balance-sheet` | Balance sheet data, including assets, liabilities, and shareholders' equity. | -| `get-cash-flow` | Cash flow statement data, including operating, investing, and financing activities. | -| `get-earnings` | Earnings data and reports, including historical and estimated earnings. | -| `get-financial-overview` | A comprehensive financial overview, including general information, highlights, and valuation metrics. | -| `get-income-statement` | Income statement data, including revenue, expenses, and profitability. | -| `get-stock-prices` | Daily share prices (open, high, low, close, adjusted close and volume), optionally within a date range. | +| `get-analyst-ratings` | Analyst ratings and recommendations, with buy/sell/hold ratings and price targets. | +| `get-balance-sheet` | Balance sheet data, with assets, liabilities, and shareholders' equity. | +| `get-cash-flow` | Cash flow statement data, with operating, investing, and financing activities. | +| `get-earnings` | Earnings data and reports, with historical and estimated earnings. | +| `get-financial-overview` | A comprehensive financial overview, with general information, highlights, and valuation metrics. | +| `get-income-statement` | Income statement data, with revenue, expenses, and profitability. | +| `get-stock-prices` | Daily share prices (open, high, low, close, adjusted close and volume). You can limit them to a date range. | ### Tool Parameters -Each tool expects to receive the stock ticker symbol as a required `ticker` parameter, in the format -`TICKER.EXCHANGE` (e.g., `AAPL.US` for Apple Inc.). All US companies use the `.US` exchange code. +Each tool requires the stock ticker symbol in the `ticker` parameter, in the format `TICKER.EXCHANGE` (for example, +`AAPL.US` for Apple Inc.). All US companies use the `.US` exchange code. -In addition, `get-stock-prices` accepts two optional parameters to limit the date range: +`get-stock-prices` also accepts two optional parameters to limit the date range: -- `from` - The first trading day to return, as `YYYY-MM-DD`. Omit to start from the beginning of the published history. -- `to` - The last trading day to return, as `YYYY-MM-DD`. Omit to run to the most recent close. +- `from` - The first trading day to return, as `YYYY-MM-DD`. If you do not send it, the data starts at the beginning of + the published history. +- `to` - The last trading day to return, as `YYYY-MM-DD`. If you do not send it, the data ends at the most recent close. ### Share Prices -The share prices from `get-stock-prices` are returned oldest first, with one row per trading day. Weekends and market -holidays are therefore absent from the data. When comparing prices over time, use the adjusted close, which is -corrected for splits and dividends. +`get-stock-prices` returns the share prices with the oldest first, with one row for each trading day. Thus, the data +does not include weekends and market holidays. To compare prices over time, use the adjusted close. The adjusted close +includes corrections for splits and dividends. -A single call returns at most 500 trading days. If the requested range is longer, only the most recent 500 trading days -are returned and the response says so. Narrow the range with `from` and `to` to read an earlier period. +One call returns a maximum of 500 trading days. If the requested range is longer, the tool returns only the most recent +500 trading days. The response then tells you this. To read an earlier period, make the range smaller with `from` and +`to`. :::note Unstable Responses -We do not promise that MCP server responses will be stable over time, in contrast to traditional API responses. The -data may be updated, and the models may also change how they respond to user requests. If you need stable responses for -your application we suggest prompting for a structured data response after the agent has called the tools. +Traditional API responses are stable over time. We do not promise that MCP server responses will be stable. The data +can change, and the models can also change how they respond to user requests. If your application needs stable +responses, we recommend this procedure. After the agent calls the tools, ask it for a structured data response. ::: diff --git a/docs/ai/mcp/intro.md b/docs/ai/mcp/intro.md index 13b553c..b318033 100644 --- a/docs/ai/mcp/intro.md +++ b/docs/ai/mcp/intro.md @@ -4,20 +4,19 @@ sidebar_label: Introduction # Introduction -By using an MCP server you can connect your AI models and agents directly to BAV data. This allows your agents to -retrieve up-to-date information from BAV and use it to answer user queries, generate insights, and power your workflows. +With an MCP server, you can connect your AI models and agents directly to BAV data. Your agents can then get current +information from BAV. They can use it to answer user queries, make insights, and power your workflows. -MCP (Model Context Protocol) is an open standard that allows AI models and agents to interact with external data -sources through a set of defined tools. Think of it as an API but specifically designed for AI models and agents to call -tools to retrieve data. +MCP (Model Context Protocol) is an open standard. It lets AI models and agents use external data sources through a set +of defined tools. MCP is similar to an API, but it is specially for AI models and agents that call tools to get data. -We're excited to see how you and your agents use BAV data to power your workflows. If you have questions, feedback, or -requests for new MCP tools, please let us know. +We are interested to see how you and your agents use BAV data in your workflows. If you have questions, feedback, or +requests for new MCP tools, tell us. ## Our MCP Servers -We currently offer a few different MCP servers that you can connect to depending on which dataset you want to access. -Please refer to each server's documentation for more details on the available tools. +We have some different MCP servers. Connect to the server for the dataset that you want to use. For more information +about the available tools, refer to the documentation for each server. | Server | URL | Data | |-------------------------------------------------|-----------------------------------------------|-------------------------------------------------------------------| @@ -27,13 +26,13 @@ Please refer to each server's documentation for more details on the available to | [Market Share](./market-share.md) | `https://mcp-beta.wppbav.com/v1/market-share` | Euromonitor market share for brands and companies. | :::note -The domain will change to `mcp.wppbav.com` in the future. We'll communicate this change in advance with a good notice -period so you can update your applications accordingly. +The domain will change to `mcp.wppbav.com` in the future. We will tell you about this change a sufficient time before +it occurs, so that you can update your applications. ::: -In addition to our own servers, the [Social Data](./social.md) connector by our partner Sightly is available as a -third-party connector in WPP Open. It gives your agents access to real-time social and news listening data that works -well alongside BAV brand perception data. +The [Social Data](./social.md) connector from our partner Sightly is also available as a third-party connector in WPP +Open. It gives your agents access to real-time social and news listening data. This data works well together with BAV +brand perception data. ## Getting started @@ -44,15 +43,12 @@ well alongside BAV brand perception data. ## Building an internal tool? -Getting started with the BAV MCP server has a little learning curve in familiarizing yourself with BAV data, concepts -and methodology to make the most out of it. If you are building an internal tool to release to the group, please do [get -in touch with us](mailto:bavsupport@wpp.com) for assistance and collaboration. +To get the most from the BAV MCP server, you must first learn about BAV data, concepts and methodology. If you build an +internal tool to release to the group, [contact us](mailto:bavsupport@wpp.com). We can help you and work with you. ## Issues and Feedback -If you encounter any issues while using the MCP servers or have suggestions for improvements, please reach out to us. -The AI development speed is rapid and we are continuously working to enhance our MCP offerings as new capabilities are -possible. +If you have problems with the MCP servers or have suggestions for improvements, contact us. AI development is fast. +We continue to improve our MCP servers when new capabilities become possible. -Your needs and feedback are invaluable in helping us prioritize our development efforts. We look forward to hearing from -you! +Your needs and feedback help us to set the priorities for our development. We look forward to your feedback. diff --git a/docs/ai/mcp/market-share.md b/docs/ai/mcp/market-share.md index 59d7269..1cec7c7 100644 --- a/docs/ai/mcp/market-share.md +++ b/docs/ai/mcp/market-share.md @@ -4,82 +4,83 @@ sidebar_label: Market Share Server # Market Share MCP Server -The Market Share MCP Server provides access to Euromonitor market share data for brands and companies through a set of -tools that can be called by AI agents. Market share can be sliced by category, geography, data type and year, and -read alongside BAV brand equity data for brands and companies that have been linked to BAV. +The Market Share MCP Server gives access to Euromonitor market share data for brands and companies through a set of +tools that AI agents can call. You can divide market share by category, geography, data type and year. For brands and +companies with a link to BAV, you can also read market share together with BAV brand equity data. ## Connecting to the server Our remote MCP server uses the Streamable HTTP transport. -To connect to the Market Share MCP server, you need to use the following URL: +To connect to the Market Share MCP server, use this URL: ``` https://mcp-beta.wppbav.com/v1/market-share ``` :::note -The domain will change to `mcp.wppbav.com` in the future. We'll communicate this change in advance with a good notice -period so you can update your applications accordingly. +The domain will change to `mcp.wppbav.com` in the future. We will tell you about this change a sufficient time before +it occurs, so that you can update your applications. ::: -For authorization, please see the [access and authorization](./access-authorization.md) section. For step-by-step -instructions for your client, see [connecting clients](./connecting-clients.md). +For authorization, refer to the [access and authorization](./access-authorization.md) section. For step-by-step +instructions for your client, refer to [connecting clients](./connecting-clients.md). ### Access -The Market Share tools require access to Euromonitor data. Users without it will not see any tools when connecting -to the server. Please [get in touch with us](mailto:bavsupport@wpp.com) if you need access. +The Market Share tools require access to Euromonitor data. When users without this access connect to the server, +they see no tools. If you need access, [contact us](mailto:bavsupport@wpp.com). ## How the data works -The server gives your agent a set of instructions on how to use the data. These are worth knowing if you are building -on top of the server, as they explain how to read the responses. - -- **Euromonitor has its own IDs.** Euromonitor keeps its own catalog of brands, companies, categories, geographies, - industries and data types, and none of them are BAV's. Look up IDs with the `get-euromonitor-*` tools first. A BAV ID - passed as a Euromonitor ID does not fail. It silently reads as a different entity. -- **Linked BAV brands and companies.** Where a Euromonitor brand or company has been linked to a BAV brand or company, - the lookup tools say so. Only linked entries can be read alongside BAV brand equity data. You can also pass BAV brand - and company IDs directly using the `bav_brands` and `bav_companies` parameters, which are matched through the link. -- **Every share query must be narrowed.** A share query has to name at least one entity, category, geography or - industry. A year on its own would return the whole of Euromonitor and is refused. -- **Null is not zero.** The measures arrive in separate extracts and are merged into one row. A `null` value is a - figure that was not supplied for that slice, never a zero. -- **Only licensed industries are available.** An industry that is not listed by `get-euromonitor-industries` is not - licensed, which means there is no data at all rather than a share of zero. +The server gives your agent a set of instructions about how to use the data. If you build on the server, it is +important to know these instructions, because they explain how to read the responses. + +- **Euromonitor has its own IDs.** Euromonitor has its own catalog of brands, companies, categories, geographies, + industries and data types. None of them are BAV items. First, find the IDs with the `get-euromonitor-*` tools. If you + send a BAV ID as a Euromonitor ID, the request does not fail. The tool silently reads it as a different entity. +- **Linked BAV brands and companies.** If a Euromonitor brand or company has a link to a BAV brand or company, the + lookup tools tell you. You can read only linked entries together with BAV brand equity data. You can also send BAV + brand and company IDs directly in the `bav_brands` and `bav_companies` parameters. The tools match them through the + link. +- **Every share query must be narrowed.** A share query must name one or more entities, categories, geographies or + industries. A year alone will return all of Euromonitor, so the tool refuses it. +- **Null is not zero.** The measures come in separate extracts, and the system merges them into one row. A `null` + value is a figure that Euromonitor did not supply for that slice. It is never a zero. +- **Only licensed industries are available.** If `get-euromonitor-industries` does not list an industry, that industry + is not licensed. This means that there is no data, not a share of zero. ## Available Tools -The Market Share MCP server provides two sets of tools: +The Market Share MCP server has two sets of tools: -- **Catalog Tools:** Look up the Euromonitor IDs that the share tools filter on. -- **Share Data Tools:** Fetch market share figures for brands and companies. +- **Catalog Tools:** Find the Euromonitor IDs that the share tools use as filters. +- **Share Data Tools:** Get market share figures for brands and companies. -**Tip:** You can always ask the agent to list the available tools interactively, or you can use -the [list tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#listing-tools) mechanism as -defined in the MCP specification. This will return the full tool definitions including parameters and descriptions. +**Tip:** You can ask the agent to list the available tools. You can also use +the [list tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#listing-tools) mechanism from +the MCP specification. This mechanism returns the full tool definitions, with parameters and descriptions. ### Catalog Tools -All catalog tools accept an optional `search` parameter to search by part of a name, and a `page` parameter for -pagination. Results are returned 50 at a time, and the response includes a `next_page` value until there are no more -pages. +All catalog tools accept an optional `search` parameter to search by part of a name. They also accept a `page` +parameter for pagination. Each page contains 50 results. The response includes a `next_page` value until there are no +more pages. | Tool | Description | Additional parameters | |-------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| -| `get-euromonitor-brands` | Search Euromonitor brands, including the owning Euromonitor company and the BAV brand each one is linked to. | `companies` (Euromonitor company IDs), `linked_to_bav` (true/false) | -| `get-euromonitor-companies` | Search Euromonitor companies, including the BAV company each one is linked to. | `linked_to_bav` (true/false) | +| `get-euromonitor-brands` | Search Euromonitor brands. Includes the Euromonitor company that owns each brand and its linked BAV brand. | `companies` (Euromonitor company IDs), `linked_to_bav` (true/false) | +| `get-euromonitor-companies` | Search Euromonitor companies. Includes the linked BAV company of each one. | `linked_to_bav` (true/false) | | `get-euromonitor-categories` | Search the tree of Euromonitor categories that a market share is a share of. | `industries` (Euromonitor industry IDs), `level` (depth in the tree), `parent` (category ID) | -| `get-euromonitor-geographies` | Search the tree of regions, countries and cities, including the BAV country each one lines up with. | `type` (`region`, `country` or `city`) | +| `get-euromonitor-geographies` | Search the tree of regions, countries and cities. Includes the applicable BAV country of each one. | `type` (`region`, `country` or `city`) | | `get-euromonitor-industries` | Search the Euromonitor industries, the top of the category tree and the whole of what is licensed. | - | -| `get-euromonitor-data-types` | Search the data types, i.e. what a share row measures, such as retail value or retail volume. | `industries` (Euromonitor industry IDs), `categories` (Euromonitor category IDs) | +| `get-euromonitor-data-types` | Search the data types. A data type is what a share row measures, such as retail value or retail volume. | `industries` (Euromonitor industry IDs), `categories` (Euromonitor category IDs) | -A few things to keep in mind when working with the catalogs: +Remember these points when you use the catalogs: -- Euromonitor names brands and companies its own way, often using the legal name for companies (e.g. "Procter & Gamble - Co, The"). Searching for a distinctive part of the name works better than the full name. -- A parent category's figures cover the whole of it, so a parent should never be summed with its children. -- A region's figures are its own, never the sum of the countries in it. +- Euromonitor names brands and companies in its own way. For companies, it frequently uses the legal name (for example + "Procter & Gamble Co, The"). A search for a distinctive part of the name works better than the full name. +- The figures of a parent category include all of that category. Thus, never add a parent to its children. +- The figures of a region are its own figures. They are never the sum of the countries in the region. ### Share Data Tools @@ -88,29 +89,29 @@ A few things to keep in mind when working with the catalogs: | `get-brand-market-share` | How much of a category a brand holds in a market. | | `get-company-market-share` | How much of a category a company holds in a market. This is the company's own share, not the sum of its brands. | -Both tools accept the following parameters. Each parameter accepts an array of IDs or names (up to 50 values). +Both tools accept these parameters. Each parameter accepts an array of IDs or names (up to 50 values). - `brands` - Euromonitor brand IDs or names, from `get-euromonitor-brands`. Brand tool only. -- `bav_brands` - BAV brand IDs or names. Matched through the link on the brand. An unlinked brand returns nothing. - Brand tool only. +- `bav_brands` - BAV brand IDs or names. The tool matches them through the link on the brand. A brand without a link + returns nothing. Brand tool only. - `companies` - Euromonitor company IDs or names, from `get-euromonitor-companies`. -- `bav_companies` - BAV company IDs or names. Matched through the link on the company. An unlinked company returns - nothing. +- `bav_companies` - BAV company IDs or names. The tool matches them through the link on the company. A company without + a link returns nothing. - `categories` - Euromonitor category IDs or names. - `geographies` - Euromonitor geography IDs or names. Not BAV country IDs. - `industries` - Euromonitor industry IDs or names. -- `data_types` - Euromonitor data type IDs or names, e.g. "Retail Value RSP". Pass one, since rows that only differ by - data type measure different things. -- `years` - Year numbers, e.g. `2024`. Must be combined with another filter. -- `score_type` - Which measure each row carries: `actual_usd` (default), `actual_local`, `percentage` (the share of the +- `data_types` - Euromonitor data type IDs or names, for example "Retail Value RSP". Send one data type, because rows + that are different only by data type measure different things. +- `years` - Year numbers, for example `2024`. You must use it with another filter. +- `score_type` - The measure in each row: `actual_usd` (default), `actual_local`, `percentage` (the share of the category in that market) or `rank` (the position in the category, where 1 is the largest). -At least one of the brand, company, category, geography or industry parameters must be provided. If a name or ID cannot -be matched, the tool returns an error naming the parameter rather than an empty result, so that your agent can look up +You must send one or more of the brand, company, category, geography or industry parameters. If the tool cannot match a +name or ID, it does not return an empty result. It returns an error that names the parameter. Your agent can then find the correct value and try again. :::note Unstable Responses -We do not promise that MCP server responses will be stable over time, in contrast to traditional API responses. The -data may be updated, and the models may also change how they respond to user requests. If you need stable responses for -your application we suggest prompting for a structured data response after the agent has called the tools. +Traditional API responses are stable over time. We do not promise that MCP server responses will be stable. The data +can change, and the models can also change how they respond to user requests. If your application needs stable +responses, we recommend this procedure. After the agent calls the tools, ask it for a structured data response. ::: diff --git a/docs/ai/mcp/mcp-apps.md b/docs/ai/mcp/mcp-apps.md index 82d7bb4..549ca5c 100644 --- a/docs/ai/mcp/mcp-apps.md +++ b/docs/ai/mcp/mcp-apps.md @@ -4,27 +4,27 @@ sidebar_label: MCP Apps (Charts) # MCP Apps -The [BAV MCP server](./bav.md) includes a set of display tools that render interactive BAV charts directly in the -conversation. They are built on [MCP Apps](https://github.com/modelcontextprotocol/ext-apps), an extension to the -Model Context Protocol that lets a tool come with its own user interface. +The [BAV MCP server](./bav.md) includes a set of display tools that show interactive BAV charts directly in the +conversation. These tools use [MCP Apps](https://github.com/modelcontextprotocol/ext-apps). MCP Apps is an extension to +the Model Context Protocol that lets a tool have its own user interface. ## How it works -Each display tool declares a UI resource (a `ui://` URI) in its tool metadata. When an agent calls the tool, a client -that supports MCP Apps loads that resource, an HTML page served with the `text/html;profile=mcp-app` MIME type, and -renders it in a sandboxed frame inside the conversation. The tool result carries the chart configuration and data as -structured content, which the page uses to draw the chart. +Each display tool declares a UI resource (a `ui://` URI) in its tool metadata. The resource is an HTML page with the +`text/html;profile=mcp-app` MIME type. When an agent calls the tool, a client that supports MCP Apps loads that +resource. The client then shows the page in a sandboxed frame in the conversation. The tool result contains the chart +configuration and data as structured content. The page uses this content to draw the chart. -You don't need to fetch the resources yourself. A client with MCP Apps support handles this automatically. +You do not need to get the resources yourself. A client with MCP Apps support does this automatically. ## Client support -MCP Apps is an extension, so not every MCP client supports it. Support is growing across AI assistants and agent -frameworks, but it varies between clients and versions, so please check the documentation of the client you use. +MCP Apps is an extension. Thus, some MCP clients do not support it. More AI assistants and agent frameworks support it +over time. But the support is different between clients and versions. Refer to the documentation of your client. -In a client without MCP Apps support, the display tools can still be called, but no chart is shown. The agent only -receives a short text confirmation. If your client does not support MCP Apps, have your agent use the regular data tools -instead. +In a client without MCP Apps support, the agent can call the display tools, but the client does not show a chart. The +agent gets only a short text confirmation. If your client does not support MCP Apps, tell your agent to use the regular +data tools. ## Display tools @@ -39,17 +39,19 @@ All display tools are available to users who can view BAV brand data. ### Parameters -The display tools take the same data selection parameters as the brand data tools: `studies` (required to get a -chart), `brands`, `audiences`, `countries` and `years`. Selecting a study works exactly as described in -[selecting data](./bav.md#selecting-data). If only `countries` and `years` are given, the tool asks the agent to choose -a study first. If the data is still being generated, the tool says so and the agent should call it again shortly. +The display tools use the same data selection parameters as the brand data tools: `studies` (required to get a +chart), `brands`, `audiences`, `countries` and `years`. Study selection works as +[selecting data](./bav.md#selecting-data) describes. If the request has only `countries` and `years`, the tool tells the +agent to select a study first. If the data is not ready yet, the tool tells the agent. The agent must then call the +tool again soon. -Some display tools take extra parameters: +Some display tools have more parameters: - `display-imagery-chart` - - `chart_type` - `line` (default), `bar` or `tree`. The treemap is only available when there is a single series. + - `chart_type` - `line` (default), `bar` or `tree`. The treemap is available only when there is one series. - `score_type` - `rank` (default) or `percentage`. - - `sort_by` - A series ID to sort the attributes by, highest first. If left out, attributes are sorted alphabetically. + - `sort_by` - A series ID to sort the attributes by, highest first. If you do not give it, the tool sorts the + attributes alphabetically. - `display-brand-relationship-chart` - `data_type` - The data shown first: `preferences` (default), `recommendation` or `usage`. @@ -61,15 +63,15 @@ All charts: - Offer a fullscreen mode when the client supports it. - Link to the same view in the WPP BAV platform, so the user can continue the analysis there. -The imagery chart also lets the user switch between line and bar, between rank and percentage scores, and change the -sort order, without another tool call. The brand relationship chart lets the user switch between preferences, -recommendation and usage. +In the imagery chart, the user can also change between line and bar, and between rank and percentage scores. The user +can also change the sort order. These changes do not need another tool call. In the brand relationship chart, the user +can change between preferences, recommendation and usage. ## Charts and commentary -The display tools return a chart, not the data. The text the agent receives only confirms that the chart is shown, and -points it to the matching data tool. If you want the agent to comment on what the chart shows, it should also call the -data tool: +The display tools return a chart, not the data. The text that the agent gets only confirms that the client shows the +chart. The text also refers the agent to the applicable data tool. If you want the agent to comment on the chart, the +agent must also call the data tool: | Display tool | Data tool(s) | |------------------------------------|----------------------------------------------------------------------| diff --git a/docs/ai/mcp/social.md b/docs/ai/mcp/social.md index 7ffde2f..8d174a3 100644 --- a/docs/ai/mcp/social.md +++ b/docs/ai/mcp/social.md @@ -4,37 +4,36 @@ sidebar_label: Social Data # Social Data MCP Server -The Social Data MCP Server, provided by our partner [Sightly](https://sightly.com), enables the intersection of -real-time data listening and brand perception. The server provides Model Context Protocol (MCP) tools that allow -clients to add these capabilities in conjunction with their existing data stack, enabling AI assistants and -applications to access comprehensive brand profiles, discover cultural trends, and gather real-time insights from news -articles, social media posts, TikTok and YouTube. +Our partner [Sightly](https://sightly.com) supplies the Social Data MCP Server. The server connects real-time data +listening and brand perception. It gives Model Context Protocol (MCP) tools that let clients add these capabilities to +their current data stack. With these tools, AI assistants and applications can get comprehensive brand profiles and +find cultural trends. They can also get real-time insights from news articles, social media posts, TikTok and YouTube. :::info Availability -The Social Data MCP Server is available as a connector in WPP Open. See -[Connecting clients: WPP Open](./connecting-clients.md#wpp-open) for how to add it to your agents. +The Social Data MCP Server is available as a connector in WPP Open. To add it to your agents, refer to +[Connecting clients: WPP Open](./connecting-clients.md#wpp-open). ::: This page is based on Sightly's MCP server documentation (version 1.36.0). ### Key Capabilities -- **Brand Intelligence**: Access detailed brand profiles including values, mission, vision, and brand positioning -- **Cultural Trend Analysis**: Discover macro cultural trends and patterns by aggregating news moments and social media narratives +- **Brand Intelligence**: Get detailed brand profiles, with values, mission, vision, and brand positioning +- **Cultural Trend Analysis**: Find macro cultural trends and patterns. The tools aggregate news moments and social media narratives to find them - **Real-Time News Insights**: Find clustered news moments (day-to-day events) and search individual news articles - **Social Media Intelligence**: Track social media narratives (day-to-day conversations) and analyze individual posts -- **TikTok Trend Discovery**: Get trending TikTok hashtags filtered by category, date range, country, and optional search terms -- **YouTube Intelligence**: Search YouTube videos and channels from a curated dataset with filtering by language, country, categories, and engagement metrics -- **YouTube Creator Discovery**: Find creators by topic or by who watches them, profile known channels including audience demographics and partnership eligibility, and track how interest in a topic is moving on YouTube -- **Audience Targeting**: Generate platform-specific audience targeting segments for ad campaigns across multiple platforms +- **TikTok Trend Discovery**: Get trending TikTok hashtags. Filter them by category, date range, country, and optional search terms +- **YouTube Intelligence**: Search YouTube videos and channels from a curated dataset. Filter by language, country, categories, and engagement metrics +- **YouTube Creator Discovery**: Find creators by topic or by their viewers. Get profiles of known channels, with audience demographics and partnership eligibility. Track how interest in a topic changes on YouTube +- **Audience Targeting**: Generate platform-specific audience targeting segments for ad campaigns on many platforms ### Data Hierarchy -The server organizes data in a hierarchical structure: +The server puts data in a hierarchical structure: -- **Individual Level**: Articles and social media posts provide detailed, granular content -- **Cluster Level**: Moments (news clusters) and Narratives (social media clusters) group related content -- **Trend Level**: Trends aggregate moments and narratives to reveal long-term cultural patterns +- **Individual Level**: Articles and social media posts give detailed, granular content +- **Cluster Level**: Moments (news clusters) and Narratives (social media clusters) put related content in groups +- **Trend Level**: Trends aggregate moments and narratives to show long-term cultural patterns --- @@ -50,42 +49,44 @@ The server organizes data in a hierarchical structure: **Hierarchy**: -- **Social Posts** → Clustered into **Narratives** (day-to-day conversations) -- **Articles** → Clustered into **Moments** (day-to-day news events) -- **Narratives + Moments** → Aggregated into **Trends** (long-term cultural patterns) +- **Social Posts** → Clusters of posts are **Narratives** (day-to-day conversations) +- **Articles** → Clusters of articles are **Moments** (day-to-day news events) +- **Narratives + Moments** → Aggregates of these are **Trends** (long-term cultural patterns) ## Array Parameters -Every parameter documented as an array below also accepts a string, for clients that cannot send real JSON arrays: +All parameters that this page shows as arrays also accept a string. This is for clients that cannot send real JSON +arrays: -- A JSON-encoded array, such as `"[\"Nike\", \"Adidas\"]"`, is parsed into the equivalent array. -- Any other string, such as `"Nike"`, is treated as a single-element array. +- The server parses a JSON-encoded array, such as `"[\"Nike\", \"Adidas\"]"`, into the equivalent array. +- The server uses all other strings, such as `"Nike"`, as an array with one element. -Sending a real array is still preferred. The documented maximum item counts apply either way, and values are never -split on commas, so `"Nike, Adidas"` is one value rather than two. +But we recommend that you send a real array. The documented maximum item counts apply to arrays and strings. The server +never splits values at commas. Thus, `"Nike, Adidas"` is one value, not two. ## Tools ### get_brand_profile -Get a brand's profile: industry, business and mentality summaries, mission, vision and value statements, key terms, -related entities, and the brand's answers to opinion and scenario questions. +Get the profile of a brand. The profile has the industry, business and mentality summaries, the mission, vision and +value statements, and key terms. It also has related entities, and the answers of the brand to opinion and scenario +questions. -**Note**: Brand profiles must be created and submitted in Sightly before they can be retrieved via this tool. -Only profiles owned by your account or its child accounts are returned. `brand_name` is matched approximately, so close -variants of the profile name still find it. +**Note**: You must create and submit brand profiles in Sightly before this tool can get them. The tool returns only +profiles that your account or its child accounts own. The tool uses an approximate match for `brand_name`. Thus, close +variants of the profile name also find the profile. **Parameters**: - `brand_name` (string, required): Brand name -**Returns**: plain text, not JSON. It opens with a `BRAND NAME: ` line followed by bracketed sections, each -omitted when empty: +**Returns**: plain text, not JSON. It starts with a `BRAND NAME: ` line. Sections in brackets come after this +line. The response does not include empty sections: - `[BRAND_INFORMATION]`: `Label: value` lines for industry, business summary, mentality summary, mission, vision and value statements, and key terms -- `[COMPANIES]`, `[INFLUENCERS]`, `[EVENTS]`, `[SOCIAL_CAUSES]`, `[PHILANTHROPIC_ORGANIZATIONS]`: one `name → relationship (type)` line per related entity -- `[OPINION_QUESTIONS]`, `[SCENARIO_QUESTIONS]`: one `question → answer` line per question +- `[COMPANIES]`, `[INFLUENCERS]`, `[EVENTS]`, `[SOCIAL_CAUSES]`, `[PHILANTHROPIC_ORGANIZATIONS]`: one `name → relationship (type)` line for each related entity +- `[OPINION_QUESTIONS]`, `[SCENARIO_QUESTIONS]`: one `question → answer` line for each question -When no matching profile is found, the response is the plain message `No profile found for `. +If the tool does not find an applicable profile, the response is the plain message `No profile found for `. **Example**: ```json @@ -99,23 +100,23 @@ When no matching profile is found, the response is the plain message `No profile ### get_trends -Discover macro cultural trends (long-term patterns) from news and social media. Does not cover YouTube; for how -interest in a topic is moving on YouTube, use `get_youtube_creator_insights` with `insight_type="trends"`. +Find macro cultural trends (long-term patterns) in news and social media. This tool does not include YouTube. To see +how interest in a topic changes on YouTube, use `get_youtube_creator_insights` with `insight_type="trends"`. **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Search terms. If not provided, returns top trends sorted by total article count (biggest trends first). Cannot be combined with `sort_by` +- `search_terms` (array, 0-3 terms, optional): Search terms. If you do not send them, the tool returns the top trends, sorted by total article count (largest trends first). You cannot use it with `sort_by` - `start_date` (string, optional): `YYYY-MM-DD` format, earliest `2026-01-01` - `end_date` (string, optional): `YYYY-MM-DD` format, earliest `2026-01-01` -- `brand` (array, optional): Filter to trends that mention these brands (max 5, OR'd). Case-insensitive substring match against every brand on the trend, not only the 10 listed in `top_brands` -- `person` (array, optional): Filter to trends that mention these people (max 5, OR'd). Case-insensitive substring match against every person on the trend, not only the 10 listed in `top_people` -- `sort_by` (string, optional): Only valid without search terms. Options: `"size"` (default, total article count - biggest trends) or `"recency"` (most recent trends first) -- `limit` (int, optional): Results per search term (default: 3, max: 5) -- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster +- `brand` (array, optional): Filter to trends that mention these brands (max 5, OR'd). A case-insensitive substring match against all brands on the trend, not only the 10 brands in `top_brands` +- `person` (array, optional): Filter to trends that mention these people (max 5, OR'd). A case-insensitive substring match against all people on the trend, not only the 10 people in `top_people` +- `sort_by` (string, optional): Valid only without search terms. Options: `"size"` (default, total article count - largest trends) or `"recency"` (most recent trends first) +- `limit` (int, optional): Results for each search term (default: 3, max: 5) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` to get only sample records. This is significantly faster Each trend in `sample_trends` includes `title`, `overview`, `bullet_points`, `start_date`, `end_date`, `total_moment_count`, `total_narrative_count`, `total_article_count`, `total_post_count`, `article_count_timeline` and -`post_count_timeline` (see [Timelines](#timelines)), `top_brands` and `top_people` (up to 10 names each), and -`representative_moments` and `representative_narratives` (up to 3 each). +`post_count_timeline` (refer to [Timelines](#timelines)), `top_brands` and `top_people` (a maximum of 10 names each), +and `representative_moments` and `representative_narratives` (a maximum of 3 each). **Example with search terms**: ```json @@ -146,23 +147,24 @@ Each trend in `sample_trends` includes `title`, `overview`, `bullet_points`, `st Find clustered news articles about topics (day-to-day events). **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Search terms. If not provided, returns top moments sorted by article count (biggest story clusters first). Cannot be combined with `sort_by` -- `start_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. Supports hour/minute precision; for a whole-day search use `T00:00:00` -- `end_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search use `T23:59:59` +- `search_terms` (array, 0-3 terms, optional): Search terms. If you do not send them, the tool returns the top moments, sorted by article count (largest story clusters first). You cannot use it with `sort_by` +- `start_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. Supports hour and minute precision. For a whole-day search, use `T00:00:00` +- `end_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search, use `T23:59:59` - `category` (array, optional): Filter by content categories (max 5) - `entity` (array, optional): Filter by entity names (max 5) -- `sort_by` (string, optional): Only valid without search terms. Options: `"size"` (default, article count - biggest clusters) or `"recency"` (most recent moments first) -- `limit` (int, optional): Results per search term (default: 8, max: 20) -- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster +- `sort_by` (string, optional): Valid only without search terms. Options: `"size"` (default, article count - largest clusters) or `"recency"` (most recent moments first) +- `limit` (int, optional): Results for each search term (default: 8, max: 20) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` to get only sample records. This is significantly faster Each moment in `sample_news_moments` includes `title`, `summary`, `start_date`, `end_date`, `total_article_count`, `article_count_timeline` (see [Timelines](#timelines)), and a `representative_article` with `title`, `url`, `published_at`, `publisher_name`, `publisher_domain` and `publisher_location`. -**Sensitive topics**: each moment may include `sensitive_topics`, the brand-safety topics the moment substantially -involves. Values come from: sex, drugs, crime, death, hacking, terrorism, tobacco, alcohol, military conflict, politics, -obscenity, conspiracy, guns, human rights, kids channel, racism. An empty list means the moment was evaluated and none -were flagged; the field is omitted for moments that have not been evaluated yet. +**Sensitive topics**: each moment can include `sensitive_topics`. This field lists the brand-safety topics that are +an important part of the moment. The values come from this list: sex, drugs, crime, death, hacking, terrorism, tobacco, +alcohol, military conflict, politics, obscenity, conspiracy, guns, human rights, kids channel, racism. An empty list +means that Sightly examined the moment and found no sensitive topics. If Sightly did not examine a moment yet, the +moment does not have this field. **Example with search terms**: ```json @@ -208,31 +210,31 @@ were flagged; the field is omitted for moments that have not been evaluated yet. Find clustered social media posts about topics (day-to-day conversations). **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Search terms. If not provided, returns top narratives sorted by post count (most discussed first). Cannot be combined with `sort_by` +- `search_terms` (array, 0-3 terms, optional): Search terms. If you do not send them, the tool returns the top narratives, sorted by post count (most discussed first). You cannot use it with `sort_by` - `start_date` (string, optional): `YYYY-MM-DD` format, earliest `2026-01-01` - `end_date` (string, optional): `YYYY-MM-DD` format, earliest `2026-01-01` - `sentiment` (string, optional): Filter by sentiment: `very_positive`, `positive`, `neutral`, `negative`, `very_negative` - `platform` (array, optional): Filter by platforms (max 5): X, Reddit, Truth Social, Pinterest, Instagram, Bluesky, TikTok, Threads - `theme` (array, optional): Filter by themes (max 5). Same theme list as [`get_social_media_posts`](#get_social_media_posts) -- `entity` (array, optional): Filter to narratives about a specific named person, brand, organization, product, event, or place (max 5), e.g. `["Messi", "Nike"]`. Case-insensitive substring match; multiple values are OR'd. Covers the roughly two-thirds of narratives where an entity was detected. For broad topics or moods, use `search_terms` instead -- `min_likes` (int, optional): Only return narratives whose posts have at least this many likes in total (must be ≥ 0). Narratives with no like total are excluded -- `min_comments` (int, optional): Only return narratives whose posts have at least this many comments in total (must be ≥ 0). Narratives with no comment total are excluded -- `min_shares` (int, optional): Only return narratives whose posts have at least this many shares/reposts in total (must be ≥ 0). Coverage is partial (roughly a quarter of narratives), so prefer `min_likes`/`min_comments` for general engagement filtering -- `country` (array, optional): Only return narratives with at least one post from these countries, as ISO 3166-1 alpha-2 codes (max 5, OR'd, any case), e.g. `["gb", "au"]`. This is an inclusion filter, not a dominance filter: a global narrative with a single UK post matches `["gb"]`. To see what a market is talking about, compare that country's `country_counts` entry against `total_post_count` on each record. Roughly a third of posts have no known country -- `sort_by` (string, optional): Only valid without search terms. Options: `"size"` (default, post count - most discussed) or `"recency"` (most recent narratives first) -- `limit` (int, optional): Results per search term (default: 8, max: 20) -- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster -- `include_original_text` (bool, optional, default `false`): Add `original_text` to each narrative's `representative_post`, i.e. the post's text in the language it was written in. Set `true` only when the source-language wording matters. Absent for posts that were already English +- `entity` (array, optional): Filter to narratives about a specific named person, brand, organization, product, event, or place (max 5), e.g. `["Messi", "Nike"]`. A case-insensitive substring match. Multiple values are OR'd. Includes only the narratives with a detected entity (about two-thirds). For broad topics or moods, use `search_terms` +- `min_likes` (int, optional): Return only narratives with posts that have this number of likes or more in total (must be ≥ 0). The tool does not return narratives with no like total +- `min_comments` (int, optional): Return only narratives with posts that have this number of comments or more in total (must be ≥ 0). The tool does not return narratives with no comment total +- `min_shares` (int, optional): Return only narratives with posts that have this number of shares/reposts or more in total (must be ≥ 0). Only some narratives have this data (about a quarter). Thus, for general engagement filters, we recommend `min_likes`/`min_comments` +- `country` (array, optional): Return only narratives with one or more posts from these countries, as ISO 3166-1 alpha-2 codes (max 5, OR'd, any case), e.g. `["gb", "au"]`. This filter checks for inclusion, not dominance. For example, a global narrative with one UK post matches `["gb"]`. To see the topics of conversation in a market, compare the `country_counts` entry of that country with `total_post_count` on each record. About a third of posts have no known country +- `sort_by` (string, optional): Valid only without search terms. Options: `"size"` (default, post count - most discussed) or `"recency"` (most recent narratives first) +- `limit` (int, optional): Results for each search term (default: 8, max: 20) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` to get only sample records. This is significantly faster +- `include_original_text` (bool, optional, default `false`): Add `original_text` to the `representative_post` of each narrative. This is the text of the post in its original language. Set `true` only when the source-language words are important. Posts that were already in English do not have this field Each narrative in `sample_social_media_narratives` includes `title`, `summary`, `start_date`, `end_date`, `total_post_count`, a `representative_post` (with `text`, `platform`, `post_publish_date` and, when available, `url` and -`author_name`), and `source_counts`. The `representative_post` text is always English: non-English posts are -machine-translated, so quote it as a translation unless you request `include_original_text`. +`author_name`), and `source_counts`. The `representative_post` text is always in English. A machine translates posts +that are not in English. Thus, quote the text as a translation, unless you request `include_original_text`. Each narrative also includes: -- `sentiment_score`: the cluster's overall sentiment on a -100 (most negative) to 100 (most positive) scale. The `sentiment` filter buckets this score: `very_negative` (below -75), `negative` (below -25), `neutral` (-25 to 25), `positive` (above 25), `very_positive` (above 75) -- `total_likes`, `total_comments`, `total_shares`: cluster-level engagement totals (omitted when unavailable) -- `country_counts` and `country_unclassified_count`: a per-country breakdown of where the posts come from (top 10 countries, with the remainder folded into an `other` entry) +- `sentiment_score`: the overall sentiment of the cluster, on a scale from -100 (most negative) to 100 (most positive). The `sentiment` filter puts this score in buckets: `very_negative` (below -75), `negative` (below -25), `neutral` (-25 to 25), `positive` (above 25), `very_positive` (above 75) +- `total_likes`, `total_comments`, `total_shares`: engagement totals for the cluster (not included when not available) +- `country_counts` and `country_unclassified_count`: the number of posts from each country (the top 10 countries, and an `other` entry for the remaining countries) **Example with search terms**: ```json @@ -266,21 +268,21 @@ Each narrative also includes: Search individual news articles (detailed content). **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Keep complete concepts together (e.g., `"renewable energy policy"` not `["renewable", "energy"]`). If not provided, returns most recent articles sorted by publish date. Non-English articles carry an English machine translation alongside the original text, and searches match both -- `start_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search use `T00:00:00` -- `end_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search use `T23:59:59` +- `search_terms` (array, 0-3 terms, optional): Keep complete concepts together (e.g., `"renewable energy policy"` not `["renewable", "energy"]`). If you do not send them, the tool returns the most recent articles, sorted by publish date. Articles that are not in English have an English machine translation and the original text. Searches match both +- `start_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search, use `T00:00:00` +- `end_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search, use `T23:59:59` - `publisher` (string, optional): Filter by publisher name -- `category` (array, optional): Filter by content categories (max 5). Do not prefix values with `news/` +- `category` (array, optional): Filter by content categories (max 5). Do not put `news/` at the start of values - `entity` (array, optional): Filter by entity names (max 5) -- `publisher_location` (string, optional): Filter by the publisher's country, as one full English country name: United States, United Kingdom, Canada, Germany, Spain, Turkey, South Africa, Nigeria, China, India, Philippines, Thailand, Mexico, Brazil, Argentina, France, Italy, Netherlands, Australia, Poland, United Arab Emirates, Japan. Articles with no recorded publisher location never match -- `language_code` (array, optional): Filter by the article's original language as lowercase ISO 639-3 codes (max 5, OR'd), e.g. `["spa", "deu"]`. Supported: eng, spa, deu, fra, ita, pol, nld, ara, jpn, por, zho, hin, tur, tha, rus, kor, fas, vie. Coverage is partial (only newer articles carry a language code), so use it to narrow by language rather than to find all English coverage -- `limit` (int, optional): Results per search term (default: 10, max: 50) -- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster -- `include_full_body` (bool, optional, default `false`): Return each article's full body text. By default `body` is truncated to 2,000 characters. Non-English articles also carry `original_title`/`original_body` (pre-truncated to roughly 500 characters, unaffected by this flag) +- `publisher_location` (string, optional): Filter by the country of the publisher, as one full English country name: United States, United Kingdom, Canada, Germany, Spain, Turkey, South Africa, Nigeria, China, India, Philippines, Thailand, Mexico, Brazil, Argentina, France, Italy, Netherlands, Australia, Poland, United Arab Emirates, Japan. Articles with no recorded publisher location never match +- `language_code` (array, optional): Filter by the original language of the article, as lowercase ISO 639-3 codes (max 5, OR'd), e.g. `["spa", "deu"]`. Supported: eng, spa, deu, fra, ita, pol, nld, ara, jpn, por, zho, hin, tur, tha, rus, kor, fas, vie. Only newer articles have a language code. Thus, use this filter to limit results by language, not to find all English articles +- `limit` (int, optional): Results for each search term (default: 10, max: 50) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` to get only sample records. This is significantly faster +- `include_full_body` (bool, optional, default `false`): Return the full body text of each article. By default, the tool truncates `body` to 2,000 characters. Articles that are not in English also have `original_title`/`original_body`. These fields are always truncated to about 500 characters, and this flag does not change them Each article in `sample_news_articles` includes `title`, `body`, `url`, `published_at`, `publisher_name`, -`publisher_domain`, `publisher_location`, `categories`, `entities`, `scenarios`, and `language_code`. Fields with no -value are omitted. +`publisher_domain`, `publisher_location`, `categories`, `entities`, `scenarios`, and `language_code`. The response +does not include fields with no value. **Example with search terms**: ```json @@ -324,28 +326,28 @@ value are omitted. Search individual social media posts (detailed content). **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Keep complete concepts together. If not provided, returns most recent posts sorted by publish date. Use for topics, themes, concepts, or moods; use `entity` for specific named people, brands, products, events or places. Combine both to find a topic about a named entity -- `start_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search use `T00:00:00` -- `end_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search use `T23:59:59` +- `search_terms` (array, 0-3 terms, optional): Keep complete concepts together. If you do not send them, the tool returns the most recent posts, sorted by publish date. Use it for topics, themes, concepts, or moods. Use `entity` for specific named people, brands, products, events or places. Use both to find a topic about a named entity +- `start_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search, use `T00:00:00` +- `end_date` (string, optional): UTC datetime `YYYY-MM-DDTHH:MM:SS`, earliest `2026-01-01T00:00:00`. For a whole-day search, use `T23:59:59` - `platform` (array, optional): Filter by platforms (max 5): X, Reddit, Truth Social, Pinterest, Instagram, Bluesky, TikTok, Threads - `theme` (array, optional): Filter by themes (max 5): discounts, purchase, appearance, churn, cost, ads, experience, craftmanship, transaction, criminal, loyalty, stock, taste, temperature, ambiance, delivery, fit, injury, knowledge, leadership, comfort, access, illness, location, restrooms, speed, satisfaction, wait times, cleanliness, durability, friendliness, selection -- `entity` (array, optional): Filter to posts about a specific named person, brand, organization, product, event, or place (max 5), e.g. `"Messi"`, `"Nike"`, `"FIFA World Cup"`. Case-insensitive substring match (`"messi"` matches `"Lionel Messi"`); multiple values are OR'd. Only covers the roughly half of posts where an entity was detected. Use short, distinctive fragments -- `min_likes` (int, optional): Only return posts with at least this many likes (must be ≥ 0). Posts with no like count are excluded -- `min_comments` (int, optional): Only return posts with at least this many comments (must be ≥ 0). Posts with no comment count are excluded -- `min_shares` (int, optional): Only return posts with at least this many shares/reposts (must be ≥ 0). Many platforms do not report shares, so this can sharply narrow results -- `min_author_followers` (int, optional): Only return posts whose author has at least this many followers (must be ≥ 0). Use for questions about influential or large accounts. Posts with no follower count are excluded, which drops platforms without a follower concept (Reddit, Facebook, Tumblr) entirely -- `country` (array, optional): Filter by the post's country of origin as ISO 3166-1 alpha-2 codes (max 5, OR'd, any case), e.g. `["us", "gb"]`. About half of all posts carry a country. Best-covered countries: us, th, gb, in, br, fr, tr, mx -- `language_code` (array, optional): Filter by the post's detected language as lowercase ISO 639-1 codes (max 5, OR'd), e.g. `["en", "ja"]`. Values must be lowercase (`"JA"` matches nothing). Pair with `country` to get a language within a market -- `limit` (int, optional): Results per search term (default: 10, max: 50) -- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster -- `include_full_body` (bool, optional, default `false`): Return each post's full text. By default post text is truncated to 2,000 characters -- `include_original_text` (bool, optional, default `false`): Add `original_text` to each post, i.e. its text in the language it was written in. Absent for posts that were already English, so its presence signals a non-English original +- `entity` (array, optional): Filter to posts about a specific named person, brand, organization, product, event, or place (max 5), e.g. `"Messi"`, `"Nike"`, `"FIFA World Cup"`. A case-insensitive substring match (`"messi"` matches `"Lionel Messi"`). Multiple values are OR'd. Includes only the posts with a detected entity (about half). Use short, distinctive fragments +- `min_likes` (int, optional): Return only posts with this number of likes or more (must be ≥ 0). The tool does not return posts with no like count +- `min_comments` (int, optional): Return only posts with this number of comments or more (must be ≥ 0). The tool does not return posts with no comment count +- `min_shares` (int, optional): Return only posts with this number of shares/reposts or more (must be ≥ 0). Many platforms do not report shares. Thus, this filter can remove many results +- `min_author_followers` (int, optional): Return only posts from authors with this number of followers or more (must be ≥ 0). Use it for questions about influential or large accounts. The tool does not return posts with no follower count. Thus, it removes all posts from platforms that do not have followers (Reddit, Facebook, Tumblr) +- `country` (array, optional): Filter by the country of origin of the post, as ISO 3166-1 alpha-2 codes (max 5, OR'd, any case), e.g. `["us", "gb"]`. About half of all posts have a country. The countries with the most data: us, th, gb, in, br, fr, tr, mx +- `language_code` (array, optional): Filter by the detected language of the post, as lowercase ISO 639-1 codes (max 5, OR'd), e.g. `["en", "ja"]`. Values must be lowercase (`"JA"` matches nothing). Use it with `country` to get a language in a market +- `limit` (int, optional): Results for each search term (default: 10, max: 50) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` to get only sample records. This is significantly faster +- `include_full_body` (bool, optional, default `false`): Return the full text of each post. By default, the tool truncates post text to 2,000 characters +- `include_original_text` (bool, optional, default `false`): Add `original_text` to each post. This is the text of the post in its original language. Posts that were already in English do not have this field. Thus, if the field is present, the original was not in English Each post in `sample_social_media_posts` includes `text`, `platform`, `url`, `post_publish_date`, `author_name`, -`themes`, `likes`, `comments`, `shares`, `author_followers`, `entities`, `country` and `language_code` (each omitted -when unavailable). Post text is always English: non-English posts are machine-translated on ingestion. Search is both -keyword and semantic, so a query in one language retrieves posts written in another; use `language_code` to restrict -results to an original language. +`themes`, `likes`, `comments`, `shares`, `author_followers`, `entities`, `country` and `language_code` (each field +only when available). Post text is always in English. When Sightly ingests a post that is not in English, a machine +translates it. The search uses keywords and semantics. Thus, a query in one language can find posts in a different +language. To limit results to an original language, use `language_code`. **Example with search terms**: ```json @@ -401,16 +403,16 @@ results to an original language. ### get_tiktok_hashtags -Get trending TikTok hashtags. Can optionally filter by search terms or get top hashtags by category, date range and -country. +Get trending TikTok hashtags. You can filter by search terms. You can also get top hashtags by category, date range +and country. **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Optional search terms to filter results. If not provided, returns top hashtags according to other parameters -- `category_name` (string, optional): Filter by TikTok category. When omitted, a query with search terms spans all categories, while a query without search terms defaults to the cross-category `"ALL"` leaderboard. Available categories: ALL, ACADEMIC_RESOURCES, ANIMATION_AND_COMICS, APPAREL_AND_ACCESSORIES, ART, AUTOMOTIVE, BABY_CARE, BABY_KIDS_AND_MATERNITY, BEAUTY, BEAUTY_AND_PERSONAL_CARE, BEAUTY_SERVICES, BUSINESS_AND_FINANCE, BUSINESS_SERVICES, CARD_AND_BOARD_GAMES, CAREER_AND_PROFESSIONAL_GROWTH, COLLEGE, COMEDY, COMMUNITY_UPDATES_AND_ISSUES, CONVENTIONAL_AND_MAINSTREAM_SPORTS, COOKING, CRAFTING_AND_CREATIONS, CULTURE, DANCE, DIARY_AND_VLOG, DRINKS, EATING_EXPERIENCES, EDUCATION, ENTERTAINMENT_AND_SPORTS_NEWS, ENVIRONMENT, EXERCISE_AND_FITNESS, EXTREME_AND_ADVENTURE_SPORTS, FAMILY, FINANCIAL_SERVICES, FOOD, FOOD_AND_BEVERAGE, FOOD_RECOMMENDATIONS, GADGETS_AND_INNOVATION, GAMES, GENERAL_TRAVEL, HAIR_CARE, HEALTH, HEALTH_AND_WELLNESS, HISTORY_AND_LITERATURE, HOME_AND_GARDEN, HOME_IMPROVEMENT, HOUSEHOLD_PRODUCTS, LEARNING_AND_DEVELOPMENT, LEISURE_AND_RECREATION_FACILITIES, LIFE_SERVICES, LIVESTOCK_AND_FARMING, MISCELLANEOUS_PERFORMANCES, MOVIES_AND_TV, MUSIC, NEWS_AND_ENTERTAINMENT, OTHER_BEAUTY, OTHER_FASHION, OTHER_TRANSPORTATION, OUTDOOR_RECREATION, OUTFITS, PERFORMING_ARTS, PERSONAL_PHOTOGRAPHY, PETS, PET_CARE_AND_ACCESSORIES, PHOTOGRAPHY, PRODUCTIVITY_AND_EFFICIENCY, ROMANCE, SCIENCE, SENSORY_EXPERIENCES, SHOWS_FESTIVALS_AND_EXHIBITIONS, SOFTWARE_AND_APPS, SPECIAL_EFFECTS, SPORTS, SPORTS_AND_OUTDOOR, SUPERNATURAL_AND_HORROR, TECHNOLOGY, TOYS_COLLECTIBLES_AND_MEMORABILIA, TRAVEL, VEHICLE_AND_TRANSPORTATION, VIDEO_GAMES, WILDLIFE_AND_EXOTIC_PETS +- `search_terms` (array, 0-3 terms, optional): Optional search terms to filter results. If you do not send them, the tool returns the top hashtags for the other parameters +- `category_name` (string, optional): Filter by TikTok category. If you do not send it, a query with search terms includes all categories. A query without search terms then uses the cross-category `"ALL"` leaderboard by default. Available categories: ALL, ACADEMIC_RESOURCES, ANIMATION_AND_COMICS, APPAREL_AND_ACCESSORIES, ART, AUTOMOTIVE, BABY_CARE, BABY_KIDS_AND_MATERNITY, BEAUTY, BEAUTY_AND_PERSONAL_CARE, BEAUTY_SERVICES, BUSINESS_AND_FINANCE, BUSINESS_SERVICES, CARD_AND_BOARD_GAMES, CAREER_AND_PROFESSIONAL_GROWTH, COLLEGE, COMEDY, COMMUNITY_UPDATES_AND_ISSUES, CONVENTIONAL_AND_MAINSTREAM_SPORTS, COOKING, CRAFTING_AND_CREATIONS, CULTURE, DANCE, DIARY_AND_VLOG, DRINKS, EATING_EXPERIENCES, EDUCATION, ENTERTAINMENT_AND_SPORTS_NEWS, ENVIRONMENT, EXERCISE_AND_FITNESS, EXTREME_AND_ADVENTURE_SPORTS, FAMILY, FINANCIAL_SERVICES, FOOD, FOOD_AND_BEVERAGE, FOOD_RECOMMENDATIONS, GADGETS_AND_INNOVATION, GAMES, GENERAL_TRAVEL, HAIR_CARE, HEALTH, HEALTH_AND_WELLNESS, HISTORY_AND_LITERATURE, HOME_AND_GARDEN, HOME_IMPROVEMENT, HOUSEHOLD_PRODUCTS, LEARNING_AND_DEVELOPMENT, LEISURE_AND_RECREATION_FACILITIES, LIFE_SERVICES, LIVESTOCK_AND_FARMING, MISCELLANEOUS_PERFORMANCES, MOVIES_AND_TV, MUSIC, NEWS_AND_ENTERTAINMENT, OTHER_BEAUTY, OTHER_FASHION, OTHER_TRANSPORTATION, OUTDOOR_RECREATION, OUTFITS, PERFORMING_ARTS, PERSONAL_PHOTOGRAPHY, PETS, PET_CARE_AND_ACCESSORIES, PHOTOGRAPHY, PRODUCTIVITY_AND_EFFICIENCY, ROMANCE, SCIENCE, SENSORY_EXPERIENCES, SHOWS_FESTIVALS_AND_EXHIBITIONS, SOFTWARE_AND_APPS, SPECIAL_EFFECTS, SPORTS, SPORTS_AND_OUTDOOR, SUPERNATURAL_AND_HORROR, TECHNOLOGY, TOYS_COLLECTIBLES_AND_MEMORABILIA, TRAVEL, VEHICLE_AND_TRANSPORTATION, VIDEO_GAMES, WILDLIFE_AND_EXOTIC_PETS - `date_range` (string, optional): Filter by date range (default: `"1DAY"`). Available options: `"1DAY"`, `"7DAY"`, `"30DAY"`, `"120DAY"` -- `country` (array, optional): Filter by country, as uppercase ISO 3166-1 alpha-2 codes (max 5). Supported: US, GB, CA, DE, ES, TR, ZA, NG, CN, IN, PH, TH, MX, BR, AR, FR, IT, NL, PL, AU, AE, JP, PT, KR, VN. Lowercase codes are accepted and upcased. When omitted, returns hashtags across all available countries -- `limit` (int, optional): Number of results per search term, or total results if no search term (default: 50, max: 200) -- `include_total_statistics` (bool, optional, default `true`): When `false`, omits `aggregate_stats`. Unlike the other tools, these statistics are computed over the returned rows (not the full dataset), so disabling them reduces response size but does not speed up the search +- `country` (array, optional): Filter by country, as uppercase ISO 3166-1 alpha-2 codes (max 5). Supported: US, GB, CA, DE, ES, TR, ZA, NG, CN, IN, PH, TH, MX, BR, AR, FR, IT, NL, PL, AU, AE, JP, PT, KR, VN. The tool accepts lowercase codes and changes them to uppercase. If you do not send it, the tool returns hashtags from all available countries +- `limit` (int, optional): Number of results for each search term, or total results if there is no search term (default: 50, max: 200) +- `include_total_statistics` (bool, optional, default `true`): If `false`, the response does not include `aggregate_stats`. In this tool, the statistics are for the returned rows only (not the full dataset). This is different from the other tools. Thus, if you disable them, the response is smaller, but the search is not faster Each row in `hashtags` includes `hashtag_name`, `rank_position`, `rank_change` (`"NEW"` or a signed position change), `posts`, `posts_global_lifetime`, `views`, `views_global_lifetime`, `category_name`, `country_code`, `date_range`, @@ -444,12 +446,12 @@ Each row in `hashtags` includes `hashtag_name`, `rank_position`, `rank_change` ( ### get_audience_targeting -Generate audience targeting segments for specific ad platforms based on an audience description. +Generate audience targeting segments for specific ad platforms from an audience description. **Parameters**: - `audience_name` (string, required): The name of the audience to target (e.g., "Tech Enthusiasts", "Fitness Enthusiasts") - `audience_description` (string, required): A description of the audience to target (e.g., "Young professionals interested in technology and innovation") -- `platform` (string, required): Which platform to target. Available platforms: `Programmatic`, `YouTube`, `Pinterest`, `LinkedIn`, `TikTok`, `Snapchat`, `Meta`, `X`, `Reddit`, `Spotify`, `Search`. Matched case-insensitively; any other value returns an error. Always pass `X` for Twitter +- `platform` (string, required): Which platform to target. Available platforms: `Programmatic`, `YouTube`, `Pinterest`, `LinkedIn`, `TikTok`, `Snapchat`, `Meta`, `X`, `Reddit`, `Spotify`, `Search`. The match is case-insensitive. All other values return an error. Always send `X` for Twitter **Platform-Specific Targeting Types**: @@ -465,12 +467,12 @@ Generate audience targeting segments for specific ad platforms based on an audie - **Reddit**: interest_groups, keywords - **Search**: keywords -Keywords and hashtags are written for the audience rather than chosen from the platform's published segment list. Every -other targeting type is chosen from that list. +The tool writes keywords and hashtags for the audience. It does not select them from the published segment list of the +platform. The tool selects all other targeting types from that list. -**Returns**: a JSON object with two keys, both varying by platform: -- `demographics`: age, gender, income, parental status and similar options. YouTube and Search share the same demographic options -- `segments`: one list per targeting type above +**Returns**: a JSON object with two keys. The contents of both keys are different for each platform: +- `demographics`: age, gender, income, parental status and similar options. YouTube and Search use the same demographic options +- `segments`: one list for each targeting type above **Example**: ```json @@ -498,24 +500,24 @@ other targeting type is chosen from that list. ### get_youtube_videos -Search individual YouTube videos by keyword and publish date, from the Sightly curated YouTube dataset. Returns -videos, not creator analysis; for audience, engagement or partnership questions, use +Search individual YouTube videos by keyword and publish date, in the Sightly curated YouTube dataset. This tool +returns videos, not creator analysis. For audience, engagement or partnership questions, use [`get_youtube_creator_insights`](#get_youtube_creator_insights). **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Search terms for video title/description. If not provided, returns top videos sorted by view count (highest first). Cannot be combined with `sort_by` -- `start_date` (string, optional): Start of the video publish date range (`YYYY-MM-DD`, earliest `2005-02-14`). While `include_total_statistics` is `true` the range may not exceed 180 days; omit this to search the 180 days ending at `end_date` (or today) +- `search_terms` (array, 0-3 terms, optional): Search terms for video title/description. If you do not send them, the tool returns the top videos, sorted by view count (highest first). You cannot use it with `sort_by` +- `start_date` (string, optional): Start of the video publish date range (`YYYY-MM-DD`, earliest `2005-02-14`). When `include_total_statistics` is `true`, the range must not be more than 180 days. If you do not send it, the tool searches the 180 days that end at `end_date` (or today) - `end_date` (string, optional): End of the video publish date range (`YYYY-MM-DD`, earliest `2005-02-14`) - `language` (array, optional): Filter by language codes (e.g., `"en"`, `"es"`) - max 5 -- `country` (array, optional): Filter by the channel's country as uppercase ISO 3166-1 alpha-2 codes (e.g., `"US"`, `"GB"`) - max 5. Case-sensitive: lowercase codes match nothing, and the UK's code is `GB`, not `UK` -- `iab_category` (array, optional): Filter by IAB taxonomy category names (e.g., `"Sports"`, `"Music"`) - max 5. Case-insensitive substring match, so `"Sports"` also matches more specific categories that contain it -- `is_short` (boolean, optional): Filter by video type: `true` for Shorts, `false` for long-form, omit for all +- `country` (array, optional): Filter by the channel's country as uppercase ISO 3166-1 alpha-2 codes (e.g., `"US"`, `"GB"`) - max 5. Case-sensitive: lowercase codes match nothing, and the code for the UK is `GB`, not `UK` +- `iab_category` (array, optional): Filter by IAB taxonomy category names (e.g., `"Sports"`, `"Music"`) - max 5. A case-insensitive substring match. Thus, `"Sports"` also matches more specific categories that contain it +- `is_short` (boolean, optional): Filter by video type: `true` for Shorts, `false` for long-form. Do not send it to get all videos - `exclude_kids_content` (boolean, optional): Exclude kids content when `true` - `min_views` (int, optional): Minimum view count threshold - `min_channel_subscribers` (int, optional): Minimum channel subscriber count -- `sort_by` (string, optional): Only valid without search terms. Options: `"size"` (default, view count - most viewed) or `"recency"` (newest videos first) -- `limit` (int, optional): Results per search term (default: 10, max: 50) -- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster and removes the 180-day cap +- `sort_by` (string, optional): Valid only without search terms. Options: `"size"` (default, view count - most viewed) or `"recency"` (newest videos first) +- `limit` (int, optional): Results for each search term (default: 10, max: 50) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` to get only sample records. This is significantly faster and removes the 180-day cap Each video in `sample_youtube_videos` includes `title`, `description`, `video_id`, `url`, `published`, `views`, `likes`, `duration` (seconds), `is_short`, `language`, `country`, `categories`, `channel_id`, `channel_title`, and @@ -562,23 +564,23 @@ Each video in `sample_youtube_videos` includes `title`, `description`, `video_id ### get_youtube_channels -Search YouTube channels by keyword in their title or description, from the Sightly curated YouTube dataset. -Carries no audience or engagement data; pass `channel_id` values from here to -[`get_youtube_creator_insights`](#get_youtube_creator_insights) for a full profile. +Search YouTube channels by keyword in their title or description, in the Sightly curated YouTube dataset. This tool +has no audience or engagement data. For a full profile, send the `channel_id` values from this tool to +[`get_youtube_creator_insights`](#get_youtube_creator_insights). **Parameters**: -- `search_terms` (array, 0-3 terms, optional): Search terms for channel title/description. If not provided, returns top channels sorted by subscriber count (highest first). Cannot be combined with `sort_by` -- `start_date` (string, optional): Start of the latest-video publish date range (`YYYY-MM-DD`, earliest `2005-02-14`). While `include_total_statistics` is `true` the range may not exceed 180 days; omit this to search the 180 days ending at `end_date` (or today) +- `search_terms` (array, 0-3 terms, optional): Search terms for channel title/description. If you do not send them, the tool returns the top channels, sorted by subscriber count (highest first). You cannot use it with `sort_by` +- `start_date` (string, optional): Start of the latest-video publish date range (`YYYY-MM-DD`, earliest `2005-02-14`). When `include_total_statistics` is `true`, the range must not be more than 180 days. If you do not send it, the tool searches the 180 days that end at `end_date` (or today) - `end_date` (string, optional): End of the latest-video publish date range (`YYYY-MM-DD`, earliest `2005-02-14`) - `language` (array, optional): Filter by language codes (e.g., `"en"`, `"es"`) - max 5 -- `country` (array, optional): Filter by the channel's country as uppercase ISO 3166-1 alpha-2 codes (e.g., `"US"`, `"GB"`) - max 5. Case-sensitive: lowercase codes match nothing, and the UK's code is `GB`, not `UK` +- `country` (array, optional): Filter by the channel's country as uppercase ISO 3166-1 alpha-2 codes (e.g., `"US"`, `"GB"`) - max 5. Case-sensitive: lowercase codes match nothing, and the code for the UK is `GB`, not `UK` - `exclude_kids_content` (boolean, optional): Exclude kids content when `true` - `min_subscribers` (int, optional): Minimum subscriber count threshold - `min_views` (int, optional): Minimum total view count threshold - `min_video_count` (int, optional): Minimum video count on channel -- `sort_by` (string, optional): Only valid without search terms. Options: `"size"` (default, subscriber count - most popular) or `"recency"` (recently active channels first) -- `limit` (int, optional): Results per search term (default: 10, max: 50) -- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` for sample records only, which is significantly faster and removes the 180-day cap +- `sort_by` (string, optional): Valid only without search terms. Options: `"size"` (default, subscriber count - most popular) or `"recency"` (recently active channels first) +- `limit` (int, optional): Results for each search term (default: 10, max: 50) +- `include_total_statistics` (bool, optional, default `true`): Include the `aggregate_stats` block. Set `false` to get only sample records. This is significantly faster and removes the 180-day cap Each channel in `sample_youtube_channels` includes `title`, `description`, `channel_id`, `url`, `subscribers`, `video_count`, `total_views`, `latest_video_published`, `language`, `country`, and `categories`. @@ -625,38 +627,39 @@ Each channel in `sample_youtube_channels` includes `title`, `description`, `chan ### get_youtube_creator_insights -Discover and analyse YouTube creators, and track content trends, using Google's YouTube advertising data. This is -distinct from `get_youtube_videos` and `get_youtube_channels`, which search Sightly's own curated corpus by keyword and -date. Use those for historical content search; use this one for creator discovery, partnership suitability, audience -composition and trend trajectories. +Find and analyze YouTube creators, and track content trends, with the YouTube advertising data from Google. This tool +is different from `get_youtube_videos` and `get_youtube_channels`. Those tools search the curated corpus of Sightly by +keyword and date. Use those tools to search historical content. Use this tool to find creators and to examine +partnership suitability, audience composition and trend trajectories. -There are three creator modes, which are mutually exclusive. Provide exactly one of `topic`, `channel_ids`, or the +There are three creator modes. You can use only one mode at a time. Send exactly one of `topic`, `channel_ids`, or the audience filters: | Mode | Use when | Returns | |------|----------|---------| -| `topic` | Finding creators who cover a subject | Creators ranked by relevance to that topic | -| `channel_ids` | You already know the channels | Full profiles; the only mode with audience demographics and top videos | -| Audience filters | Finding creators by who watches them | Creators whose viewers match the profile | +| `topic` | You want creators who make content about a subject | Creators ranked by relevance to that topic | +| `channel_ids` | You already know the channels | Full profiles. This is the only mode with audience demographics and top videos | +| Audience filters | You want creators with a specific type of viewer | Creators with viewers that match the profile | **Parameters**: -- `insight_type` (string, optional, default `"creators"`): `"creators"` finds or profiles creators; `"trends"` returns three years of monthly trend history for a topic, or what is trending for an audience -- `topic` (string, optional): A subject in plain words (e.g. `"electric vehicles"`, `"Nike"`). Matched internally to a Google Knowledge Graph entity; the match is returned as `resolved_topic` so an ambiguous term can be checked and retried -- `channel_ids` (array, optional, max 50): YouTube channel IDs such as `"UCX6OQ3DkcsbYNE6H8uQQuVA"`. Channel names cannot be looked up here; get IDs from `get_youtube_channels` first. Only the first `limit` IDs are profiled (10 by default) and the rest are silently dropped, so raise `limit` when passing more than 10. Not valid with `insight_type="trends"` +- `insight_type` (string, optional, default `"creators"`): `"creators"` finds creators or gets their profiles. `"trends"` returns three years of monthly trend history for a topic, or the current trends for an audience +- `topic` (string, optional): A subject in plain words (e.g. `"electric vehicles"`, `"Nike"`). The tool matches it to a Google Knowledge Graph entity. The response gives the match as `resolved_topic`. Thus, you can examine an ambiguous term and try again +- `channel_ids` (array, optional, max 50): YouTube channel IDs such as `"UCX6OQ3DkcsbYNE6H8uQQuVA"`. You cannot use channel names here. First, get the IDs from `get_youtube_channels`. The tool gets profiles only for the first `limit` IDs (10 by default) and silently ignores the other IDs. Thus, if you send more than 10 IDs, increase `limit`. Not valid with `insight_type="trends"` - `audience_age_ranges` (array, optional, max 5): Viewer age ranges: `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, `65+` - `audience_genders` (array, optional, max 5): Viewer genders: `male`, `female` -- `audience_interests` (array, optional, max 5): Viewer interests in plain words (e.g. `"cooking"`). Describes the audience's interests, whereas `topic` describes what the creator makes content about. Each interest is matched to a Google Knowledge Graph entity; an interest that cannot be matched returns an error -- `country` (string, optional, default `"us"`): ISO 3166-1 alpha-2 code in any case (the UK is `gb`, Japan `jp`, India `in`). Creator results, audience data and trends are all specific to this country. Supports the 219 countries Google Ads can target, which excludes Taiwan (`tw`), Hong Kong (`hk`), and Puerto Rico (`pr`); any other code returns an error -- `limit` (int, optional): Defaults to 15 for creator searches and 10 for channel profiles (max 50 for profiles, 100 otherwise). Ignored for trends, which return at most 5 -- `include_brand_sentiment` (bool, optional, default `false`): Only applies with `insight_type="trends"` and a `topic` naming a brand. Returns up to 6 months of positive/neutral/negative view share plus AI-written summaries of what drove the positive and negative sentiment, derived from video content only (never comments). Fails for non-brand topics -- `include_top_videos` (bool, optional, default `true`): Only applies to channel profiles. Set `false` to roughly halve the response when you need only channel metrics and audience demographics +- `audience_interests` (array, optional, max 5): Viewer interests in plain words (e.g. `"cooking"`). This parameter tells the interests of the audience. `topic` tells the subject of the content of the creator. The tool matches each interest to a Google Knowledge Graph entity. If the tool cannot match an interest, it returns an error +- `country` (string, optional, default `"us"`): ISO 3166-1 alpha-2 code in any case (the UK is `gb`, Japan `jp`, India `in`). Creator results, audience data and trends are all specific to this country. Supports the 219 countries that Google Ads can target. These countries do not include Taiwan (`tw`), Hong Kong (`hk`), and Puerto Rico (`pr`). All other codes return an error +- `limit` (int, optional): The default is 15 for creator searches and 10 for channel profiles (max 50 for profiles, 100 for the other modes). The tool ignores it for trends, which return a maximum of 5 +- `include_brand_sentiment` (bool, optional, default `false`): Applies only with `insight_type="trends"` and a `topic` that names a brand. Returns a maximum of 6 months of positive/neutral/negative view share. It also returns AI-written summaries of the causes of the positive and negative sentiment. These summaries come only from video content (never comments). Fails for topics that are not brands +- `include_top_videos` (bool, optional, default `true`): Applies only to channel profiles. If you need only channel metrics and audience demographics, set `false`. This makes the response about half the size -**Data sharing consent**: Google gates non-public fields behind each creator's consent. When `data_sharing_consent` is -`false`, `engagement_rate`, the per-video averages, `languages` and `audience` are absent (not zero) for that creator. -Roughly a quarter of creators withhold consent, and large official channels often do. +**Data sharing consent**: Google shows fields that are not public only if the creator gives consent. When +`data_sharing_consent` is `false`, the response for that creator does not have `engagement_rate`, the per-video +averages, `languages` and `audience`. These fields are absent, not zero. About a quarter of creators do not give +consent. Large official channels frequently do not give consent. -**No pagination**: Google returns roughly a thousand creators per search with no paging. `total_available` reports how -many matched; raise `limit` rather than expecting a second page. +**No pagination**: Google returns about a thousand creators for each search, with no pages. `total_available` gives the +number of matches. Do not expect a second page. Increase `limit`. **Example - find creators covering a topic**: ```json @@ -705,58 +708,60 @@ many matched; raise `limit` rather than expecting a second page. ``` **Response fields**: -- `country`: the country searched -- `resolved_topic`: the Knowledge Graph entity your topic text matched (`query`, `name`, `machine_id`, `description`), with `other_matches` listing alternatives -- `total_available` / `returned`: how many creators, channels or trends matched, versus how many were returned -- `channels_not_found`: requested channel IDs Google did not recognise +- `country`: the country of the search +- `resolved_topic`: the Knowledge Graph entity that matches your topic text (`query`, `name`, `machine_id`, `description`). `other_matches` lists alternatives +- `total_available` / `returned`: the number of creators, channels or trends that matched, and the number that the tool returned +- `channels_not_found`: requested channel IDs that Google did not recognize - `creators[]`: `name`, `channel_id`, `handle`, `channel_created`, `country`, `languages`, `relevance`, `data_sharing_consent`, `metrics` - `profiles[]`: `name`, `channel_id`, `handle`, `channel_created`, `country`, `channel_type`, `languages`, `data_sharing_consent`, `metrics`, plus `audience` (viewer share by age range, gender, device and country), `content_topics`, and `top_videos` (up to 5). Profiles carry no relevance - `trends[]`: `name`, trend direction, `views`, `views_indexed`, `audience_share`, `change_percent`, `history` (monthly), `brand_sentiment` -- `metrics`: subscribers, views, videos, likes, comments, Shorts views and videos, `engagement_rate`, per-video averages, whether the creator is an active Shorts or live stream creator, and `partnership_opportunities` (advertising products the creator is eligible for) +- `metrics`: subscribers, views, videos, likes, comments, Shorts views and videos, `engagement_rate`, per-video averages, whether the creator is an active Shorts or live stream creator, and `partnership_opportunities` (advertising products that the creator is eligible for) **Reading trends**: -- Trend data lags by roughly two months; the newest month is the latest Google has published -- `change_percent` is a fraction (`0.19` = +19%). At the top level it compares the latest month with three months earlier; within `history`, each month compares with the month before -- `views_indexed` is 0-100 against the topic's own peak month, so it cannot be compared across topics +- Trend data is about two months late. The newest month is the latest month that Google published +- `change_percent` is a fraction (`0.19` = +19%). At the top level, it compares the latest month with the month three months before. In `history`, it compares each month with the month before +- `views_indexed` is 0-100, relative to the peak month of the topic. Thus, you cannot compare it between topics - `views` is the absolute view count for the latest month only -- `history` covers 36 months, newest first, for topic trends only. Audience trends return `audience_share` instead: the fraction of the requested audience that searched for or viewed the trend -- `brand_sentiment` shares are proportions of views and sum to 1 per month. Months Google lacks enough data for carry no shares +- `history` includes 36 months, newest first, for topic trends only. Audience trends return `audience_share` in its place. This is the fraction of the requested audience that searched for or viewed the trend +- `brand_sentiment` shares are proportions of views, and their sum is 1 for each month. If Google does not have sufficient data for a month, that month has no shares ## Response Structure ### Output Format -Every tool returns its result as a single text block: +All tools return their result as one text block: -- **Results found**: a short data context (guidance on how to interpret the payload), a blank line, then the payload. The payload is JSON for every tool except `get_brand_profile`, which returns plain text. -- **Nothing found**: a short plain-text message with no JSON, such as `No News Articles found for: . Try broader search terms or expand the date range.` This happens when no search term returns a result, when no brand profile matches, and when `get_youtube_creator_insights` finds no creators, profiles, or trends. When at least one search term returns results, the terms without any come back with an empty `sample_*` list instead. -- **Invalid input**: a tool error describing the problem, such as an unknown audience-targeting platform, `sort_by` sent with `search_terms`, or a YouTube date range wider than 180 days. +- **Results found**: a short data context (guidance about how to interpret the payload), a blank line, then the payload. The payload is JSON for all tools except `get_brand_profile`, which returns plain text. +- **Nothing found**: a short plain-text message with no JSON, such as `No News Articles found for: . Try broader search terms or expand the date range.` This occurs when no search term returns a result, when no brand profile matches, and when `get_youtube_creator_insights` finds no creators, profiles, or trends. If one or more search terms return results, the terms without results have an empty `sample_*` list. +- **Invalid input**: a tool error that describes the problem. Examples are an unknown audience-targeting platform, `sort_by` sent with `search_terms`, or a YouTube date range of more than 180 days. ### Search Tool Payloads `get_trends`, `get_news_moments`, `get_social_media_narratives`, `get_news_articles`, `get_social_media_posts`, -`get_youtube_videos`, and `get_youtube_channels` share one shape: +`get_youtube_videos`, and `get_youtube_channels` use one shape: -- `search_start_date` / `search_end_date`: the range actually searched. `YYYY-MM-DD` for trends, narratives, and the YouTube tools; `YYYY-MM-DDTHH:MM:SS` for moments, articles, and posts. -- `search_results`: one entry per search term, or a single entry when browsing without search terms. Each entry holds: - - `search_term`: the term, omitted when browsing without search terms - - `aggregate_stats`: population statistics, omitted when `include_total_statistics=false` +- `search_start_date` / `search_end_date`: the range that the tool searched. `YYYY-MM-DD` for trends, narratives, and the YouTube tools. `YYYY-MM-DDTHH:MM:SS` for moments, articles, and posts. +- `search_results`: one entry for each search term, or one entry if you browse without search terms. Each entry contains: + - `search_term`: the term. Not included if you browse without search terms + - `aggregate_stats`: population statistics. Not included when `include_total_statistics=false` - the sample list: `sample_trends`, `sample_news_moments`, `sample_social_media_narratives`, `sample_news_articles`, `sample_social_media_posts`, `sample_youtube_videos`, or `sample_youtube_channels` -`aggregate_stats.total_matches` is the number of records matching the query in the whole database, while the -`sample_*` list holds representative examples capped by `limit`. Fields with no value are omitted from records rather -than returned as null. +`aggregate_stats.total_matches` is the number of records in the full database that match the query. The `sample_*` +list contains representative examples, with a maximum set by `limit`. The records do not include fields with no value. +The tools do not return these fields as null. + +The other tools have their own shapes. Their sections describe these shapes: -The other tools have their own shapes, described in their sections: `get_tiktok_hashtags` returns `hashtags` rows with -statistics over those rows, `get_youtube_creator_insights` returns creators, profiles, or trends with -`total_available` and `returned`, `get_audience_targeting` returns `demographics` and `segments`, and -`get_brand_profile` returns plain text. +- `get_tiktok_hashtags` returns `hashtags` rows, with statistics for those rows. +- `get_youtube_creator_insights` returns creators, profiles, or trends, with `total_available` and `returned`. +- `get_audience_targeting` returns `demographics` and `segments`. +- `get_brand_profile` returns plain text. ### Aggregate Statistics -Statistics cover every record matching the query, not just the returned sample. They are expensive to compute, so pass -`include_total_statistics=false` when you only need a few example records; the search is then significantly faster. -`get_youtube_creator_insights` has no `include_total_statistics` parameter. +The statistics include all records that match the query, not only the returned sample. The calculation of the +statistics takes much time. Thus, if you need only some example records, send `include_total_statistics=false`. The +search is then significantly faster. `get_youtube_creator_insights` has no `include_total_statistics` parameter. - `get_social_media_posts`: `total_matches`, `platform_distribution`, `top_themes_distribution`, `language_distribution`, `date_distribution`, `likes_stats`, `comments_stats`, `shares_stats` - `get_news_articles`: `total_matches`, `top_publishers_distribution`, `top_categories_distribution`, `top_iab_categories_distribution`, `publisher_location_distribution`, `language_code_distribution`, `date_distribution` @@ -765,21 +770,21 @@ Statistics cover every record matching the query, not just the returned sample. - `get_social_media_narratives`: `total_matches`, `total_post_count`, `sentiment_distribution` (negative, neutral, positive), `platform_distribution`, `country_distribution`, `narrative_size_distribution`, `narratives_per_day_date_distribution`, `total_likes_stats`, `total_comments_stats`, `total_shares_stats` - `get_news_moments`: `total_matches`, `total_article_count`, `moment_size_distribution`, `moments_per_day_date_distribution` - `get_trends`: `total_matches`, `total_article_count`, `total_post_count`, `top_brands_distribution`, `top_people_distribution`, `trends_per_day_date_distribution` -- `get_tiktok_hashtags`: `views_distribution`, `posts_distribution`, `rank_change_distribution`, `top_country_distribution`, computed over the returned rows rather than the full dataset +- `get_tiktok_hashtags`: `views_distribution`, `posts_distribution`, `rank_change_distribution`, `top_country_distribution`. The tool calculates these for the returned rows only, not for the full dataset -Notes on reading these: +How to read these statistics: -- **Date distributions** are `{"interval": ..., "buckets": [{"date": ..., "count": ...}]}` with up to 30 buckets. The interval (for example `1d`, `7d`, or `1M`) is chosen automatically to fit the searched range, so the `*_per_day_date_distribution` series are not always daily. -- **Cluster dates**: the `*_per_day_date_distribution` series count clusters (when stories broke, conversations started, or trends concluded), not their contents. For article or post volume over time, use `get_news_articles` or `get_social_media_posts`. -- **Multi-valued fields** (a narrative's platforms, an article's categories) count a record in every bucket it belongs to, so buckets can sum to more than `total_matches`. -- **Truncation**: distributions keyed by value (platforms, themes, languages, countries, publishers, categories, brands, people) list only the most frequent values, so a missing key means zero or a value outside the top ones. Range and date distributions list every bucket, including empty ones. -- **Engagement stats**: each `*_stats` object has `count`, `min`, `max`, `avg`, and `sum`. `count` reflects only records that have a value for that metric, so compare it to `total_matches` to gauge coverage. +- **Date distributions** are `{"interval": ..., "buckets": [{"date": ..., "count": ...}]}` with a maximum of 30 buckets. The tool automatically selects the interval (for example `1d`, `7d`, or `1M`) for the searched range. Thus, the `*_per_day_date_distribution` series are not always daily. +- **Cluster dates**: the `*_per_day_date_distribution` series count clusters, not their contents. The date is when a story started, when a conversation started, or when a trend ended. For article or post volume over time, use `get_news_articles` or `get_social_media_posts`. +- **Multi-valued fields** (the platforms of a narrative, the categories of an article) count a record in each bucket that applies to it. Thus, the sum of the buckets can be more than `total_matches`. +- **Truncation**: distributions by value (platforms, themes, languages, countries, publishers, categories, brands, people) list only the most frequent values. Thus, a missing key means zero or a value that is not in the top values. Range and date distributions list all buckets, also empty buckets. +- **Engagement stats**: each `*_stats` object has `count`, `min`, `max`, `avg`, and `sum`. `count` includes only records that have a value for that metric. To find how many records have the metric, compare `count` with `total_matches`. ### Timelines -`article_count_timeline` (trends and moments) and `post_count_timeline` (trends) show a record's own volume over its -lifetime. Records with 14 or fewer days of activity get one entry per active day; records with 15 to 90 days are -grouped into 7-day entries, and longer ones into calendar months. +`article_count_timeline` (trends and moments) and `post_count_timeline` (trends) show the volume of a record during +its full life. Records with 14 days of activity or less have one entry for each active day. Records with 15 to 90 days +have 7-day entries. Longer records have entries for calendar months. ### Example Response Structure @@ -814,42 +819,42 @@ A `get_social_media_posts` response: ### Dates -- **Date-only format** (`YYYY-MM-DD`): used by `get_trends` and `get_social_media_narratives`, earliest `2026-01-01` -- **UTC datetime format** (`YYYY-MM-DDTHH:MM:SS`): used by `get_news_articles`, `get_news_moments`, and `get_social_media_posts`, earliest `2026-01-01T00:00:00`. Naive UTC; do not include a timezone offset. For a whole-day search use `T00:00:00` to `T23:59:59` +- **Date-only format** (`YYYY-MM-DD`): for `get_trends` and `get_social_media_narratives`, earliest `2026-01-01` +- **UTC datetime format** (`YYYY-MM-DDTHH:MM:SS`): for `get_news_articles`, `get_news_moments`, and `get_social_media_posts`, earliest `2026-01-01T00:00:00`. Naive UTC. Do not include a timezone offset. For a whole-day search, use `T00:00:00` to `T23:59:59` - **YouTube tools** (`get_youtube_videos`, `get_youtube_channels`): `YYYY-MM-DD`, earliest `2005-02-14` -- **Default**: if not provided, the start date is the earliest available date -- **180-day YouTube cap**: while `include_total_statistics` is `true` (the default), the YouTube tools search at most 180 days. An omitted `start_date` defaults to the 180 days ending at `end_date` (or today), and an explicit range wider than 180 days returns an error. Send `include_total_statistics: false` to search the full history without population statistics -- **What the range filters on**: an article's or post's publish date, a moment's or narrative's earliest article or post, a trend's latest publish date, a video's publish date, and a channel's latest video publish date +- **Default**: if you do not send a start date, the start date is the earliest available date +- **180-day YouTube cap**: when `include_total_statistics` is `true` (the default), the YouTube tools search a maximum of 180 days. If you do not send `start_date`, the tools search the 180 days that end at `end_date` (or today). An explicit range of more than 180 days returns an error. To search the full history without population statistics, send `include_total_statistics: false` +- **What the range filters on**: the publish date of an article or post, the earliest article or post of a moment or narrative, the latest publish date of a trend, the publish date of a video, and the latest video publish date of a channel ### Countries -Each tool supports a different set of countries and expects its own code format: +Each tool supports a different set of countries and uses its own code format: | Tool | Parameter | Format | Supported countries | |------|-----------|--------|---------------------| -| `get_social_media_posts` | `country` | ISO 3166-1 alpha-2, any case | Any country (about half of posts carry one) | +| `get_social_media_posts` | `country` | ISO 3166-1 alpha-2, any case | Any country (about half of posts have one) | | `get_social_media_narratives` | `country` | ISO 3166-1 alpha-2, any case | Any country | | `get_news_articles` | `publisher_location` | Full English name, one value | The 22 countries listed under [`get_news_articles`](#get_news_articles) | -| `get_tiktok_hashtags` | `country` | ISO 3166-1 alpha-2, uppercase (lowercase is upcased) | US, GB, CA, DE, ES, TR, ZA, NG, CN, IN, PH, TH, MX, BR, AR, FR, IT, NL, PL, AU, AE, JP, PT, KR, VN | +| `get_tiktok_hashtags` | `country` | ISO 3166-1 alpha-2, uppercase (the tool changes lowercase to uppercase) | US, GB, CA, DE, ES, TR, ZA, NG, CN, IN, PH, TH, MX, BR, AR, FR, IT, NL, PL, AU, AE, JP, PT, KR, VN | | `get_youtube_videos` | `country` | ISO 3166-1 alpha-2, uppercase only | Any country | | `get_youtube_channels` | `country` | ISO 3166-1 alpha-2, uppercase only | Any country | -| `get_youtube_creator_insights` | `country` (default `us`) | ISO 3166-1 alpha-2, any case | The 219 countries Google Ads can target (not Taiwan, Hong Kong or Puerto Rico) | +| `get_youtube_creator_insights` | `country` (default `us`) | ISO 3166-1 alpha-2, any case | The 219 countries that Google Ads can target (not Taiwan, Hong Kong or Puerto Rico) | | `get_trends`, `get_news_moments`, `get_audience_targeting`, `get_brand_profile` | None | | No country filter | -Two rules apply everywhere: +Two rules apply to all tools: -- The UK's code is `gb` (or `GB`), never `uk`. A `uk` value matches nothing on the search tools and returns an error on `get_tiktok_hashtags` and `get_youtube_creator_insights`. -- A country outside a tool's fixed list (`get_news_articles`, `get_tiktok_hashtags`, `get_youtube_creator_insights`) returns an error. On the tools that accept any country, an unknown or wrongly cased code returns no results rather than an error. +- The code for the UK is `gb` (or `GB`), never `uk`. A `uk` value matches nothing on the search tools. It returns an error on `get_tiktok_hashtags` and `get_youtube_creator_insights`. +- Some tools have a fixed list of countries (`get_news_articles`, `get_tiktok_hashtags`, `get_youtube_creator_insights`). A country that is not on the list returns an error. On the tools that accept all countries, an unknown code or a code with incorrect case returns no results, not an error. ### Search Terms -- 0-3 terms per request (optional for every tool that accepts them) -- Terms run in parallel when provided +- 0-3 terms for each request (optional for all tools that accept them) +- If you send terms, the tool runs them in parallel - For articles/posts: Keep complete concepts together - ✅ `["renewable energy policy"]` - ❌ `["renewable", "energy", "policy"]` -- **`sort_by` cannot be combined with `search_terms`**: for the tools that accept `sort_by` (`get_trends`, `get_news_moments`, `get_social_media_narratives`, `get_youtube_videos`, `get_youtube_channels`), sending both returns an error. When search terms are provided, results are ranked by relevance automatically, so omit `sort_by`. Use `"recency"` only when chronological ordering is explicitly wanted -- **Without search terms**: Tools return results sorted by a logical default, customizable with the `sort_by` parameter: +- **`sort_by` cannot be combined with `search_terms`**: some tools accept `sort_by` (`get_trends`, `get_news_moments`, `get_social_media_narratives`, `get_youtube_videos`, `get_youtube_channels`). If you send both parameters to these tools, they return an error. If you send search terms, the tools automatically rank results by relevance. Thus, do not send `sort_by`. Use `"recency"` only when the user explicitly wants chronological order +- **Without search terms**: Tools sort the results in a logical default order. You can change this order with the `sort_by` parameter: - Trends: default "size" (biggest trends), optional "recency" (most recent trends) - Moments: default "size" (biggest story clusters), optional "recency" (most recent moments) - Narratives: default "size" (most discussed), optional "recency" (most recent narratives) @@ -873,12 +878,13 @@ Two rules apply everywhere: - Audience targeting segments → `get_audience_targeting` - YouTube creators to partner with, their audience, or YouTube topic trends → `get_youtube_creator_insights` -The three YouTube tools cover different ground. `get_youtube_videos` and `get_youtube_channels` search Sightly's curated -historical corpus by keyword and date; use them to find content that was published. `get_youtube_creator_insights` uses -Google's advertising data; use it to discover creators, judge partnership suitability, see who watches a channel, or -track a topic's trajectory. Channel IDs flow one way: look a channel up with `get_youtube_channels`, then pass its ID to -`get_youtube_creator_insights` for the audience profile. +The three YouTube tools have different functions. `get_youtube_videos` and `get_youtube_channels` search the curated +historical corpus of Sightly by keyword and date. Use them to find published content. `get_youtube_creator_insights` +uses the advertising data from Google. Use it to find creators, to examine partnership suitability, to see the viewers +of a channel, or to track the trajectory of a topic. Channel IDs go in one direction only. First, find a channel with +`get_youtube_channels`. Then send its ID to `get_youtube_creator_insights` to get the audience profile. -Call more than one of these tools for the same question only when chaining channel IDs as above, or when the user asks -for both sources. `get_trends` covers news and social media, not YouTube. No tool ranks channels by growth or momentum, -so a request for "trending channels" is answered by the single best-fitting tool, with that limitation stated. +Call more than one of these tools for the same question only in two conditions. The first condition is when you send +channel IDs from one tool to the other, as above. The second condition is when the user asks for both sources. +`get_trends` includes news and social media, not YouTube. No tool ranks channels by growth or momentum. Thus, for a +request for "trending channels", use the one tool that is the best fit, and tell the user about this limit. From 738c1e45fbe2a70293998710731fc8dcc699de60 Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sun, 25 Oct 2026 10:33:34 +0100 Subject: [PATCH 19/23] Rewrite Python SDK docs in Simplified Technical English Co-Authored-By: Claude Opus 5.5 --- docs/developer-tools/index.md | 20 +- docs/developer-tools/python/advanced-usage.md | 96 +++++----- docs/developer-tools/python/authentication.md | 18 +- docs/developer-tools/python/basic-usage.md | 180 +++++++++--------- .../python/endpoints/audience-groups.md | 4 +- .../python/endpoints/audiences.md | 4 +- .../python/endpoints/brand-metric-groups.md | 4 +- .../python/endpoints/brand-metrics.md | 4 +- .../python/endpoints/brands.md | 4 +- .../python/endpoints/brandscape-data.md | 48 ++--- .../python/endpoints/categories.md | 10 +- .../python/endpoints/cities.md | 4 +- .../python/endpoints/collections.md | 4 +- .../python/endpoints/companies.md | 4 +- .../python/endpoints/countries.md | 4 +- .../developer-tools/python/endpoints/index.md | 32 ++-- .../python/endpoints/regions.md | 4 +- .../python/endpoints/sectors.md | 4 +- .../python/endpoints/studies.md | 4 +- .../developer-tools/python/endpoints/years.md | 4 +- docs/developer-tools/python/index.md | 29 +-- docs/developer-tools/python/installation.md | 24 +-- .../python/reference-classes.md | 35 ++-- docs/developer-tools/python/tools.md | 28 +-- 24 files changed, 279 insertions(+), 293 deletions(-) diff --git a/docs/developer-tools/index.md b/docs/developer-tools/index.md index 946f3e2..4850d7e 100644 --- a/docs/developer-tools/index.md +++ b/docs/developer-tools/index.md @@ -4,18 +4,18 @@ sidebar_label: Overview # Developer Tools and SDKs -Libraries and tools for interacting with your BAV API integration. +Libraries and tools to work with your BAV API integration. -We want to make it as easy as possible for you to work with the BAV API. With SDKs we take care of the heavy lifting for -you, so you can spend more time building your integration. +We want to make it as easy as possible for you to work with the BAV API. The SDKs do the difficult work for you. Thus, +you can spend more time on your integration. -Since BAV is an internal WPP product we don't have a dedicated team to build and maintain SDKs. Instead we rely on the -WPP community to help maintain SDKs for languages that they write in. By sharing the load we can ensure that the SDKs -are maintained and up to date, while saving time and effort for everyone. +BAV is an internal WPP product, so we do not have a dedicated team to build and maintain SDKs. Instead, we rely on the +WPP community to help maintain SDKs for the languages that they write in. When we share the work, we can make sure that +the SDKs stay maintained and up to date. This also saves time and effort for everyone. :::note -The collection of SDKs here are driven by community need and development. If you have done an integration with a -language we don't yet have an SDK for and would consider packaging it as an SDK and sharing, please let us know. +Community need and community development drive the collection of SDKs on this page. Did you make an integration in a +language that does not have an SDK yet? If you want to package it as an SDK and share it, let us know. ::: ## Python SDK @@ -26,9 +26,9 @@ The Python SDK is created and maintained by Ignacio Maiz at BAV@WPP. ## BAV API Specification -The API specifications will help you get set up with a broad range of API tools, such as Postman. +The API specifications help you set up a broad range of API tools, such as Postman. - [Postman Collection](/collections/bav-api-postman.json) - [Swagger Definition](/collections/bav-api-swagger.json) -*(right-click and select to download the file to your computer)* +*(To download a file to your computer, right-click the link and select the download option.)* diff --git a/docs/developer-tools/python/advanced-usage.md b/docs/developer-tools/python/advanced-usage.md index 3218a9e..a362818 100644 --- a/docs/developer-tools/python/advanced-usage.md +++ b/docs/developer-tools/python/advanced-usage.md @@ -7,28 +7,25 @@ sidebar_label: Advanced Usage import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -This section is intended for developers who are interested in embedding `bavapi` functionality into their APIs and -applications. +This section is for developers who want to embed `bavapi` functionality into their APIs and applications. :::info Async Support -`bavapi` natively supports asynchronous execution, so it is ready to work with popular `async` libraries such as +`bavapi` natively supports asynchronous execution, so it can work with popular `async` libraries such as [`fastapi`](https://fastapi.tiangolo.com/). ::: ## The `Client` interface -The `Client` class is the backbone of `bavapi`, and it is the recommended way to interact with the API for more -advanced users. +The `Client` class is the backbone of `bavapi`. For more advanced users, we recommend `Client` to work with the API. :::tip -If you're familiar with the `requests` or `httpx` python packages, this is similar to using `requests.Session()` or -`httpx.Client()`. +If you know the `requests` or `httpx` python packages, this is similar to `requests.Session()` or `httpx.Client()`. ::: -Using the `Client` class instead of the top-level endpoint functions (`bavapi.brands`, for example), can bring -significant performance improvements, especially when performing multiple requests at the same time. +The `Client` class can give significant performance improvements over the top-level endpoint functions (for example, +`bavapi.brands`). This is especially true when you send multiple requests at the same time. -The `Client` interface is based on `httpx.Client`, so it benefits from all the performance features from `httpx`: +The `Client` interface is based on `httpx.Client`, so it gets all the performance features of `httpx`: :::note Quote from the `httpx` [docs](https://www.python-httpx.org/advanced/) @@ -38,19 +35,18 @@ The `Client` interface is based on `httpx.Client`, so it benefits from all the p ::: -By using `Client`, you will also get all these benefits, including in Jupyter Notebooks. +When you use `Client`, you get all these benefits. This is also true in Jupyter Notebooks. ## Using the `Client` interface -It is recommended to use `Client` in an `async with` block: +We recommend that you use `Client` in an `async with` block: ```py async with bavapi.Client("TOKEN") as bav: result = await bav.brands("Swatch") ``` -Otherwise, it is possible to use `Client` methods outside of an `async with` block, but it might be slightly less -performant. +You can also use `Client` methods outside of an `async with` block, but the performance can be slightly lower. ```py bav = bavapi.Client("TOKEN") @@ -60,21 +56,21 @@ await bav.aclose() # Close the connection after you're done making requests ## Other endpoints -Because of the large number of available endpoints in the Fount and the highly customizable queries, some endpoints -won't have extended support from the start. +The Fount has a large number of endpoints, and the queries are highly customizable. Thus, some endpoints do not have +extended support from the start. :::note Open for feedback -If you would like to see new endpoints with full type annotations and validation support, please open an +If you want new endpoints with full type annotations and validation support, open an [issue](https://github.com/wppbav/bavapi-sdk-python/issues) on GitHub with the "Feature Request" template. ::: -`bavapi` provides `raw_query` functions/methods to access all the available endpoints without existing endpoint +`bavapi` has `raw_query` functions/methods. Use them to access the available endpoints that do not have endpoint functions/methods: - `bavapi.raw_query` for synchronous requests. - `bavapi.Client.raw_query` for asynchronous requests. -These `raw_query` methods require the use of `bavapi.Query` instances to make the request: +These `raw_query` methods require `bavapi.Query` instances to make the request: ```py async with bavapi.Client("TOKEN") as bav: @@ -84,7 +80,7 @@ async with bavapi.Client("TOKEN") as bav: ) ``` -These functions will return a list of JSON dictionaries, one for each entry retrieved from the Fount: +These functions return a list of JSON dictionaries, one for each entry from the Fount: ```json [ @@ -95,17 +91,17 @@ These functions will return a list of JSON dictionaries, one for each entry retr ``` :::tip -These methods are meant to be used for custom processing of data (not resulting in a `pandas` DataFrame), but it is -also possible to use some of the parsing functions available in `bavapising.responses`. +These methods are for custom data processing that does not make a `pandas` DataFrame. But you can also use some of +the parsing functions in `bavapising.responses`. ::: ## The `Query` class -`bavapi.Query` is a `pydantic`-powered class that holds and validates all the common (aside from -endpoint-specific filters) query parameters to pass to the Fount API. +`bavapi.Query` is a class that uses `pydantic`. It holds and validates all the common query parameters (not the +endpoint-specific filters) to send to the Fount API. -The default values for the class are the same as the default values in the Fount API itself, so an empty `Query` -object can be used to get all entries for a specific endpoint: +The default values for the class are the same as the default values in the Fount API. Thus, you can use an empty +`Query` object to get all entries for a specific endpoint: ```py query = bavapi.Query() @@ -115,7 +111,7 @@ async with bavapi.Client("TOKEN") as bav: res = await bav.raw_query("brand-metrics", query) ``` -`Query` can be used to set limits on the number of pages retrieved, or to request a specific page from a query: +You can use `Query` to limit the number of pages that you get, or to request a specific page from a query: ```py bavapi.Query( @@ -127,23 +123,24 @@ bavapi.Query( ### `Query` parameters -All Fount queries performed with `bavapi.Query` support the following parameters: +All Fount queries that use `bavapi.Query` support the following parameters: - `id`: Return only results for a specific id. - `page`: The page number of results to return. - `per_page`: The number of results to return per page. Default is 25 and maximum is 100. -- `max_pages`: The maximum number of pages to request. Defaults to requesting all pages in a query. +- `max_pages`: The maximum number of pages to request. By default, `bavapi` requests all pages in a query. - `fields`: The keys for the fields to include in the response. Usually they are the field name in lower case. - `sort`: The key(s) for the field(s) to order the response results by. - `include`: Additional linked resources to include in the response. -- `updated_since`: Only return items that have been updated since this timestamp. +- `updated_since`: Only return items that changed after this timestamp. -For more information on the behavior of each of these parameters, see the [customizing fields](/customizing/fields.md) +For more information about the behavior of each of these parameters, see the [customizing fields](/customizing/fields.md) section. ### Raw parameter dictionary -The `to_params` method can be used to parse the parameters into a dictionary of what will be sent to the Fount API: +Use the `to_params` method to parse the parameters into a dictionary. This dictionary shows what `bavapi` will send to +the Fount API: ```py >>> bavapi.Query( @@ -160,25 +157,24 @@ The `to_params` method can be used to parse the parameters into a dictionary of } ``` -1. Needs the endpoint name to format parameters correctly. -2. Parses `filters` and `include` into the correct format for the Fount API, and parses all elements in lists of +1. Needs the endpoint name to format the parameters correctly. +2. Parses `filters` and `include` into the correct format for the Fount API. Also parses all elements in lists of parameters to their string representation. ## Control `bavapi` batching behavior -`bavapi` will automatically batch paginated requests to the API to improve latency and throughput. Default values are -set to maintain around twenty concurrent requests at a time. +`bavapi` automatically batches paginated requests to the API to improve latency and throughput. The default values +keep about twenty concurrent requests at a time. -In addition, `bavapi` will also automatically retry failed requests a number of times (default `2`), which can be -defined by the user. +`bavapi` also automatically retries failed requests. You can set the number of retries (default `2`). Both top-level functions and the `Client` class have the following parameters to control the behavior of the requests: -- `batch_size`: Number of pages to include in each batch of requests, default `10`. -- `n_workers`: Number of worker coroutines that will make batched requests at once, default `2`. -- `retries`: Number of times to retry a page request before raising an exception, default `3`. -- `on_errors`: Whether to `"warn"` about failed requests at the end of the query, or `"raise"` immediately upon failure - (after retries), default `"warn"`. +- `batch_size`: Number of pages in each batch of requests, default `10`. +- `n_workers`: Number of worker coroutines that make batched requests at the same time, default `2`. +- `retries`: Number of times to retry a page request before `bavapi` raises an exception, default `3`. +- `on_errors`: Set to `"warn"` to get a warning about failed requests at the end of the query. Set to `"raise"` to + raise an exception immediately after a failure (after retries). Default `"warn"`. These parameters can be set in both top-level functions and the async `Client` class: @@ -212,22 +208,22 @@ async with bavapi.Client( -The query from the examples above will result in *25* concurrent API requests (5 `batch_size` * 5 `n_workers`), and -`bavapi` will retry each failed request *twice* (after the initial request). `on_errors="raise"` will ensure that an -exception is raised if all retries for any page result in exceptions. +The query in the examples above makes *25* concurrent API requests (5 `batch_size` * 5 `n_workers`). `bavapi` will +retry each failed request *twice* (after the initial request). If all retries for a page cause exceptions, +`on_errors="raise"` makes sure that `bavapi` raises an exception. :::caution -In order to avoid SSL and timeout issues, it is recommended to set `batch_size` and `n_workers` so `bavapi` will -perform at most 20-30 concurrent requests. The default is 20 concurrent requests (10 `batch_size` * 2 `n_workers`). +To prevent SSL and timeout problems, we recommend that you set `batch_size` and `n_workers` so that `bavapi` sends a +maximum of 20-30 concurrent requests. The default is 20 concurrent requests (10 `batch_size` * 2 `n_workers`). ::: ## User Agent -It is possible to set the `User Agent` parameter for HTTP requests. +You can set the `User Agent` parameter for HTTP requests. The default user agent is `"BAVAPI SDK Python"`. -If you want to change the user agent for your application, you can set it when instantiating a `Client`: +To change the user agent for your application, set it when you instantiate a `Client`: ```py bav = bavapi.Client(user_agent="Your User Agent") diff --git a/docs/developer-tools/python/authentication.md b/docs/developer-tools/python/authentication.md index f7652a1..038a135 100644 --- a/docs/developer-tools/python/authentication.md +++ b/docs/developer-tools/python/authentication.md @@ -1,11 +1,11 @@ # Authentication -Access to the API via the Python SDK works the same way as it does in the API as a whole. Please follow the -instructions in the [Authentication](/authentication.md) section of the main API documentation to get started. +Access to the API through the Python SDK works the same way as access to the API in general. To start, follow the +instructions in the [Authentication](/authentication.md) section of the main API documentation. -In order to keep your API token secure, you should avoid using your token directly in your code and applications. +To keep your API token secure, do not put your token directly in your code and applications. -Instead, place the code in a `.env` file at the top of your project directory, and use `python-dotenv` to load the +Instead, put the token in a `.env` file at the top of your project directory. Then use `python-dotenv` to load the token into your environment: ```prompt @@ -14,21 +14,21 @@ my-project-folder └─── ... (other stuff) ``` -Create this `.env` file (note the leading dot) in the top level of your working directory, and write down your token -like so: +Create this `.env` file (note the leading dot) in the top level of your working directory. Write your token in the +file as follows: ```env BAV_API_TOKEN = "your_token_here" ``` -To now use this file, you will need to install the [`python-dotenv`](https://github.com/theskumar/python-dotenv) +To use this file, install the [`python-dotenv`](https://github.com/theskumar/python-dotenv) package: ```prompt pip install python-dotenv ``` -Now, paste this code at the top of your Python files or Jupyter Notebooks: +Then, paste this code at the top of your Python files or Jupyter Notebooks: ```py import os @@ -38,7 +38,7 @@ load_dotenv() # Load environment variables from `.env` into the system's enviro TOKEN = os.environ["BAV_API_TOKEN"] # Assign our "BAV_API_TOKEN" environment variable to `TOKEN` ``` -Now you can use `TOKEN` in your API requests: +You can then use `TOKEN` in your API requests: ```py bavapi.brands(TOKEN, name="Swatch") diff --git a/docs/developer-tools/python/basic-usage.md b/docs/developer-tools/python/basic-usage.md index 8579651..8bc5d45 100644 --- a/docs/developer-tools/python/basic-usage.md +++ b/docs/developer-tools/python/basic-usage.md @@ -7,8 +7,8 @@ sidebar_label: Basic Usage import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -Once you have installed `bavapi` and acquired a token from the Fount, you can start using `bavapi` directly in Python -or in a Jupyter Notebook. +After you install `bavapi` and get a token from the Fount, you can use `bavapi` directly in Python or in a Jupyter +Notebook. ```py import bavapi @@ -16,14 +16,14 @@ import bavapi ## Making Requests -You can query the available [endpoints](endpoints/) with their corresponding methods. Replace `TOKEN` with +You can query the available [endpoints](endpoints/) with their related methods. Replace `TOKEN` with your [API key](authentication). ```py swatch = bavapi.brands("TOKEN", name="Swatch") # Replace `TOKEN` with your API key ``` -These endpoints methods will return a pandas DataFrame containing the data retrieved for your query: +These endpoint methods return a pandas DataFrame that contains the data for your query: | | id | name | ... | |----:|:-------|:-------|:----| @@ -42,31 +42,31 @@ all_adults = bavapi.audiences("TOKEN", name="All Adults") ``` :::info Want to use other endpoints? -The BAV API is very extensive, so not all endpoints are fully implemented yet. +The BAV API is large, so the SDK does not fully implement all endpoints yet. -To query unsupported endpoints see the [Other endpoints](advanced-usage#other-endpoints) section in Advanced Usage. +To query unsupported endpoints, see the [Other endpoints](advanced-usage#other-endpoints) section in Advanced Usage. ::: ## `bavapi` query parameters -In order to validate the request parameters before sending a bad request, `bavapi` will automatically check that the -parameters from your query and filters are of the type expected by the Fount API. If any parameter doesn't conform to -the API requirements, `bavapi` will raise a `ValidationError`. +`bavapi` validates the request parameters before it sends a request. It automatically checks that the parameters +from your query and filters are of the type that the Fount API expects. If a parameter does not agree with the API +requirements, `bavapi` will raise a `ValidationError`. :::note What it's doing -`bavapi` performs an initial request to make sure the query parameters are valid, and to retrieve information about the -number of pages it will need to fetch. +`bavapi` sends an initial request to make sure that the query parameters are valid. This request also gets the number +of pages that `bavapi` must fetch. -If the initial request fails, `bavapi` will not perform more requests. +If the initial request fails, `bavapi` will not send more requests. -Similarly, if the initial request returns the entirety of the query (e.g., there are only 10 results and `per_page` is -above 10, which it is by default), no further requests will be performed, and instead the data from the initial response -will be returned. +The initial request can return all of the query results. For example, there are only 10 results, and `per_page` is +more than 10 (the default value is more than 10). In this case, `bavapi` does not send more requests. It returns the data from the +initial response. ::: ### Filters -Each endpoint has a filter class associated with it, as each endpoint has its own filter requirements: +Each endpoint has its own filter requirements, so each endpoint has a related filters class: | Endpoint | Filters class | |-------------------------|----------------------------| @@ -85,26 +85,26 @@ Each endpoint has a filter class associated with it, as each endpoint has its ow These filters are available under the `bavapi.filters` namespace. :::caution Don't mix and match filters -Using a filters class not meant for a specific endpoint won't raise any errors from the outset, but it also won't -provide IDE type support or type validation to the parameters that are associated with each endpoint. +If you use a filters class that is not for the specific endpoint, you will not get errors at the start. But you will +also not get IDE type support or type validation for the parameters of that endpoint. -Similarly, using a dictionary (as seen in the example below) won't provide validation or type hints. Use the dictionary -method with caution. +Also, a dictionary (as in the example below) does not give validation or type hints. Be careful when you use the +dictionary method. ::: -Some of the more common filters for each endpoint have been added directly to the `bavapi` functions. More info in the -[endpoints](./endpoints/) section. +The `bavapi` functions include some of the more common filters for each endpoint directly. For more information, see +the [endpoints](./endpoints/) section. :::info Example -`bavapi.brands` has parameters such as `name`, `country_codes`, `year_numbers`, `brand_id` or `studies`, which you can -use directly from the function without creating a filters instance. +`bavapi.brands` has parameters such as `name`, `country_codes`, `year_numbers`, `brand_id` or `studies`. You can use +these parameters directly in the function. You do not need to create a filters instance. ::: -However, less commonly used filters, as well as [value filters](#value-filters) must be specified by using the `filters` -parameters in each function. +But you must specify less commonly used filters and [value filters](#value-filters) in the `filters` parameter of +each function. -Filters can be specified using a python dictionary (if you know the name of the filters you need), or directly creating -a filter instance. +You can specify filters with a python dictionary (if you know the names of the filters that you need). You can also +create a filters instance directly. @@ -128,8 +128,7 @@ result = bavapi.brands( :::caution -If both regular function parameters and filters are specified, the values in the filters parameter will take precedence -for the actual request: +If you specify both regular function parameters and filters, the request uses the values in the filters parameter: ```py result = bavapi.brands(name="Swatch", filters={"name": "Facebook"}) @@ -140,11 +139,11 @@ The request will use `name="Facebook"`, because values specified in the `filters ### Value filters -"Value" filters refer to filtering on the values of the data returned by the endpoint. For example, filtering by -category name or by sector. +"Value" filters filter the values of the data that the endpoint returns. For example, they can filter by category +name or by sector. -These value filters **must** be specified in the `filters` parameter. If they are added to the function call as regular -keyworrd arguments, a `ValidationError` will be raised. +You **must** specify these value filters in the `filters` parameter. If you add them to the function call as regular +keyword arguments, `bavapi` will raise a `ValidationError`. ```py bavapi.brands(name="Swatch", filters={"sector_name": "Watches"}) # ok @@ -152,8 +151,8 @@ bavapi.brands(name="Swatch", filters={"sector_name": "Watches"}) # ok bavapi.brands(name="Swatch", sector_name="Watches") # raises ValidationError ``` -When using additional value filters, which might not be available in the arguments to the function call, it is -recommended to use the `filters` parameter instead of mixing function parameters and Filters parameters: +Some value filters are not available as arguments to the function call. If you use these value filters, we recommend +that you use only the `filters` parameter. Do not mix function parameters and Filters parameters: ```py bavapi.brands(filters=bavapi.filters.BrandsFilters(name="Swatch", sector_name="Watches")) @@ -161,8 +160,8 @@ bavapi.brands(filters=bavapi.filters.BrandsFilters(name="Swatch", sector_name="W ### Fields -It is possible to [specify which fields](/customizing/fields.md) a response should contain. If so, the API will **only** -return those fields. +You can [specify which fields](/customizing/fields.md) a response contains. If you do this, the API will return +**only** those fields. ```py result = bavapi.brands(name="Swatch", fields=["id", "name"]) @@ -171,7 +170,7 @@ result.columns # will only have ["id", "name"] as columns ### Sort -It is possible to [sort the data](/customizing/filters.md#sorting-results) by a column from the response. +You can [sort the data](/customizing/filters.md#sorting-results) by a column from the response. ```py # sorted by name @@ -181,15 +180,14 @@ result = bavapi.brands(name="Swatch", sort="name") result = bavapi.brands(name="Swatch", sort="-name") ``` -Responses are sorted by item id, in ascending order, by default. +By default, responses are sorted by item id, in ascending order. ### Includes -Aside from the data directly available for each of the resources in the Fount, these resources can also be connected -across endpoints. +Each resource in the Fount has its own data. Resources can also connect to other resources across endpoints. -Each endpoint supports different [included fields](/customizing/includes.md). Please read the -[API documentation](/intro.md) for more info on the specific set of includes supported by each endpoint. +Each endpoint supports different [included fields](/customizing/includes.md). For more information about the includes +that each endpoint supports, read the [API documentation](/intro.md). ```py # will include info about the brand's company @@ -202,36 +200,36 @@ The `brandscape_data` function includes `study`, `brand`, `category` and `audien ### Pagination -All requests to the Fount are [paginated](/pagination.md), meaning that one must request and receive from the server -one page at a time. The SDK automatically combines all responses into one data table for convenience. +All requests to the Fount are [paginated](/pagination.md). This means that you request and receive one page at a +time from the server. For convenience, the SDK automatically combines all responses into one data table. -Pagination is controlled by three parameters: +Three parameters control pagination: - `page` - `per_page` - `max_pages` -If only `page` is set to an integer greater than `0`, that single page will be requested. +If you set only `page` to an integer greater than `0`, `bavapi` requests only that page. ```py bavapi.studies(page=1) # Will request a single page of data ``` -If either `per_page` or `max_pages` are set, `bavapi` will request the appropriate pages from the Fount API. +If you set `per_page` or `max_pages`, `bavapi` will request the applicable pages from the Fount API. -While the Fount API default is `25`, the default `per_page` set by `bavapi` is `100`. +The Fount API default for `per_page` is `25`, but the `bavapi` default is `100`. :::note -The maximum number of elements per page allowed by the Fount API is `1000`. +The Fount API allows a maximum of `1000` elements per page. ::: -`bavapi` will calculate the number of pages from the total items reported by the Fount. +`bavapi` calculates the number of pages from the total number of items that the Fount reports. -It is also possible to set the number of `max_pages`, which will limit the number of pages requested regardless of the -reported total. +You can also set `max_pages`. This limits the number of pages that `bavapi` requests, independent of the reported +total. -The `page` value will be used as the starting page for the request. Therefore, if `page=10` and, for example, -`max_pages=30`, `bavapi` will request pages `10` to `40`. +`bavapi` uses the `page` value as the start page for the request. For example, if `page=10` and `max_pages=30`, +`bavapi` will request pages `10` to `40`. ```py # Request pages with 50 items per page @@ -253,24 +251,23 @@ bavapi.studies("TOKEN", page=3, max_pages=30) ### Metric and metric group keys -`metric_keys` and `metric_group_keys` are special filters to specify the data *columns* that the response should -contain. +`metric_keys` and `metric_group_keys` are special filters. They specify which data *columns* the response contains. The API response will include all score types for that metric or metric group. :::note -Currently, only the `brandscape-data` endpoint supports the use of metric and metric group keys. All other endpoints -will ignore this parameter. More info in the +At this time, only the `brandscape-data` endpoint supports metric and metric group keys. All other endpoints +ignore this parameter. For more information, see the [`brandscape-data`](endpoints/brandscape-data.md#metric-and-metric-group-keys) endpoint section. ::: ## Using `Query` objects -While the available parameters in endpoint functions and methods are provided for convenience, it is possible to use -`bavapi.Query` objects directly inside function calls. +The parameters in the endpoint functions and methods are there for convenience. You can also use `bavapi.Query` +objects directly in function calls. -Similarly to filters objects, when using `Query` in one of the endpoint methods, the parameter values specified in the -`Query` object will take precedence over parameters specified at the function level. +This works the same as filters objects. If you use `Query` in an endpoint method, the parameter values in the `Query` +object take precedence over the parameters at the function level. ```py # will use `name="Facebook"` because `query` values take precedence. @@ -278,16 +275,16 @@ bavapi.brands(name="Swatch", query=bavapi.Query(filters={"name":"Facebook"})) ``` :::note -Read more about `Query` in the [Advanced usage](./advanced-usage#the-query-class) section. +For more information about `Query`, see the [Advanced usage](./advanced-usage#the-query-class) section. ::: ## Formatting output -It is possible that some of the data retrieved from the Fount includes multiple items. +Some of the data from the Fount can include multiple items. :::info Example -For example, requesting the `studies` include in `bavapi.brands` will return a column containing lists of dictionaries -with study info for all studies that a brand appears in. +For example, if you request the `studies` include in `bavapi.brands`, you get a column that contains lists of +dictionaries. These dictionaries contain study information for all studies that include the brand. | | id | name | studies | |----:|------:|:---------|:--------------------------------------| @@ -296,8 +293,8 @@ with study info for all studies that a brand appears in. ::: -`bavapi` provides a `stack_data` parameter to its functions and methods that will take those lists of dictionaries and -generate a new entry (row) in the resulting DataFrame for each element in the list. +The `bavapi` functions and methods have a `stack_data` parameter. This parameter takes those lists of dictionaries. +It then makes a new entry (row) in the resulting DataFrame for each element in the list. ```py bavapi.brands("Facebook", include="studies", stack_data=True) @@ -311,10 +308,9 @@ bavapi.brands("Facebook", include="studies", stack_data=True) ## Suppressing progress bars -`bavapi` displays progress bars to show download progress. Each tick in the progress bar refers to individual pages -being downloaded. +`bavapi` shows progress bars for the download progress. Each tick in the progress bar is one downloaded page. -It's possible to supress progress bar outputs via the `verbose` parameter in function calls and `Client` init methods: +To hide the progress bars, use the `verbose` parameter in function calls and `Client` init methods: @@ -336,12 +332,12 @@ async with bavapi.Client(TOKEN, verbose=False) as bav: ## Timeout -By default, API requests will timeout after 30 seconds in order to avoid hangups. +By default, API requests time out after 30 seconds. This prevents requests that do not stop. -This may happen more commonly when performing requests with more than 50-100 pages. If you get a `TimeoutError`, you -can change this parameter to allow for longer timeouts. +Timeouts occur more frequently in requests with more than 50-100 pages. If you get a `TimeoutError`, you can change +this parameter to let requests run longer before they time out. -It is possible to set the time before timeout when performing requests with `bavapi`: +You can set the time before the timeout when you send requests with `bavapi`: @@ -365,14 +361,14 @@ async with bavapi.Client(TOKEN, timeout=60) as bav: ### Warn or raise when a page fails to download -You can control the error handling behavior of `bavapi` by changing the `on_errors` parameter in top-level functions -and the `Client` interface. +To control how `bavapi` handles errors, change the `on_errors` parameter in top-level functions and the `Client` +interface. Options and examples: -- `"warn"` (default): Will return all successfully downloaded data, and warn at the end about any pages that failed -- downloading so they can be manually retried. -- `"raise"`: Will raise any exception that occurs immediately. This was the default behavior until `v0.13`. +- `"warn"` (default): Returns all data that downloaded successfully. At the end, it shows a warning about all pages + that did not download, so that you can try them again manually. +- `"raise"`: Raises each exception immediately when it occurs. This was the default behavior until `v0.13`. @@ -394,26 +390,26 @@ Exception: ... # Raised :::caution "Some requests may still raise" -During the initial handshake between `bavapi` and the Fount API, only SSL errors are retried. Therefore, some queries -may still raise exceptions even if `on_errors` is set to `"warn"`: +During the initial handshake between `bavapi` and the Fount API, `bavapi` retries only SSL errors. Thus, some queries +can still raise exceptions when `on_errors` is set to `"warn"`: -- Invalid parameters will raise a `ValidationError` if they are not of the correct Python type -- Server errors will raise an `APIError` with additional details about the issue -- Queries with no results found will raise a `DataNotFoundError` -- Requests which exceed the user's rate limit will raise a `RateLimitExceededError` +- If parameters are not of the correct Python type, they raise a `ValidationError` +- Server errors raise an `APIError` with more details about the problem +- Queries that find no results raise a `DataNotFoundError` +- Requests that exceed the user's rate limit raise a `RateLimitExceededError` ::: ### Retry failed requests -`bavapi` will automatically retry requests that fail because of an exception. The number of retry attempts can be -controlled via the `retries` parameter in top-level functions and the `Client` interface: +`bavapi` automatically retries requests that fail because of an exception. To control the number of retry attempts, +use the `retries` parameter in top-level functions and the `Client` interface: ```py bavapi.brands("TOKEN", retries=5) # Will retry pages 5 times after original failure ``` :::note -There are some additional, advanced options for controlling the behavior of `bavapi` requests. More info in the -[Control `bavapi` batching behavior](advanced-usage#control-bavapi-batching-behavior) section from the Advanced Usage +There are also some advanced options to control the behavior of `bavapi` requests. For more information, see the +[Control `bavapi` batching behavior](advanced-usage#control-bavapi-batching-behavior) section of the Advanced Usage documentation. ::: diff --git a/docs/developer-tools/python/endpoints/audience-groups.md b/docs/developer-tools/python/endpoints/audience-groups.md index 937ab0b..cc8f95d 100644 --- a/docs/developer-tools/python/endpoints/audience-groups.md +++ b/docs/developer-tools/python/endpoints/audience-groups.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`audience-groups` endpoint](/core-resources/audience-groups.md). ::: -The `audience-groups` endpoint has full support, including query validation. +The `audience-groups` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | ------------------- | ----------------- | ------------------------ | ----------------------- | @@ -44,4 +44,4 @@ These filters are available directly within the function/method: - Positional filters: `name` - Keyword filters: `audience_group_id` -For other filters, passing an `AudienceGroupsFilters` instance to the `filters` parameter is required. +For other filters, you must give an `AudienceGroupsFilters` instance to the `filters` parameter. diff --git a/docs/developer-tools/python/endpoints/audiences.md b/docs/developer-tools/python/endpoints/audiences.md index 65c04c2..8759f0a 100644 --- a/docs/developer-tools/python/endpoints/audiences.md +++ b/docs/developer-tools/python/endpoints/audiences.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`audiences` endpoint](/audiences/audiences.md). ::: -The `audiences` endpoint has full support, including query validation. +The `audiences` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | ------------- | ----------- | ------------------ | ------------------ | @@ -44,4 +44,4 @@ These filters are available directly within the function/method: - Positional filters: `name`, `active`, `public` - Keyword filters: `audience_id`, `private`, `groups` -For other filters, passing an `AudiencesFilters` instance to the `filters` parameter is required. +For other filters, you must give an `AudiencesFilters` instance to the `filters` parameter. diff --git a/docs/developer-tools/python/endpoints/brand-metric-groups.md b/docs/developer-tools/python/endpoints/brand-metric-groups.md index cc2d9fd..05d0b3d 100644 --- a/docs/developer-tools/python/endpoints/brand-metric-groups.md +++ b/docs/developer-tools/python/endpoints/brand-metric-groups.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`brand-metric-groups` endpoint](/metrics/metric-groups.md). ::: -The `brand-metric-groups` endpoint has full support, including query validation. +The `brand-metric-groups` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | ----------------------- | --------------------- | ---------------------------- | -------------------------- | @@ -44,4 +44,4 @@ These filters are available directly within the function/method: - Positional filters: `name`, `active` - Keyword filters: `group_id` -For other filters, passing an `BrandMetricGroupsFilters` instance to the `filters` parameter is required. +For other filters, you must give a `BrandMetricGroupsFilters` instance to the `filters` parameter. diff --git a/docs/developer-tools/python/endpoints/brand-metrics.md b/docs/developer-tools/python/endpoints/brand-metrics.md index 6512153..6fd66eb 100644 --- a/docs/developer-tools/python/endpoints/brand-metrics.md +++ b/docs/developer-tools/python/endpoints/brand-metrics.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`brand-metrics` endpoint](/metrics/metrics.md). ::: -The `brand-metrics` endpoint has full support, including query validation. +The `brand-metrics` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | ----------------- | --------------- | ---------------------- | --------------------- | @@ -44,4 +44,4 @@ These filters are available directly within the function/method: - Positional filters: `name`, `active`, `public` - Keyword filters: `metric_id`, `private`, `groups` -For other filters, passing an `BrandMetricsFilters` instance to the `filters` parameter is required. +For other filters, you must give a `BrandMetricsFilters` instance to the `filters` parameter. diff --git a/docs/developer-tools/python/endpoints/brands.md b/docs/developer-tools/python/endpoints/brands.md index 061fcde..0b861d1 100644 --- a/docs/developer-tools/python/endpoints/brands.md +++ b/docs/developer-tools/python/endpoints/brands.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`brands` endpoint](/core-resources/brands.md). ::: -The `brands` endpoint has full support, including query validation. +The `brands` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | ---------- | -------- | --------------- | --------------- | @@ -44,4 +44,4 @@ These filters are available directly within the function/method: - Positional filters: `name`, `country_codes`, `year_numbers` - Keyword filters: `brand_id`, `studies` -For other filters, passing a `BrandsFilters` instance to the `filters` parameter is required. +For other filters, you must give a `BrandsFilters` instance to the `filters` parameter. diff --git a/docs/developer-tools/python/endpoints/brandscape-data.md b/docs/developer-tools/python/endpoints/brandscape-data.md index 36a06bc..3152cba 100644 --- a/docs/developer-tools/python/endpoints/brandscape-data.md +++ b/docs/developer-tools/python/endpoints/brandscape-data.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`brandscape-data` endpoint](/brand-data/brandscape-data.md). ::: -The `brandscape-data` endpoint has full support, including query validation. +The `brandscape-data` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | ------------------- | ----------------- | ------------------------ | ------------------- | @@ -38,7 +38,7 @@ async with bavapi.Client("TOKEN") as bav: :::caution -`brandscape-data` has filters which have a slightly **different** name than for other endpoints: +Some `brandscape-data` filters have a slightly **different** name than the filters for other endpoints: - `year_number` instead of `year_numbers`. - `country_code` instead of `country_codes`. @@ -52,16 +52,15 @@ These filters are available directly within the function/method: - Positional filters: `country_code`, `year_number`, `audiences`, `brand_name` (search by name) - Keyword filters: `studies` -For other filters, passing a `BrandscapeFilters` instance to the `filters` parameter is required. +For other filters, you must give a `BrandscapeFilters` instance to the `filters` parameter. ## Required filters -`brandscape-data` can retrieve brand datasets from an arbitrary combination of studies, audiences and years, so it is -possible that the request becomes too large for the server to deliver effectively for all users. Please see the see the -main API documentation for the [brandscape data endpoint](/brand-data/brandscape-data.md) for more details on -required filters to apply. +`brandscape-data` can get brand datasets from any combination of studies, audiences and years. Thus, a request can +become too large for the server to deliver effectively for all users. For more details about the required filters, see +the main API documentation for the [brandscape data endpoint](/brand-data/brandscape-data.md). -If a query does not have any of these combinations of filters, it will raise a `ValidationError`: +If a query does not have one of these combinations of filters, it will raise a `ValidationError`: ```py bavapi.brandscape_data("TOKEN") # Error, no filters specified @@ -77,15 +76,14 @@ bavapi.brandscape_data( ## Default includes -In order to provide critical information about the data retrieved from `brandscape-data` some `include` values are -requested by +To give critical information about the data from `brandscape-data`, `bavapi` requests some `include` values by default: `study`, `brand`, `category` and `audience`. -If you add any of these values in the `include` field by themselves, the default won't be used, and `bavapi` will make a -request with the specified `include` instead. +If you add one of these values in the `include` field by itself, `bavapi` does not use the default. It makes a request +with the specified `include` instead. -If, on the other hand, you request an `include` that is *not* part of the default values, `bavapi` will append that new -value to the default `include` values. +If you request an `include` that is *not* part of the default values, `bavapi` will add that new value to the default +`include` values. ```py # All default includes will be requested @@ -101,30 +99,26 @@ bavapi.brandscape_data("TOKEN", brand_name="Facebook", include="company") ## Clashing column names -Some includes can have clashing column names with the original data. This happens, for example, with the `"brand"` -include, which when expanded will have column names such as `"brand_name"`, which is already present in -the `brandscape-data` table. +Some includes can have column names that clash with the column names of the original data. For example, the expanded +`"brand"` include has column names such as `"brand_name"`. The `brandscape-data` table already has this column. -To circumvent this issue, the response parsing function will append the `"global_"` prefix to includes with potentially -clashing names. +To prevent this problem, the response parsing function adds the `"global_"` prefix to includes that can have clashing +names. -As a result, you will see a set of columns, extracted from the `"brand"` include, which will have a `"global_"` prefix -in their names. +Thus, a set of columns from the `"brand"` include will have a `"global_"` prefix in their names. :::caution -This may change in future versions of `bavapi` as the parsing logic is upgraded. +This can change in future versions of `bavapi` when the parsing logic changes. ::: ## Metric keys -`brandscape-data` provides a special filter to specify the data *columns* that the response should -contain: `metric_keys`. +`brandscape-data` has a special filter to specify which data *columns* the response contains: `metric_keys`. -You can specify the metrics that your response should contain, and the API will include all score types for that metric. +You can specify the metrics for your response. The API will include all score types for each of these metrics. :::info Example -Setting `metric_keys` to `["differentiation", "relevance"]` will instruct the request to only return the following -columns: +If you set `metric_keys` to `["differentiation", "relevance"]`, the request will return only the following columns: - `differentiation_c` - `differentiation_rank` diff --git a/docs/developer-tools/python/endpoints/categories.md b/docs/developer-tools/python/endpoints/categories.md index 4ee32ba..8f76b17 100644 --- a/docs/developer-tools/python/endpoints/categories.md +++ b/docs/developer-tools/python/endpoints/categories.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`categories` endpoint](/core-resources/categories.md). ::: -The `categories` endpoint has full support, including query validation. +The `categories` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | -------------- | ------------ | ------------------- | ------------------- | @@ -44,13 +44,13 @@ These filters are available directly within the function/method: - Positional filters: `name`, `sector` - Keyword filters: `category_id` -For other filters, passing an `CategoriesFilters` instance to the `filters` parameter is required. +For other filters, you must give a `CategoriesFilters` instance to the `filters` parameter. ## Default includes -In order to provide critical information about the data retrieved from `categories`, and to move its structure in line -with data downloads from the Fount or BAV's Cultural Rank Tool (CRT), some `include` values are requested by default: -`sector`. +`bavapi` requests some `include` values by default: `sector`. These values give critical information about the data +from `categories`. They also make its structure align with data downloads from the Fount or BAV's Cultural Rank Tool +(CRT). ```py # All default (sector) includes will be requested diff --git a/docs/developer-tools/python/endpoints/cities.md b/docs/developer-tools/python/endpoints/cities.md index 6624281..dbd9888 100644 --- a/docs/developer-tools/python/endpoints/cities.md +++ b/docs/developer-tools/python/endpoints/cities.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`cities` endpoint](/core-resources/cities.md). ::: -The `cities` endpoint has full support, including query validation. +The `cities` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | ---------- | -------- | --------------- | --------------- | @@ -44,4 +44,4 @@ These filters are available directly within the function/method: - Positional filters: `capitals`, `countries`, `in_best_countries` - Keyword filters: `city_id` -For other filters, passing an `CitiesFilters` instance to the `filters` parameter is required. +For other filters, you must give a `CitiesFilters` instance to the `filters` parameter. diff --git a/docs/developer-tools/python/endpoints/collections.md b/docs/developer-tools/python/endpoints/collections.md index de08880..0b0bab7 100644 --- a/docs/developer-tools/python/endpoints/collections.md +++ b/docs/developer-tools/python/endpoints/collections.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`collections` endpoint](/brands/collections.md). ::: -The `collections` endpoint has full support, including query validation. +The `collections` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | --------------- | ------------- | -------------------- | -------------------- | @@ -44,4 +44,4 @@ These filters are available directly within the function/method: - Positional filters: `name`, `public` - Keyword filters: `collection_id`, `shared_with_me`, `mine` -For other filters, passing an `CollectionsFilters` instance to the `filters` parameter is required. +For other filters, you must give a `CollectionsFilters` instance to the `filters` parameter. diff --git a/docs/developer-tools/python/endpoints/companies.md b/docs/developer-tools/python/endpoints/companies.md index 892ea67..ea070d8 100644 --- a/docs/developer-tools/python/endpoints/companies.md +++ b/docs/developer-tools/python/endpoints/companies.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`companies` endpoint](/core-resources/companies.md). ::: -The `companies` endpoint has full support, including query validation. +The `companies` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | ------------- | ----------- | ------------------ | ------------------ | @@ -44,4 +44,4 @@ These filters are available directly within the function/method: - Positional filters: `public`, `private`, `brands` - Keyword filters: `company_id` -For other filters, passing an `CompaniesFilters` instance to the `filters` parameter is required. +For other filters, you must give a `CompaniesFilters` instance to the `filters` parameter. diff --git a/docs/developer-tools/python/endpoints/countries.md b/docs/developer-tools/python/endpoints/countries.md index 2c25c91..f671503 100644 --- a/docs/developer-tools/python/endpoints/countries.md +++ b/docs/developer-tools/python/endpoints/countries.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`countries` endpoint](/metadata/countries.md). ::: -The `countries` endpoint has full support, including query validation. +The `countries` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | ------------- | ----------- | ------------------ | ------------------ | @@ -44,4 +44,4 @@ These filters are available directly within the function/method: - Positional filters: `active`, `regions`, `with_studies` - Keyword filters: `country_id`, `with_recent_studies` -For other filters, passing an `CountriesFilters` instance to the `filters` parameter is required. +For other filters, you must give a `CountriesFilters` instance to the `filters` parameter. diff --git a/docs/developer-tools/python/endpoints/index.md b/docs/developer-tools/python/endpoints/index.md index dab905d..a96491f 100644 --- a/docs/developer-tools/python/endpoints/index.md +++ b/docs/developer-tools/python/endpoints/index.md @@ -7,7 +7,7 @@ sidebar_label: Overview import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -As of `v1.1`, these are the endpoints that have been fully implemented in `bavapi`: +As of `v1.1`, `bavapi` has full implementations of these endpoints: - [`audiences`](audiences.md) - [`audience-groups`](audience-groups.md) @@ -25,34 +25,34 @@ As of `v1.1`, these are the endpoints that have been fully implemented in `bavap - [`studies`](studies.md) - [`years`](years.md) -"Implemented" meaning that the endpoint has a corresponding function, `Client` method, and filters class associated -with them. More info in each endpoint's respective section linked above. +"Implemented" means that the endpoint has a related function, `Client` method, and filters class. For more +information, see the section for each endpoint in the list above. -If an existing endpoint does not appear in the list above, you can still perform queries to them using the `raw_query` -methods (see [below](#other-endpoints)), but `bavapi` won't validate filter parameters. +If an endpoint is not in the list above, you can still send queries to it with the `raw_query` methods (see +[below](#other-endpoints)). But `bavapi` will not validate the filter parameters. -Examples for each endpoint are available in each of their individual sections, both for the top-level, synchronous -functions, and the asynchronous methods in `bavapi.Client`. +The section for each endpoint has examples for the top-level, synchronous functions and for the asynchronous methods in +`bavapi.Client`. -For a summary of all existing Fount endpoints, as well as their parameters and supported filters, please see the +For a summary of all Fount endpoints and their parameters and supported filters, see the [Resources](/intro.md) section of the Fount API documentation. ## Other endpoints -While there are some commonly used endpoints with more extensive validation support, there are a *lot* of additional -endpoints available for querying. +Some commonly used endpoints have more extensive validation support. But there are a *lot* of other endpoints that +you can query. -With the `raw_query` functions and methods, you can perform requests to any endpoint in the Fount, even if it's not -supported with dedicated code. +With the `raw_query` functions and methods, you can send requests to any endpoint in the Fount. This is also true for +endpoints that do not have dedicated code. | Endpoint | Function | `Client` method | Filters class | | -------- | ----------- | ------------------ | -------------- | | `{any}` | `raw_query` | `Client.raw_query` | `FountFilters` | -Queries from `raw_query` functions and methods return a list of JSON dictionaries, instead of a `pandas` DataFrame. +Queries from `raw_query` functions and methods return a list of JSON dictionaries, not a `pandas` DataFrame. :::note -You need to use a `Query` instance to perform queries with `raw_query` methods. +You must use a `Query` instance to send queries with `raw_query` methods. [More info](../advanced-usage.md#other-endpoints) ::: @@ -80,8 +80,8 @@ async with bavapi.Client("TOKEN") as bav: -Since the result of these queries will be a list of JSON dictionaries, you can use the `parse_response` function in the -`bavapi.parsing.responses` module to parse the JSON response into a DataFrame: +The result of these queries is a list of JSON dictionaries. To parse the JSON response into a DataFrame, use the +`parse_response` function in the `bavapi.parsing.responses` module: ```py import bavapi diff --git a/docs/developer-tools/python/endpoints/regions.md b/docs/developer-tools/python/endpoints/regions.md index 421d2c3..95e72c1 100644 --- a/docs/developer-tools/python/endpoints/regions.md +++ b/docs/developer-tools/python/endpoints/regions.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`regions` endpoint](/core-resources/regions.md). ::: -The `regions` endpoint has full support, including query validation. +The `regions` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | ----------- | --------- | ---------------- | ---------------- | @@ -44,4 +44,4 @@ These filters are available directly within the function/method: - Positional filters: `name` - Keyword filters: `region_id` -For other filters, passing an `RegionsFilters` instance to the `filters` parameter is required. +For other filters, you must give a `RegionsFilters` instance to the `filters` parameter. diff --git a/docs/developer-tools/python/endpoints/sectors.md b/docs/developer-tools/python/endpoints/sectors.md index c05b086..9cbfc7d 100644 --- a/docs/developer-tools/python/endpoints/sectors.md +++ b/docs/developer-tools/python/endpoints/sectors.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`sectors` endpoint](/core-resources/sectors.md). ::: -The `sectors` endpoint has full support, including query validation. +The `sectors` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | ----------- | --------- | ---------------- | ---------------- | @@ -44,4 +44,4 @@ These filters are available directly within the function/method: - Positional filters: `name`, `in_most_influential` - Keyword filters: `sector_id` -For other filters, passing an `SectorsFilters` instance to the `filters` parameter is required. +For other filters, you must give a `SectorsFilters` instance to the `filters` parameter. diff --git a/docs/developer-tools/python/endpoints/studies.md b/docs/developer-tools/python/endpoints/studies.md index bfea2ee..c7762e3 100644 --- a/docs/developer-tools/python/endpoints/studies.md +++ b/docs/developer-tools/python/endpoints/studies.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`studies` endpoint](/studies/studies.md). ::: -The `studies` endpoint has full support, including query validation. +The `studies` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | ----------- | --------- | ---------------- | ---------------- | @@ -44,4 +44,4 @@ These filters are available directly within the function/method: - Positional filters: `country_codes`, `year_numbers`, `full_year`, `released`, `bav_study` - Keyword filters: `study_id` -For other filters, passing a `StudiesFilters` instance to the `filters` parameter is required. +For other filters, you must give a `StudiesFilters` instance to the `filters` parameter. diff --git a/docs/developer-tools/python/endpoints/years.md b/docs/developer-tools/python/endpoints/years.md index f0fc49f..89869fd 100644 --- a/docs/developer-tools/python/endpoints/years.md +++ b/docs/developer-tools/python/endpoints/years.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Read more in the API documentation for the [`years` endpoint](/metadata/years.md). ::: -The `years` endpoint has full support, including query validation. +The `years` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | --------- | -------- | --------------- | -------------- | @@ -44,4 +44,4 @@ These filters are available directly within the function/method: - Positional filters: `year` - Keyword filters: `year_id` -For other filters, passing an `YearsFilters` instance to the `filters` parameter is required. +For other filters, you must give a `YearsFilters` instance to the `filters` parameter. diff --git a/docs/developer-tools/python/index.md b/docs/developer-tools/python/index.md index d47b335..2a672d3 100644 --- a/docs/developer-tools/python/index.md +++ b/docs/developer-tools/python/index.md @@ -11,24 +11,25 @@ sidebar_label: Overview [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/wpp-bavapi) ](https://pypi.org/project/wpp-bavapi/) -The Python SDK for the BAV API makes it easy to consume BAV data within your Python scripts. It is published +The Python SDK for the BAV API makes it easy to use BAV data in your Python scripts. It is published as `wpp-bavapi` in [PyPI](https://pypi.org/project/wpp-bavapi/) and hosted on [GitHub](https://github.com/wppbav/bavapi-sdk-python/). -Queries are validated automatically thanks to `pydantic` and retrieved asynchronously via the `httpx` package. +The SDK uses `pydantic` to validate queries automatically. It uses the `httpx` package to get the data +asynchronously. -To start using `bavapi`, go to the [Installation](installation.md) section. +To start with `bavapi`, go to the [Installation](installation.md) section. -After going through the Installation, please see [Basic Usage](basic-usage.md). For more advanced topics, -see the [Advanced Usage](advanced-usage.md) section. +After the installation, see [Basic Usage](basic-usage.md). For more advanced topics, see the +[Advanced Usage](advanced-usage.md) section. -Each Fount API endpoint may behave slightly differently. You can find detailed explanations in +The behavior of each Fount API endpoint can be slightly different. You can find detailed explanations in the [Endpoints](python/endpoints/) section. ## Example usage :::info "Protected access" -:lock: To use `bavapi`, you will need a Fount API token. Read more in the [Authentication](../authentication) section. +:lock: To use `bavapi`, you need a Fount API token. Read more in the [Authentication](../authentication) section. ::: ```py @@ -60,17 +61,17 @@ the [Endpoints](python/endpoints/) section. - [`sectors`](endpoints/sectors.md) - [`studies`](endpoints/studies.md) - [`years`](endpoints/years.md) - - Other endpoints are available via the `raw_query` functions and methods. -- Validates query parameters are of the correct types and provides type hints for better IDE support. -- Retrieve multiple pages of data simultaneously, as well as monitors and prevents exceeding API rate limit. -- Both synchronous and asynchronous APIs for accessing BAV data. + - Other endpoints are available through the `raw_query` functions and methods. +- Validates that query parameters are of the correct types, and gives type hints for better IDE support. +- Gets multiple pages of data at the same time. Monitors the API rate limit and prevents requests that exceed it. +- Both synchronous and asynchronous APIs to access BAV data. ## Issues -For bug reports and feature requests, please open an issue +For bug reports and feature requests, open an issue on [GitHub](https://github.com/wppbav/bavapi-sdk-python/issues/). ## Contributing -We welcome contributions to the Python SDK which is hosted as a public repository on GitHub. Please see the -[Contributing](https://github.com/wppbav/bavapi-sdk-python/blob/main/CONTRIBUTING.md) document for more information. +We welcome contributions to the Python SDK. It is a public repository on GitHub. For more information, see the +[Contributing](https://github.com/wppbav/bavapi-sdk-python/blob/main/CONTRIBUTING.md) document. diff --git a/docs/developer-tools/python/installation.md b/docs/developer-tools/python/installation.md index 509e48b..26198ef 100644 --- a/docs/developer-tools/python/installation.md +++ b/docs/developer-tools/python/installation.md @@ -5,28 +5,28 @@ import TabItem from '@theme/TabItem'; ## Prerequisites -The SDK requires python 3.8 or higher to run. +The SDK requires python 3.8 or higher. -If you don't have python installed, you can download it from the official Python [website](https://www.python.org/downloads/) or [Anaconda](https://www.anaconda.com/). +If you do not have python, you can download it from the official Python [website](https://www.python.org/downloads/) or [Anaconda](https://www.anaconda.com/). -You will also need a BAV API token to peform requests to the Fount. For instructions on how to get your own API token, see the [Authentication](authentication.md) section. +You also need a BAV API token to send requests to the Fount. For instructions on how to get your own API token, see the [Authentication](authentication.md) section. ## Dependencies The SDK depends on the following excellent libraries: - `httpx` for communication with the Fount API. -- `pandas` for processing retrieved data into tables. +- `pandas` to process the data into tables. - `pydantic` to validate query and filter parameters. - `nest-asyncio` to support Jupyter notebooks. - `tqdm` to show helpful progress bars. - `typing-extensions` for type checking compatibility in older Python versions. -These libraries will be installed automatically when you install `bavapi`. +When you install `bavapi`, the installer also installs these libraries automatically. ## Installing the SDK in your project -Once you have your virtual environment activated, you can install `bavapi` with the following command: +After you activate your virtual environment, install `bavapi` with the following command: ```prompt pip install wpp-bavapi @@ -34,9 +34,9 @@ pip install wpp-bavapi :::tip Installing with conda -`bavapi` is not currently available from `conda` directly, though it should be possible to install and use it within a `conda` environment. +`bavapi` is not currently available directly from `conda`. But you can probably install and use it in a `conda` environment. -Use the following commands to maximize compatibility between `conda` and `pip`: +To get the best compatibility between `conda` and `pip`, use the following commands: ```prompt conda install httpx, pandas, pydantic, nest-asyncio, tqdm, typing_extensions @@ -48,13 +48,13 @@ pip install wpp-bavapi --no-deps ### Installing from source -To install from source, clone the GitHub repository into your local machine: +To install from source, clone the GitHub repository to your local machine: ```prompt git clone https://github.com/wppbav/bavapi-sdk-python.git ``` -Go into the cloned directory and install `bavapi`: +Go to the cloned directory. Then install `bavapi`: ```prompt cd bavapi-sdk-python @@ -63,6 +63,6 @@ pip install . ## Installing `bavapi` *Reference* classes -`bavapi` can generate some convenience reference classes which map Fount resource IDs with a more readable name, both for ease of use and for autocompletion in IDEs. These classes are automatically generated by a console command that becomes available once `bavapi` is installed. +`bavapi` can generate some convenience reference classes. These classes map Fount resource IDs to more readable names. They make the IDs easier to use and give autocompletion in IDEs. A console command generates these classes automatically. This command becomes available after you install `bavapi`. -Please see the [Reference Classes](reference-classes.md) section for more information. +For more information, see the [Reference Classes](reference-classes.md) section. diff --git a/docs/developer-tools/python/reference-classes.md b/docs/developer-tools/python/reference-classes.md index 69f8b75..41ad489 100644 --- a/docs/developer-tools/python/reference-classes.md +++ b/docs/developer-tools/python/reference-classes.md @@ -7,23 +7,22 @@ sidebar_label: Reference Classes import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -The SDK can generate some convenience reference classes which map Fount resource IDs with a more readable name, both -for ease of use and for autocompletion in IDEs. +The SDK can generate some convenience reference classes. These classes map Fount resource IDs to more readable names. +They make the IDs easier to use and give autocompletion in IDEs. -These classes are automatically generated by a console command that becomes available once `bavapi` is installed. +A console command generates these classes automatically. This command becomes available after you install `bavapi`. :::note Protected Access -A Fount API token is required to generate reference files. See -the [Authentication](developer-tools/python/authentication.md) section for more information and -instructions for using `.env` files within your Python project. +You need a Fount API token to generate reference files. For more information, and for instructions on how to use +`.env` files in your Python project, see the [Authentication](developer-tools/python/authentication.md) section. ::: -As of `v1.1` the following reference classes will be generated in a folder named `bavapi_refs`: +As of `v1.1`, the command generates the following reference classes in a folder named `bavapi_refs`: - `Audiences`: encodes audience IDs - `Countries`: encodes country IDs -A sample reference class would look like this: +This is an example of a reference class: ```py class Audiences(Enum): @@ -31,7 +30,7 @@ class Audiences(Enum): ... ``` -And could be used to have better visibility when filtering API responses: +You can use it to make your filters for API responses easier to read: @@ -51,14 +50,14 @@ bavapi.brandscape_data(country_code="US", year=2022, audiences=27) :::caution Ignore reference classes on public repositories -Please take care not to commit reference classes to public repositories. Add `bavapi_refs/` to your `.gitignore` file. +Do not commit reference classes to public repositories. Add `bavapi_refs/` to your `.gitignore` file. ::: -To generate these reference classes, there are two options for authenticating your requests: +When you generate these reference classes, you have two options to authenticate your requests: -- Specify the Fount API token via the `-t`/`--token` argument -- Use a `.env` file to store your Fount API token and install `python-dotenv` to read the file into your environment. - See the [Authentication](authentication.md#recommended-way-to-manage-api-keys) section for more info. +- Specify the Fount API token with the `-t`/`--token` argument. +- Store your Fount API token in a `.env` file, and install `python-dotenv` to read the file into your environment. + For more information, see the [Authentication](authentication.md#recommended-way-to-manage-api-keys) section. Run the following command: @@ -79,15 +78,15 @@ bavapi-gen-refs -t "TOKEN" --all -Alternatively, you can specify the name of the reference class to generate: +You can also specify the name of the reference class to generate: ```prompt bavapi-gen-refs --name audiences ``` -To update existing reference classes with the latest data, re-run `bavapi-gen-refs --all` on your terminal. +To update your reference classes with the latest data, run `bavapi-gen-refs --all` again in your terminal. :::caution Keep the reference classes up to date -The audiences and markets change over time. It is recommended to update your reference classes regularly. Typically -audiences and markets are never deleted, however we can't guarantee that it will never happen. +The audiences and markets change over time. We recommend that you update your reference classes regularly. Usually, +audiences and markets are not deleted. But we cannot guarantee that this will never occur. ::: diff --git a/docs/developer-tools/python/tools.md b/docs/developer-tools/python/tools.md index 3c5a3ed..24653e2 100644 --- a/docs/developer-tools/python/tools.md +++ b/docs/developer-tools/python/tools.md @@ -1,18 +1,18 @@ # Tools/TurboPitch :::info -Read more in the API documentation for the [tools endpoint](/brand-data/index.md). +Read more in the API documentation for the [tools endpoint](/brand-data/tools.md). ::: -The `tools` namespace in `bavapi` and the API enables access to ready-made analyses and frameworks to gain direct insights from BAV data. +The `tools` namespace in `bavapi` and the API gives access to ready-made analyses and frameworks. These give direct insights from BAV data. -Every tool operates by requesting the analysis to be performed on specific brands, categories, markets or audiences, specified by their ID in the Fount. The analysis is performed on the server, and the results are returned once retrieved. +Each tool requests an analysis of specific brands, categories, markets or audiences. You identify these items by their ID in the Fount. The server does the analysis, and returns the results when they are available. -Because the breadth of filters and parameters is much simpler than the query API endpoints, `pydantic` models are not needed to make requests. Function parameters are still type validated. +The filters and parameters of the tools are much simpler than the filters and parameters of the query API endpoints. Thus, you do not need `pydantic` models to make requests. The SDK still validates the types of the function parameters. ## Using `bavapi.tools` -The `tools` interface must be used through the `async` interface provided by the `bavapi.tools.ToolsClient` class: +You must use the `tools` interface through the `async` interface of the `bavapi.tools.ToolsClient` class: ```py from bavapi.tools import ToolsClient @@ -21,7 +21,7 @@ async with ToolsClient("TOKEN") as client: # Replace `"TOKEN"` with your own AP result = await client.brand_worth_map(brands=1, studies=1) ``` -You can also manually close the connection instead of using an `async with` block: +You can also close the connection manually instead of with an `async with` block: ```py from bavapi.tools import ToolsClient @@ -33,10 +33,10 @@ finally: await client.aclose() # Close the connection with the API server ``` -You will need to instantiate a new `ToolsClient` object once you use it inside the `async with` block or call `aclose`. +After you use a `ToolsClient` object inside the `async with` block or call `aclose`, you must instantiate a new `ToolsClient` object. :::caution Different return types by endpoint -Each tool will return results with different signatures. Some will return simply `pandas.DataFrame` instances, and others will return a tuple of additional metadata as a JSON dictionary and parsed data as a `pandas.DataFrame`. Please check the return type for each endpoint method in the docstrings or type hints. +Each tool returns results with a different signature. Some tools return only `pandas.DataFrame` instances. Other tools return a tuple: additional metadata as a JSON dictionary, and parsed data as a `pandas.DataFrame`. Check the return type for each endpoint method in the docstrings or type hints. ```py await ToolsClient("TOKEN").brand_worth_map(...) # returns (JSONDict, pd.DataFrame) @@ -47,20 +47,20 @@ await ToolsClient("TOKEN").brand_personality_match(...) # returns pd.DataFrame ## Client settings -Unlike the query API endpoints, these tools do not return paginated results, so many of the parameters to control pagination behavior in the query endpoints are not used. You can still specify the following when initializing `ToolsClient`: +These tools do not return paginated results, which is different from the query API endpoints. Thus, the tools do not use many of the pagination parameters of the query endpoints. When you initialize `ToolsClient`, you can still specify the following: - `auth_token` - `base_url` - `user_agent` -- `headers`: if used, don't pass `auth_token` and `user_agent` -- `client`: if used, don't pass `auth_token`, `headers` and `user_agent` +- `headers`: if you use this parameter, do not pass `auth_token` and `user_agent` +- `client`: if you use this parameter, do not pass `auth_token`, `headers` and `user_agent` - `retries` -Please refer to the [basic usage](basic-usage.md) section for more information on how to use these configuration parameters. +For more information about how to use these configuration parameters, see the [basic usage](basic-usage.md) section. ## Available endpoints -The available tools endpoints are the following: +The available tools endpoints are: - `archetypes` - `brand_personality_match` @@ -71,7 +71,7 @@ The available tools endpoints are the following: - `love_plus` - `partnership_exchange_map` -Endpoints not currently implemented are: +These endpoints are not implemented at this time: - `category_worth_map` - `swot` From 6473d726d2cc77d79ad99798a0a01435d3fdb7da Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sun, 25 Oct 2026 10:40:57 +0100 Subject: [PATCH 20/23] Fix Python SDK docs to match the bavapi source Co-Authored-By: Claude Opus 5.5 --- docs/developer-tools/python/advanced-usage.md | 21 ++++++---- docs/developer-tools/python/basic-usage.md | 38 ++++++++++--------- .../python/endpoints/audience-groups.md | 2 +- .../python/endpoints/brands.md | 2 +- .../python/endpoints/brandscape-data.md | 28 +++++++++++--- .../python/endpoints/categories.md | 4 +- .../python/endpoints/cities.md | 2 +- .../python/endpoints/companies.md | 2 +- .../developer-tools/python/endpoints/index.md | 2 +- .../python/endpoints/regions.md | 2 +- .../python/endpoints/sectors.md | 2 +- docs/developer-tools/python/index.md | 7 ++-- .../python/reference-classes.md | 8 ++-- 13 files changed, 74 insertions(+), 46 deletions(-) diff --git a/docs/developer-tools/python/advanced-usage.md b/docs/developer-tools/python/advanced-usage.md index a362818..ffcca2a 100644 --- a/docs/developer-tools/python/advanced-usage.md +++ b/docs/developer-tools/python/advanced-usage.md @@ -92,7 +92,7 @@ These functions return a list of JSON dictionaries, one for each entry from the :::tip These methods are for custom data processing that does not make a `pandas` DataFrame. But you can also use some of -the parsing functions in `bavapising.responses`. +the parsing functions in `bavapi.parsing.responses`. ::: ## The `Query` class @@ -127,12 +127,19 @@ All Fount queries that use `bavapi.Query` support the following parameters: - `id`: Return only results for a specific id. - `page`: The page number of results to return. -- `per_page`: The number of results to return per page. Default is 25 and maximum is 100. +- `per_page`: The number of results to return per page. The Fount API default is 25 and the maximum is 1000. For + paginated queries, the `bavapi` default is 100. - `max_pages`: The maximum number of pages to request. By default, `bavapi` requests all pages in a query. - `fields`: The keys for the fields to include in the response. Usually they are the field name in lower case. - `sort`: The key(s) for the field(s) to order the response results by. - `include`: Additional linked resources to include in the response. -- `updated_since`: Only return items that changed after this timestamp. +- `metric_keys`: The keys for the metrics to include in the response. Only the `brandscape-data` endpoint supports + this parameter. +- `metric_group_keys`: The keys for the metric groups to include in the response. Only the `brandscape-data` endpoint + supports this parameter. + +To get only the items that changed after a timestamp, use the `updated_since` filter in `filters`. All filters classes +have this filter. For more information about the behavior of each of these parameters, see the [customizing fields](/customizing/fields.md) section. @@ -146,14 +153,14 @@ the Fount API: >>> bavapi.Query( ... filters=BrandscapeFilters( ... brand_name="Facebook", -... year_numbers=[2012, 2013, 2014, 2015] +... year_number=[2012, 2013, 2014, 2015] ... ), ... include=["company"] ... ).to_params(endpoint="brandscape-data") # (1) { - "include[brandscape-data]": "company", # (2) + "include": "company", # (2) "filter[brand_name]": "Facebook", - "year_numbers": "2012,2013,2014,2015", + "filter[year_number]": "2012,2013,2014,2015", } ``` @@ -166,7 +173,7 @@ the Fount API: `bavapi` automatically batches paginated requests to the API to improve latency and throughput. The default values keep about twenty concurrent requests at a time. -`bavapi` also automatically retries failed requests. You can set the number of retries (default `2`). +`bavapi` also automatically retries failed requests. You can set the number of retries (default `3`). Both top-level functions and the `Client` class have the following parameters to control the behavior of the requests: diff --git a/docs/developer-tools/python/basic-usage.md b/docs/developer-tools/python/basic-usage.md index 8bc5d45..c5d546c 100644 --- a/docs/developer-tools/python/basic-usage.md +++ b/docs/developer-tools/python/basic-usage.md @@ -36,7 +36,7 @@ You can make requests to other [endpoints](endpoints/) in the same way: ```py uk_studies = bavapi.studies("TOKEN", country_code="GB") -uk22 = bavapi.brandscape_data("TOKEN", year_numbers=2022, country_code="GB", audiences=1) +uk22 = bavapi.brandscape_data("TOKEN", year_number=2022, country_code="GB", audiences=1) all_adults = bavapi.audiences("TOKEN", name="All Adults") ``` @@ -53,7 +53,7 @@ To query unsupported endpoints, see the [Other endpoints](advanced-usage#other-e from your query and filters are of the type that the Fount API expects. If a parameter does not agree with the API requirements, `bavapi` will raise a `ValidationError`. -:::note What it's doing +:::note How validation works `bavapi` sends an initial request to make sure that the query parameters are valid. This request also gets the number of pages that `bavapi` must fetch. @@ -70,21 +70,25 @@ Each endpoint has its own filter requirements, so each endpoint has a related fi | Endpoint | Filters class | |-------------------------|----------------------------| +| `"audience-groups"` | `AudienceGroupsFilters` | | `"audiences"` | `AudiencesFilters` | | `"brand-metrics"` | `BrandMetricsFilters` | | `"brand-metric-groups"` | `BrandMetricGroupsFilters` | | `"brands"` | `BrandsFilters` | | `"brandscape-data"` | `BrandscapeFilters` | | `"categories"` | `CategoriesFilters` | +| `"cities"` | `CitiesFilters` | | `"collections"` | `CollectionsFilters` | | `"companies"` | `CompaniesFilters` | +| `"countries"` | `CountriesFilters` | +| `"regions"` | `RegionsFilters` | | `"sectors"` | `SectorsFilters` | | `"studies"` | `StudiesFilters` | | `"years"` | `YearsFilters` | These filters are available under the `bavapi.filters` namespace. -:::caution Don't mix and match filters +:::caution Use the correct filters class for each endpoint If you use a filters class that is not for the specific endpoint, you will not get errors at the start. But you will also not get IDE type support or type validation for the parameters of that endpoint. @@ -111,7 +115,7 @@ create a filters instance directly. ```py result = bavapi.brands( - filters=bavapi.filters.BrandsFilters(name="Swatch", country_codes=["US", "UK"]) + "TOKEN", filters=bavapi.filters.BrandsFilters(name="Swatch", country_codes=["US", "GB"]) ) ``` @@ -120,7 +124,7 @@ result = bavapi.brands( ```py result = bavapi.brands( - filters={"name":"Swatch", "country_codes":["US", "UK"]} + "TOKEN", filters={"name":"Swatch", "country_codes":["US", "GB"]} ) ``` @@ -131,7 +135,7 @@ result = bavapi.brands( If you specify both regular function parameters and filters, the request uses the values in the filters parameter: ```py -result = bavapi.brands(name="Swatch", filters={"name": "Facebook"}) +result = bavapi.brands("TOKEN", name="Swatch", filters={"name": "Facebook"}) ``` The request will use `name="Facebook"`, because values specified in the `filters` parameter take precedence. @@ -146,16 +150,16 @@ You **must** specify these value filters in the `filters` parameter. If you add keyword arguments, `bavapi` will raise a `ValidationError`. ```py -bavapi.brands(name="Swatch", filters={"sector_name": "Watches"}) # ok +bavapi.brands("TOKEN", name="Swatch", filters={"sector_name": "Watches"}) # ok -bavapi.brands(name="Swatch", sector_name="Watches") # raises ValidationError +bavapi.brands("TOKEN", name="Swatch", sector_name="Watches") # raises ValidationError ``` Some value filters are not available as arguments to the function call. If you use these value filters, we recommend that you use only the `filters` parameter. Do not mix function parameters and Filters parameters: ```py -bavapi.brands(filters=bavapi.filters.BrandsFilters(name="Swatch", sector_name="Watches")) +bavapi.brands("TOKEN", filters=bavapi.filters.BrandsFilters(name="Swatch", sector_name="Watches")) ``` ### Fields @@ -164,7 +168,7 @@ You can [specify which fields](/customizing/fields.md) a response contains. If y **only** those fields. ```py -result = bavapi.brands(name="Swatch", fields=["id", "name"]) +result = bavapi.brands("TOKEN", name="Swatch", fields=["id", "name"]) result.columns # will only have ["id", "name"] as columns ``` @@ -174,10 +178,10 @@ You can [sort the data](/customizing/filters.md#sorting-results) by a column fro ```py # sorted by name -result = bavapi.brands(name="Swatch", sort="name") +result = bavapi.brands("TOKEN", name="Swatch", sort="name") # descending sorted by name (note the '-') -result = bavapi.brands(name="Swatch", sort="-name") +result = bavapi.brands("TOKEN", name="Swatch", sort="-name") ``` By default, responses are sorted by item id, in ascending order. @@ -191,7 +195,7 @@ that each endpoint supports, read the [API documentation](/intro.md). ```py # will include info about the brand's company -result = bavapi.brands(name="Swatch", includes="company") +result = bavapi.brands("TOKEN", name="Swatch", include="company") ``` :::note Default Includes @@ -212,7 +216,7 @@ Three parameters control pagination: If you set only `page` to an integer greater than `0`, `bavapi` requests only that page. ```py -bavapi.studies(page=1) # Will request a single page of data +bavapi.studies("TOKEN", page=1) # Will request a single page of data ``` If you set `per_page` or `max_pages`, `bavapi` will request the applicable pages from the Fount API. @@ -271,7 +275,7 @@ object take precedence over the parameters at the function level. ```py # will use `name="Facebook"` because `query` values take precedence. -bavapi.brands(name="Swatch", query=bavapi.Query(filters={"name":"Facebook"})) +bavapi.brands("TOKEN", name="Swatch", query=bavapi.Query(filters={"name":"Facebook"})) ``` :::note @@ -297,7 +301,7 @@ The `bavapi` functions and methods have a `stack_data` parameter. This parameter It then makes a new entry (row) in the resulting DataFrame for each element in the list. ```py -bavapi.brands("Facebook", include="studies", stack_data=True) +bavapi.brands("TOKEN", "Facebook", include="studies", stack_data=True) ``` | | id | name | studies_id | studies_name | ... | @@ -389,7 +393,7 @@ Exception: ... # Raised -:::caution "Some requests may still raise" +:::caution Some requests can still raise exceptions During the initial handshake between `bavapi` and the Fount API, `bavapi` retries only SSL errors. Thus, some queries can still raise exceptions when `on_errors` is set to `"warn"`: diff --git a/docs/developer-tools/python/endpoints/audience-groups.md b/docs/developer-tools/python/endpoints/audience-groups.md index cc8f95d..81a08e5 100644 --- a/docs/developer-tools/python/endpoints/audience-groups.md +++ b/docs/developer-tools/python/endpoints/audience-groups.md @@ -4,7 +4,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; :::info -Read more in the API documentation for the [`audience-groups` endpoint](/core-resources/audience-groups.md). +Read more in the API documentation for the [`audience-groups` endpoint](/audiences/audience-groups.md). ::: The `audience-groups` endpoint has full support. This support includes query validation. diff --git a/docs/developer-tools/python/endpoints/brands.md b/docs/developer-tools/python/endpoints/brands.md index 0b861d1..e83248e 100644 --- a/docs/developer-tools/python/endpoints/brands.md +++ b/docs/developer-tools/python/endpoints/brands.md @@ -4,7 +4,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; :::info -Read more in the API documentation for the [`brands` endpoint](/core-resources/brands.md). +Read more in the API documentation for the [`brands` endpoint](/brands/brands.md). ::: The `brands` endpoint has full support. This support includes query validation. diff --git a/docs/developer-tools/python/endpoints/brandscape-data.md b/docs/developer-tools/python/endpoints/brandscape-data.md index 3152cba..364993f 100644 --- a/docs/developer-tools/python/endpoints/brandscape-data.md +++ b/docs/developer-tools/python/endpoints/brandscape-data.md @@ -21,7 +21,7 @@ The `brandscape-data` endpoint has full support. This support includes query val ```py title="Using top-level functions" import bavapi -result = bavapi.brandscape_data("TOKEN", name="Facebook") +result = bavapi.brandscape_data("TOKEN", brand_name="Facebook") ``` @@ -31,7 +31,7 @@ result = bavapi.brandscape_data("TOKEN", name="Facebook") import bavapi async with bavapi.Client("TOKEN") as bav: - result = await bav.brandscape_data(name="Facebook") + result = await bav.brandscape_data(brand_name="Facebook") ``` @@ -70,7 +70,7 @@ bavapi.brandscape_data("TOKEN", year_number=2022) # Error, not enough filters bavapi.brandscape_data("TOKEN", brand_name="Facebook") # OK bavapi.brandscape_data( - "TOKEN", filters=bavapi.filters.BrandscapeFilters(audience=22, brands=123) + "TOKEN", filters=bavapi.filters.BrandscapeFilters(audiences=22, brands=123) ) # OK ``` @@ -111,11 +111,16 @@ Thus, a set of columns from the `"brand"` include will have a `"global_"` prefix This can change in future versions of `bavapi` when the parsing logic changes. ::: -## Metric keys +## Metric and metric group keys -`brandscape-data` has a special filter to specify which data *columns* the response contains: `metric_keys`. +`brandscape-data` functions and methods have two special parameters to specify which data *columns* the response +contains: `metric_keys` and `metric_group_keys`. -You can specify the metrics for your response. The API will include all score types for each of these metrics. +- Use `metric_keys` to specify the metrics for your response. +- Use `metric_group_keys` to specify the metric groups for your response. + +The API will include all score types for each of these metrics or metric groups. Each parameter accepts one key or a +list of keys. :::info Example If you set `metric_keys` to `["differentiation", "relevance"]`, the request will return only the following columns: @@ -127,3 +132,14 @@ If you set `metric_keys` to `["differentiation", "relevance"]`, the request will - Brand information such as `id`, `brand_name`, and `category_name` - Any additional columns from the `include` parameter ::: + +```py +# Returns only the score columns for the "differentiation" metric +bavapi.brandscape_data("TOKEN", studies=111, metric_keys="differentiation") + +# Returns only the score columns for the metrics in the "pillars" metric group +bavapi.brandscape_data("TOKEN", studies=111, metric_group_keys="pillars") +``` + +To find the available metric keys and metric group keys, use the [`brand-metrics`](brand-metrics.md) and +[`brand-metric-groups`](brand-metric-groups.md) endpoints. diff --git a/docs/developer-tools/python/endpoints/categories.md b/docs/developer-tools/python/endpoints/categories.md index 8f76b17..fa94f64 100644 --- a/docs/developer-tools/python/endpoints/categories.md +++ b/docs/developer-tools/python/endpoints/categories.md @@ -4,7 +4,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; :::info -Read more in the API documentation for the [`categories` endpoint](/core-resources/categories.md). +Read more in the API documentation for the [`categories` endpoint](/studies/categories.md). ::: The `categories` endpoint has full support. This support includes query validation. @@ -54,7 +54,7 @@ from `categories`. They also make its structure align with data downloads from t ```py # All default (sector) includes will be requested -bavapi.categories("TOKEN", name="All Adults") +bavapi.categories("TOKEN", name="Soap") ``` To suppress default includes, set `include` to `"no_default"`. diff --git a/docs/developer-tools/python/endpoints/cities.md b/docs/developer-tools/python/endpoints/cities.md index dbd9888..abe5643 100644 --- a/docs/developer-tools/python/endpoints/cities.md +++ b/docs/developer-tools/python/endpoints/cities.md @@ -4,7 +4,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; :::info -Read more in the API documentation for the [`cities` endpoint](/core-resources/cities.md). +Read more in the API documentation for the [`cities` endpoint](/metadata/cities.md). ::: The `cities` endpoint has full support. This support includes query validation. diff --git a/docs/developer-tools/python/endpoints/companies.md b/docs/developer-tools/python/endpoints/companies.md index ea070d8..4dbd1da 100644 --- a/docs/developer-tools/python/endpoints/companies.md +++ b/docs/developer-tools/python/endpoints/companies.md @@ -4,7 +4,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; :::info -Read more in the API documentation for the [`companies` endpoint](/core-resources/companies.md). +Read more in the API documentation for the [`companies` endpoint](/company-data/companies.md). ::: The `companies` endpoint has full support. This support includes query validation. diff --git a/docs/developer-tools/python/endpoints/index.md b/docs/developer-tools/python/endpoints/index.md index a96491f..3618a6c 100644 --- a/docs/developer-tools/python/endpoints/index.md +++ b/docs/developer-tools/python/endpoints/index.md @@ -87,7 +87,7 @@ The result of these queries is a list of JSON dictionaries. To parse the JSON re import bavapi from bavapi.parsing.responses import parse_response -result = bavapi.raw_query("companies", bavapi.Query()) +result = bavapi.raw_query("TOKEN", "companies", bavapi.Query()) parsed = parse_response(result) # will return a DataFrame ``` diff --git a/docs/developer-tools/python/endpoints/regions.md b/docs/developer-tools/python/endpoints/regions.md index 95e72c1..8c77def 100644 --- a/docs/developer-tools/python/endpoints/regions.md +++ b/docs/developer-tools/python/endpoints/regions.md @@ -4,7 +4,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; :::info -Read more in the API documentation for the [`regions` endpoint](/core-resources/regions.md). +Read more in the API documentation for the [`regions` endpoint](/metadata/regions.md). ::: The `regions` endpoint has full support. This support includes query validation. diff --git a/docs/developer-tools/python/endpoints/sectors.md b/docs/developer-tools/python/endpoints/sectors.md index 9cbfc7d..589115e 100644 --- a/docs/developer-tools/python/endpoints/sectors.md +++ b/docs/developer-tools/python/endpoints/sectors.md @@ -4,7 +4,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; :::info -Read more in the API documentation for the [`sectors` endpoint](/core-resources/sectors.md). +Read more in the API documentation for the [`sectors` endpoint](/metadata/sectors.md). ::: The `sectors` endpoint has full support. This support includes query validation. diff --git a/docs/developer-tools/python/index.md b/docs/developer-tools/python/index.md index 2a672d3..172010b 100644 --- a/docs/developer-tools/python/index.md +++ b/docs/developer-tools/python/index.md @@ -24,12 +24,12 @@ After the installation, see [Basic Usage](basic-usage.md). For more advanced top [Advanced Usage](advanced-usage.md) section. The behavior of each Fount API endpoint can be slightly different. You can find detailed explanations in -the [Endpoints](python/endpoints/) section. +the [Endpoints](endpoints/index.md) section. ## Example usage -:::info "Protected access" -:lock: To use `bavapi`, you need a Fount API token. Read more in the [Authentication](../authentication) section. +:::info Protected access +:lock: To use `bavapi`, you need a Fount API token. Read more in the [Authentication](authentication.md) section. ::: ```py @@ -58,6 +58,7 @@ the [Endpoints](python/endpoints/) section. - [`collections`](endpoints/collections.md) - [`companies`](endpoints/companies.md) - [`countries`](endpoints/countries.md) + - [`regions`](endpoints/regions.md) - [`sectors`](endpoints/sectors.md) - [`studies`](endpoints/studies.md) - [`years`](endpoints/years.md) diff --git a/docs/developer-tools/python/reference-classes.md b/docs/developer-tools/python/reference-classes.md index 41ad489..2083efb 100644 --- a/docs/developer-tools/python/reference-classes.md +++ b/docs/developer-tools/python/reference-classes.md @@ -14,7 +14,7 @@ A console command generates these classes automatically. This command becomes av :::note Protected Access You need a Fount API token to generate reference files. For more information, and for instructions on how to use -`.env` files in your Python project, see the [Authentication](developer-tools/python/authentication.md) section. +`.env` files in your Python project, see the [Authentication](authentication.md) section. ::: As of `v1.1`, the command generates the following reference classes in a folder named `bavapi_refs`: @@ -36,14 +36,14 @@ You can use it to make your filters for API responses easier to read: ```py title="Explicit audience filter" -bavapi.brandscape_data(country_code="US", year=2022, audiences=Audiences.ALL_ADULTS) +bavapi.brandscape_data("TOKEN", country_code="US", year_number=2022, audiences=Audiences.ALL_ADULTS) ``` ```py title="Audience filter not human-readable" -bavapi.brandscape_data(country_code="US", year=2022, audiences=27) +bavapi.brandscape_data("TOKEN", country_code="US", year_number=2022, audiences=27) ``` @@ -57,7 +57,7 @@ When you generate these reference classes, you have two options to authenticate - Specify the Fount API token with the `-t`/`--token` argument. - Store your Fount API token in a `.env` file, and install `python-dotenv` to read the file into your environment. - For more information, see the [Authentication](authentication.md#recommended-way-to-manage-api-keys) section. + For more information, see the [Authentication](authentication.md) section. Run the following command: From f329f80a8fe6dbe67ec5105a23c294945d931e51 Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Sun, 25 Oct 2026 10:40:57 +0100 Subject: [PATCH 21/23] Fix errors and inconsistencies in the REST and MCP docs Co-Authored-By: Claude Opus 5.5 --- docs/ai/mcp/bav.md | 2 +- docs/audience-origin/frequencies.md | 4 +-- docs/audience-origin/metric-groups.md | 4 +-- docs/audience-origin/metrics.md | 4 +-- docs/audience-origin/touchpoints.md | 4 +-- docs/audiences/audience-groups.md | 6 ++-- docs/audiences/audiences.md | 6 ++-- docs/audiences/export.md | 25 +++++++++++--- docs/audiences/managing-audiences.md | 6 ++-- docs/best-countries/metrics.md | 31 ++++++++++++++++- docs/brand-data/brand-worth.md | 2 ++ docs/brand-data/cee-opinions.md | 4 +-- docs/brand-data/commitment-funnel.md | 4 +-- docs/brand-data/influence.md | 2 ++ docs/brand-data/super-cx.md | 2 ++ docs/brands/brand-variations.md | 4 +-- docs/brands/brands.md | 4 +-- docs/brands/collections.md | 4 +-- docs/company-data/companies.md | 4 +-- docs/customizing/filters.md | 7 ++-- docs/embed/implementation.md | 21 ++++++------ docs/intro.md | 2 +- docs/measures/bav-question-groups.md | 4 +-- docs/measures/brand-measure-groups.md | 4 +-- docs/metadata/cities.md | 4 +-- docs/metadata/countries.md | 4 +-- docs/metadata/operating-companies.md | 24 ++++++++----- docs/metadata/regions.md | 11 +++--- docs/metadata/sectors.md | 8 ++--- docs/metadata/stock-exchanges.md | 8 +++-- docs/metadata/tools.md | 49 +++++++++++++++++---------- docs/metadata/years.md | 2 +- docs/metrics/metric-groups.md | 4 +-- docs/metrics/metrics.md | 4 +-- docs/pagination.md | 8 ++--- docs/studies/categories.md | 4 +-- docs/studies/studies.md | 4 +-- docs/webhooks.md | 2 +- 38 files changed, 185 insertions(+), 111 deletions(-) diff --git a/docs/ai/mcp/bav.md b/docs/ai/mcp/bav.md index 9da301f..1d643de 100644 --- a/docs/ai/mcp/bav.md +++ b/docs/ai/mcp/bav.md @@ -49,7 +49,7 @@ does not have access to that part of the platform. Most tools are available to a products need more access. The access column in the tables below tells what each tool requires. **Tip:** You can ask the agent to list the available tools. You can also use -the [list tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#listing-tools) mechanism from +the [list tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#listing-tools) mechanism from the MCP specification. This mechanism returns the full tool definitions, with parameters and descriptions. ### Metadata and Lookup Tools diff --git a/docs/audience-origin/frequencies.md b/docs/audience-origin/frequencies.md index 165ff5b..e6a5361 100644 --- a/docs/audience-origin/frequencies.md +++ b/docs/audience-origin/frequencies.md @@ -48,8 +48,8 @@ The API uses the slim relationship schema when the frequency is part of an inclu ## Additional Filters -For convenience, there is a set of additional filters. These filters are not in -the [default filters](../customizing/filters.md) and are not columns. The additional filters are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `has_metrics` - Set to `1` to return only frequencies that are used by at least one metric. diff --git a/docs/audience-origin/metric-groups.md b/docs/audience-origin/metric-groups.md index a56032f..46c3634 100644 --- a/docs/audience-origin/metric-groups.md +++ b/docs/audience-origin/metric-groups.md @@ -53,8 +53,8 @@ The API uses the slim relationship schema when the metric group is part of an in ## Additional Filters -For convenience, there is a set of additional filters. These filters are not in -the [default filters](../customizing/filters.md) and are not columns. The additional filters are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `only_parents` - Set to `1` to return only top-level groups. - `only_children` - Set to `1` to return only groups nested under a parent. diff --git a/docs/audience-origin/metrics.md b/docs/audience-origin/metrics.md index c66f3f5..81b1d82 100644 --- a/docs/audience-origin/metrics.md +++ b/docs/audience-origin/metrics.md @@ -77,8 +77,8 @@ value can mean different things in two studies. ## Additional Filters -For convenience, there is a set of additional filters. These filters are not in -the [default filters](../customizing/filters.md) and are not columns. The additional filters are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `touchpoint_id` - The ID of a [touchpoint](touchpoints.md) to filter by. - `frequency_id` - The ID of a [frequency](frequencies.md) to filter by. diff --git a/docs/audience-origin/touchpoints.md b/docs/audience-origin/touchpoints.md index a6fc41e..cbadd69 100644 --- a/docs/audience-origin/touchpoints.md +++ b/docs/audience-origin/touchpoints.md @@ -48,8 +48,8 @@ The API uses the slim relationship schema when the touchpoint is part of an incl ## Additional Filters -For convenience, there is a set of additional filters. These filters are not in -the [default filters](../customizing/filters.md) and are not columns. The additional filters are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `has_metrics` - Set to `1` to return only touchpoints that are used by at least one metric. diff --git a/docs/audiences/audience-groups.md b/docs/audiences/audience-groups.md index 526a59d..199d312 100644 --- a/docs/audiences/audience-groups.md +++ b/docs/audiences/audience-groups.md @@ -36,7 +36,7 @@ The audience groups endpoints are read-only. | `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the audience group. | | `description` | string | :white_check_mark: | :x: | :white_check_mark: | An optional description about what the group is. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this audience group was first created. | -| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this audience group was last updated. | +| `updated_at` | string | ([updated since](../customizing/filters.md)) | :white_check_mark: | :white_check_mark: | A datetime string when this audience group was last updated. | ### Relationship Response Schema @@ -50,7 +50,7 @@ The API uses the slim relationship schema when the audience group is part of an ## Relationships & includes By default, the response does not include relationships. See -the [includes section](../customizing/includes) for more information on how this works. The following relationships +the [includes section](../customizing/includes.md) for more information on how this works. The following relationships are available: - `audiences` - The [audiences](audiences.md) that belong to this audience group, with the @@ -58,4 +58,4 @@ are available: ## Searching -This endpoint supports searching. See the [searching section](../customizing/searching) for more details. \ No newline at end of file +This endpoint supports searching. See the [searching section](../customizing/searching.md) for more details. \ No newline at end of file diff --git a/docs/audiences/audiences.md b/docs/audiences/audiences.md index 172697e..1a39672 100644 --- a/docs/audiences/audiences.md +++ b/docs/audiences/audiences.md @@ -50,7 +50,7 @@ GET /api/v2/audiences/1 Where `1` is the system ID of the audience. Include `definitions.segments.metrics` to get its full definition. -:::note All adults is the base audiences +:::note All Adults is the base audience The All Adults audience is our definition of "unfiltered" or "everyone". It always has the system ID of 1. ::: @@ -133,8 +133,8 @@ See [Managing audiences](managing-audiences.md) for the full segment and metric ## Additional Filters -For convenience, audiences have a set of additional filters. These filters are not in -the [default filters](../customizing/filters.md) and are not columns. The additional filters are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `active` - Set to `1` to return only active audiences. - `inactive` - Set to `1` to return only inactive audiences. diff --git a/docs/audiences/export.md b/docs/audiences/export.md index 9dbe07a..d81c425 100644 --- a/docs/audiences/export.md +++ b/docs/audiences/export.md @@ -68,6 +68,23 @@ We want to make the integration as smooth as possible for you and your users. ## Export Types +### Audience Definition + +The Audience Definition is the full audience with its definitions, segments and metrics. Use it to create the audience +again in your own system. This export option is available for all datasets. + +#### Schema + +The payload uses the [full response schema](audiences.md#full-response-schema) of the Audiences API. It is the same +object that the [Webhooks](../webhooks.md) send for audience data changes. The payload includes these relationships: + +- `group` - The [audience group](audience-groups.md). +- `user` - The owner, with their `operating_company`. +- `definitions` - The [definitions](audiences.md#definition-schema), with their `segments`. Each segment includes its + `metrics`. + +The payload does not include a `respondents` key. + ### BAV Respondent IDs The BAV Respondent ID is a unique identifier for each respondent in an audience. This ID links the respondent to each @@ -92,7 +109,7 @@ the [Audience API schema](audiences.md). "is_public": false, "is_standard": false, "deployed_at": "2021-01-01T00:00:00Z", - "segments_updated_at": "2021-01-01T00:00:00Z", + "definitions_updated_at": "2021-01-01T00:00:00Z", "created_at": "2021-01-01T00:00:00Z", "updated_at": "2021-01-01T00:00:00Z", "group": { @@ -138,7 +155,7 @@ the [Audience API schema](audiences.md). "is_public": false, "is_standard": false, "deployed_at": "2021-01-01T00:00:00Z", - "segments_updated_at": "2021-01-01T00:00:00Z", + "definitions_updated_at": "2021-01-01T00:00:00Z", "created_at": "2021-01-01T00:00:00Z", "updated_at": "2021-01-01T00:00:00Z", "group": { @@ -162,7 +179,7 @@ the [Audience API schema](audiences.md). ### Audience Origin Progressive Numbers -The Audience Origin progressive number is an alternative ID. The GroupM Italy Audience Creator is its primary user. +The Audience Origin progressive number is an alternative ID. The Italy Audience Creator is its primary user. GroupM in Italy uses this tool. :::warning Specific approval required This export option is available only after approval from Choreograph. @@ -183,7 +200,7 @@ the [Audience API schema](audiences.md). "is_public": false, "is_standard": false, "deployed_at": "2021-01-01T00:00:00Z", - "segments_updated_at": "2021-01-01T00:00:00Z", + "definitions_updated_at": "2021-01-01T00:00:00Z", "created_at": "2021-01-01T00:00:00Z", "updated_at": "2021-01-01T00:00:00Z", "group": { diff --git a/docs/audiences/managing-audiences.md b/docs/audiences/managing-audiences.md index 788343e..969d5cf 100644 --- a/docs/audiences/managing-audiences.md +++ b/docs/audiences/managing-audiences.md @@ -13,7 +13,7 @@ An audience has these layers: - **Audience.** The audience itself with its name, description and visibility. - **Definitions.** An audience has one or more definitions. Each definition reads from a dataset (`bav` or - `audience-origin`) and uses the questions of a base study. A definition can also be limited to a specific country or + `audience-origin`). Audiences support only these two datasets. Each definition uses the questions of a base study. A definition can also be limited to a specific country or study. A definition that is not limited applies to all of the audience's data. - **Segments.** Each definition contains segments. A segment is a group of conditions that a respondent has to meet. The `within_segment_operator` decides how the conditions inside the segment combine (`AND` requires all of them, `OR` @@ -107,7 +107,7 @@ Each definition in `definitions` accepts: | Key | Type | Required | Description | |-----------------------|---------|:------------------:|-------------------------------------------------------------------------------------------------------------------------------------| -| `dataset` | string | :white_check_mark: | The dataset the definition reads from. One of `bav`, `audience-origin`, `best-countries` or `momentum`. | +| `dataset` | string | :white_check_mark: | The dataset the definition reads from. Use `bav` or `audience-origin`. The validation also accepts `best-countries` and `momentum`, but audiences do not support these datasets. | | `base_study_id` | integer | :white_check_mark: | The ID of the [study](../studies/studies.md) whose questions the definition uses. | | `definitionable_type` | string | :x: | What the definition is limited to: `country` or `study`. Leave empty for a definition that applies to all of the audience's data. | | `definitionable_id` | integer | :x: | The ID of the country or study the definition is limited to. | @@ -247,7 +247,7 @@ When you delete a segment, the API also deletes its metrics. The response has th | `within_segment_operator` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | How the metrics in the segment combine: `AND` or `OR`. | | `between_segments_operator` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | How the segment combines with the one before it: `AND` or `OR`. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this segment was first created. | -| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this segment was last updated. | +| `updated_at` | string | ([updated since](../customizing/filters.md)) | :white_check_mark: | :white_check_mark: | A datetime string when this segment was last updated. | | `metrics` | array | :x: | :x: | :x: | The [segment metrics](#segment-metric-schema) that make up the segment. Always included. | The following relationships are available as includes on the segment endpoints: diff --git a/docs/best-countries/metrics.md b/docs/best-countries/metrics.md index 482c80c..9cad79c 100644 --- a/docs/best-countries/metrics.md +++ b/docs/best-countries/metrics.md @@ -9,6 +9,8 @@ sidebar_label: Metrics When BAV studies a country in Best Countries, it uses different metrics. These metrics are divided into [groups](metric-groups.md) to make them easier to browse. +This endpoint requires the **Best Countries Data** (`bav:best-countries-data`) scope. + ## List all best countries metrics To list all of the best countries metrics and browse them through the API, use the list endpoint: @@ -25,6 +27,33 @@ If you already have the system ID of a best countries metric, you can also get i GET /api/v2/best-countries-metrics/123 ``` -Where `123` is the system ID of the brand metric. +Where `123` is the system ID of the best countries metric. ## Schema + +### Full response schema + +| Key | Type | Filterable | Sortable | Configurable | Description | +|------------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-----------------------------------------------------------------------------------------------------| +| `id` | integer | :x: | :x: | :x: | The system ID. | +| `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | If true, the metric is active. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the metric. | +| `key` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The machine-readable key of the metric. The Best Countries data endpoints name their fields after it. | +| `description` | string | :white_check_mark: | :x: | :white_check_mark: | A description of what the metric measures. | +| `group` | object | :white_check_mark: (as `group_id`) | :white_check_mark: | :white_check_mark: | The [metric group](metric-groups.md) that the metric belongs to. | +| `type` | object | :white_check_mark: | :x: | :white_check_mark: | The metric type, as an `id` (for example `boolean` or `seven_scalar`) and a readable `name`. | +| `is_respondent_metric` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | If true, the metric is a respondent-level metric. | +| `is_city_metric` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | If true, the metric applies to cities. | +| `is_country_metric` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | If true, the metric applies to countries. | +| `created_at` | string | :white_check_mark: | :x: | :white_check_mark: | A datetime string when this metric was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :x: | :white_check_mark: | A datetime string when this metric was last updated. | + +You can sort on `group_id`, `group.name` and `group.key`. The `type` filter takes the type `id`, for example +`filter[type]=boolean`. + +## Relationships & includes + +By default, relationships are not included. See the [includes section](../customizing/includes) for more information +on how this works. The following relationships are available: + +- `factors` - The [factors](factors.md) that the metric contributes to. diff --git a/docs/brand-data/brand-worth.md b/docs/brand-data/brand-worth.md index 11256ce..70dd051 100644 --- a/docs/brand-data/brand-worth.md +++ b/docs/brand-data/brand-worth.md @@ -16,6 +16,8 @@ For the Brand Worth Map tool, see the [Brand Worth Map](brand-worth-map.md) endp POST /api/v2/brandscape/brand-worth ``` +Send the parameters as a JSON body. + This endpoint requires the `bav:brand-data` scope. ## Parameters diff --git a/docs/brand-data/cee-opinions.md b/docs/brand-data/cee-opinions.md index 3d758c6..933a07f 100644 --- a/docs/brand-data/cee-opinions.md +++ b/docs/brand-data/cee-opinions.md @@ -38,8 +38,8 @@ You can do the same with `id` (exact filter), `created_at` and `updated_at`. ## Additional Filters -For convenience, there are also some additional filters for opinions. These filters are not in -the [default filters](../customizing/filters.md) and are not part of the columns. They are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `years` - A comma-separated list of year IDs. This filters the opinions to only those for the given years. - `year_number` - A comma-separated list of year numbers. This filters the opinions to only those for the given diff --git a/docs/brand-data/commitment-funnel.md b/docs/brand-data/commitment-funnel.md index 850e100..756b77a 100644 --- a/docs/brand-data/commitment-funnel.md +++ b/docs/brand-data/commitment-funnel.md @@ -9,7 +9,7 @@ It has seven stages: Loyalty, Adoption and Consideration (behavioral), Awareness GET /api/v2/tools/commitment-funnel ``` -This endpoint takes the same filters as the [brandscape data models](brandscape-data.md). Pass array parameters with +This endpoint takes the same filters as the [data models](data-models.md). Pass array parameters with array syntax, for example: ```http request @@ -32,7 +32,7 @@ You can use `countries` and `years` instead to select studies by market and year :::note -The [brandscape data models](brandscape-data.md) accept the `benchmarks` and `format` parameters. These parameters pass +The [data models](data-models.md) accept the `benchmarks` and `format` parameters. These parameters pass validation on this endpoint, but the endpoint does not apply them. The Commitment Funnel always responds with JSON and does not add benchmark rows. diff --git a/docs/brand-data/influence.md b/docs/brand-data/influence.md index 98a3509..1d9ce19 100644 --- a/docs/brand-data/influence.md +++ b/docs/brand-data/influence.md @@ -11,6 +11,8 @@ Influence is category agnostic. POST /api/v2/brandscape/influence ``` +Send the parameters as a JSON body. + This endpoint requires the `bav:brand-data` scope. ## Parameters diff --git a/docs/brand-data/super-cx.md b/docs/brand-data/super-cx.md index cc6752a..35dd2ee 100644 --- a/docs/brand-data/super-cx.md +++ b/docs/brand-data/super-cx.md @@ -15,6 +15,8 @@ endpoint for new integrations, because it shares its parameters and response wit POST /api/v2/brandscape/super-cx ``` +Send the parameters as a JSON body. + This endpoint requires the `bav:brand-data` scope. ## Parameters diff --git a/docs/brands/brand-variations.md b/docs/brands/brand-variations.md index 4abe66e..eb92f29 100644 --- a/docs/brands/brand-variations.md +++ b/docs/brands/brand-variations.md @@ -66,8 +66,8 @@ the brandscape data. ## Additional Filters -For convenience, brand variations have a set of additional filters. These filters are not in -the [default filters](../customizing/filters.md) and are not columns. The additional filters are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `brands` - A comma-separated list of brand IDs. The filter returns only the variations of these brands. - `keys` - A comma-separated list of brand variation keys. diff --git a/docs/brands/brands.md b/docs/brands/brands.md index 931c0b7..282617b 100644 --- a/docs/brands/brands.md +++ b/docs/brands/brands.md @@ -84,8 +84,8 @@ it for the `replacement`, `parent` and `children` includes. ## Additional Filters -For convenience, brands have a set of additional filters. These filters are not in -the [default filters](../customizing/filters.md) and are not columns. The additional filters are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `years` - A comma-separated list of year IDs. The filter returns only the brands that are studied in the specified years. diff --git a/docs/brands/collections.md b/docs/brands/collections.md index b339ed4..80659ad 100644 --- a/docs/brands/collections.md +++ b/docs/brands/collections.md @@ -61,8 +61,8 @@ Where `123` is the system ID of the collection. ## Additional Filters -For convenience, collections have a set of additional filters. These filters are not in -the [default filters](../customizing/filters.md) and are not columns. The additional filters are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `public` - Set to `1` to return only public collections. - `shared_with_me` - Set to `1` to return only collections shared with the user. diff --git a/docs/company-data/companies.md b/docs/company-data/companies.md index e535fe2..4cecc15 100644 --- a/docs/company-data/companies.md +++ b/docs/company-data/companies.md @@ -76,8 +76,8 @@ The API uses the slim relationship schema when the company is part of an include ## Additional Filters -For convenience, there are some additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `public` - Set to `1` to only return public (listed) companies. - `private` - Set to `1` to only return private (unlisted) companies. diff --git a/docs/customizing/filters.md b/docs/customizing/filters.md index 10669a5..ed2b0ff 100644 --- a/docs/customizing/filters.md +++ b/docs/customizing/filters.md @@ -45,10 +45,11 @@ GET /api/v2/brands?sort=-name ## Updated Since -On an index request, you can get only the data that was updated after a specific date and time. To do this, use the -`updated_since` filter. This filter takes a date time value in the format `YYYY-MM-DD HH:II:SS`. +On an index request, you can get only the data that was updated on or after a specific date. To do this, use the +`updated_since` filter. This filter takes a date in the format `YYYY-MM-DD`. The filter compares only the date part of +the update time. Do not add a time to the value. -A request that shows only the brands that were updated after January 1, 2023 can look like this: +A request that shows only the brands that were updated on or after January 1, 2023 can look like this: ```http request GET /api/v2/brands?filter[updated_since]=2023-01-01 diff --git a/docs/embed/implementation.md b/docs/embed/implementation.md index 1cc776d..15d81da 100644 --- a/docs/embed/implementation.md +++ b/docs/embed/implementation.md @@ -9,25 +9,26 @@ To bypass the Okta login screen in the embed, you can pre-authenticate your user - Your application must use Okta. - You can pass an email address, first name and last name of your user. -:::note Getting access approval +:::note Access approval To use the embed integration through our auto-login flow and bypass a user connection approval screen, you must request approval. Contact support@bernskiold.com. ::: -:::tip How to authenticate? -For more information about how to authenticate against the API, see the [Authentication](docs/authentication.md) section +:::tip Authentication +For more information about how to authenticate against the API, see the [Authentication](../authentication.md) section in the API docs. ::: To authenticate the user, make a request against the auto login endpoint: -```json +```http request POST https://fount.wppbav.com/api/v1/auto-login +Content-Type: application/json { -"email": "my-email@example.org" -"first_name": "Test", -"last_name": "Person", + "email": "my-email@example.org", + "first_name": "Test", + "last_name": "Person" } ``` @@ -39,7 +40,7 @@ The request returns an access token for the user. Pass this token to the embed i } ``` -:::caution Access Token Expiration +:::caution Access token expiry Access tokens expire every day at 00:00 UTC. ::: @@ -60,6 +61,6 @@ The supported products endpoint gives the required and optional filters that you ``` -:::caution Parameters Format -Always pass the supported parameters in an array format, for example:`?brands[0]=998&brands[1]=999` +:::caution Parameter format +Always pass the supported parameters in an array format, for example `?brands[0]=998&brands[1]=999` ::: \ No newline at end of file diff --git a/docs/intro.md b/docs/intro.md index 5713d9d..414690d 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -6,7 +6,7 @@ system. We made it a priority to make access as simple as possible. To use the API, you need an access token. See the [authentication section](authentication.md) for information about how to get one. -:::note Building a user-facing app? Please let us know... +:::note Tell us about user-facing applications If you integrate BAV data into an application, reporting tool or other system where other people also use the data, [tell us before you do this](/support). It is important for the credibility of BAV that the data is used correctly and shown in the correct context. BAV can be complex, so we want to make sure that you have the correct support and diff --git a/docs/measures/bav-question-groups.md b/docs/measures/bav-question-groups.md index 9714b73..f0f5c7c 100644 --- a/docs/measures/bav-question-groups.md +++ b/docs/measures/bav-question-groups.md @@ -52,8 +52,8 @@ The API uses the slim relationship schema when the BAV question group is part of ## Additional Filters -For convenience, there are some additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `questions` - A comma-separated list of BAV question IDs. The API returns only the groups that contain these questions. diff --git a/docs/measures/brand-measure-groups.md b/docs/measures/brand-measure-groups.md index 52745e8..eca527f 100644 --- a/docs/measures/brand-measure-groups.md +++ b/docs/measures/brand-measure-groups.md @@ -50,8 +50,8 @@ The API uses the slim relationship schema when the brand measure group is part o ## Additional Filters -For convenience, there are some additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `measures` - A comma-separated list of brand measure IDs. The API returns only the groups that contain these measures. diff --git a/docs/metadata/cities.md b/docs/metadata/cities.md index 4dc71fb..1853749 100644 --- a/docs/metadata/cities.md +++ b/docs/metadata/cities.md @@ -46,8 +46,8 @@ You can also sort the cities by `country_id`. To get the country for each city, ## Additional Filters -For convenience, there are some additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `capitals` - Set to `1` to only return capital cities. - `regions` - Set to a comma-separated list of region IDs to only return cities in those regions. diff --git a/docs/metadata/countries.md b/docs/metadata/countries.md index 457147d..c83a9bc 100644 --- a/docs/metadata/countries.md +++ b/docs/metadata/countries.md @@ -61,8 +61,8 @@ The API uses the slim relationship schema when the country is part of an include ## Additional Filters -For convenience, there are some additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `active` - Set to `1` to only return active countries. - `regions` - Set to a comma-separated list of region IDs to only return countries in those regions. diff --git a/docs/metadata/operating-companies.md b/docs/metadata/operating-companies.md index f395594..d3183a3 100644 --- a/docs/metadata/operating-companies.md +++ b/docs/metadata/operating-companies.md @@ -15,7 +15,7 @@ To list all of the operating companies and browse them through the API, use the GET /api/v2/operating-companies ``` -## Get a operating company +## Get an operating company If you already have the system ID of an operating company, you can also get its details directly. @@ -32,27 +32,33 @@ Where `123` is the system ID of the operating company. | Key | Type | Filterable | Sortable | Configurable | Description | |--------------|---------|:-----------------------------------------:|:------------------:|:------------------:|------------------------------------------------------------------| | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | -| `name` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the operating company. | | -| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this operating company was first created. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the operating company. | +| `created_at` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | A datetime string when this operating company was first created. | | `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this operating company was last updated. | ### Relationship Response Schema The API uses the slim relationship schema when the operating company is part of an include in another resource. +| Key | Type | Description | +|--------|---------|------------------------------------------| +| `id` | integer | The system ID for the operating company. | +| `name` | string | The name of the operating company. | + ## Additional Filters -For convenience, there are some additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): -- `parents` - Set to a comma-separated list of operating company IDs to only return countries owned by those operating - companies. +- `parents` - Set to a comma-separated list of operating company IDs to only return the operating companies that + have one of those operating companies as their parent. ## Relationships & includes -By default, relationships apart from the sector are not included. See +By default, relationships are not included. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: -- `parent` - The [company](../company-data/companies.md) that owns another company. +- `parent` - The parent operating company of this operating company, if it has one. The API uses the relationship + schema above. - `brand` - The [brand](../brands/brands.md) that the operating company has. diff --git a/docs/metadata/regions.md b/docs/metadata/regions.md index 81b3675..d102c1e 100644 --- a/docs/metadata/regions.md +++ b/docs/metadata/regions.md @@ -32,18 +32,17 @@ Where `123` is the system ID of the region. | Key | Type | Filterable | Sortable | Configurable | Description | |--------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-------------------------------------------------------| -| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | | -| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the region in english. | | +| `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the region in English. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this region was first created. | | `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this region was last updated. | -### Relationship Response Schema - -The API uses the slim relationship schema when the region is part of an include in another resource. +The region does not have a slim relationship schema. When a [country](countries.md) shows its region, the API uses +the full response schema. ## Relationships & includes -By default, relationships apart from the sector are not included. See +By default, relationships are not included. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: diff --git a/docs/metadata/sectors.md b/docs/metadata/sectors.md index bed8c33..8939c67 100644 --- a/docs/metadata/sectors.md +++ b/docs/metadata/sectors.md @@ -35,7 +35,7 @@ Where `123` is the system ID of the sector. | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | | `is_active` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether you can see and use the sector. | | `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the sector. | -| `excluded_for_most_influential` | - | :white_check_mark: | :white_check_mark: | :white_check_mark: | Whether the sector should be part of the Most Influential brands lists or not. | +| `excluded_for_most_influential` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | If true, the Most Influential Brands lists do not include this sector. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this sector was first created. | | `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this sector was last updated. | @@ -50,15 +50,15 @@ The API uses the slim relationship schema when the sector is part of an include ## Additional Filters -For convenience, there are some additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `in_most_influential` - Set to `1` to only return sectors that are part of the Most Influential lists. - `not_in_most_influential` - Set to `1` to only return sectors that are not part of the Most Influential lists. ## Relationships & includes -By default, relationships apart from the sector are not included. See +By default, relationships are not included. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: diff --git a/docs/metadata/stock-exchanges.md b/docs/metadata/stock-exchanges.md index 0fbc7bf..c2e700f 100644 --- a/docs/metadata/stock-exchanges.md +++ b/docs/metadata/stock-exchanges.md @@ -51,8 +51,8 @@ The API uses the slim relationship schema when the stock exchange is part of an ## Additional Filters -For convenience, there are some additional filters that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `countries` - A comma-separated list of country IDs to only return stock exchanges in those countries. - `country_codes` - A comma-separated list of country codes (two-letter, ISO standard) to only return stock exchanges in @@ -60,8 +60,10 @@ the [default filters](../customizing/filters.md) or are part of the columns. The ## Relationships & includes -By default, relationships apart from the sector are not included. See +By default, relationships are not included. See the [includes section](../customizing/includes) for more information on how this works. The following relationships are available: - `country` - The [country](countries.md) where the exchange is located. +- `companies` - The [companies](../company-data/companies.md) that are listed on the exchange, with the stock ticker + of each company. diff --git a/docs/metadata/tools.md b/docs/metadata/tools.md index 008e169..9838f72 100644 --- a/docs/metadata/tools.md +++ b/docs/metadata/tools.md @@ -14,15 +14,20 @@ To list all of the tools and browse them through the API, use the list endpoint: GET /api/v2/tools ``` -## Get a year +## Get a tool -If you already have the system ID of a year, you can also get its details directly. +If you already have the system ID of a tool, you can also get its details directly. ```http request GET /api/v2/tools/123 ``` -Where `123` is the system ID of the year. +Where `123` is the system ID of the tool. + +:::note +On the list endpoint, each item in the `data` list has its own `data` key, for example `data[0].data.name`. On the +get endpoint, the tool is directly in the `data` key. +::: ## Schema @@ -31,21 +36,29 @@ Where `123` is the system ID of the year. | Key | Type | Filterable | Sortable | Configurable | Description | |------------------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-----------------------------------------------------------------------------------------------------------------------------------------------| | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | -| `name` | integer | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the tool | -| `slug` | string | :white_check_mark: | :x: | :white_check_mark: | A unique key (slug) for the tool, used in URLs. | -| `short_description` | string | :x: | :x: | :white_check_mark: | A short sentence description about what the tool does. | -| `description` | string | :x: | :x: | :white_check_mark: | A longer HTML-formatted description about the tool. | -| `documentation_url` | string | :x: | :x: | :white_check_mark: | The URL to the documentation for this tool (not yet available) | -| `api_documentation_url` | string | :x: | :x: | :white_check_mark: | The URL to the API documentation here on the developer portal. | -| `api_endpoint_url` | string | :x: | :x: | :white_check_mark: | The URL to the API endpoint for the tool, if available. | -| `supported_parameters` | object | :x: | :x: | :white_check_mark: | The filter parameters that the tool supports. The object key is the parameter name, and the value is true/false. | -| `required_parameters` | object | :x: | :x: | :white_check_mark: | The required parameters for the tool. The object key is the parameter name, and the value is true/false. | -| `multiple_choice_parameters` | object | :x: | :x: | :white_check_mark: | The parameters that allow more than one selection. The object key is the parameter name, and the value is true/false. | -| `extra_parameters` | object | :x: | :x: | :white_check_mark: | Additional configuration parameters that control the query experience. | -| `export_formats` | object | :x: | :x: | :white_check_mark: | The available exports in the interface. The object key is the parameter name, and the value is true/false. Only available exports are listed. | -| `is_in_preview` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | If true, the tool is currently unreleased but the user still has access to it under a "preview access" scheme. | -| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this year was first created. | -| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this year was last updated. | +| `name` | string | :white_check_mark: | :white_check_mark: | :white_check_mark: | The name of the tool. | +| `slug` | string | :white_check_mark: | :x: | :white_check_mark: | A unique key (slug) for the tool. The Fount uses it in URLs. | +| `short_description` | string | :x: | :x: | :white_check_mark: | A short sentence that tells what the tool does. | +| `description` | string | :x: | :x: | :white_check_mark: | A longer HTML-formatted description of the tool. | +| `documentation_url` | string | :x: | :x: | :white_check_mark: | The URL to the user documentation for this tool. | +| `api_documentation_url` | string | :x: | :x: | :white_check_mark: | The URL to the API documentation on the developer portal. | +| `api_endpoint_url` | string | :x: | :x: | :white_check_mark: | The URL to the API endpoint for the tool, if the tool has one. | +| `supported_parameters` | object | :x: | :x: | :white_check_mark: | The filter parameters that the tool supports. The object key is the parameter name, and the value is true/false. | +| `required_parameters` | object | :x: | :x: | :white_check_mark: | The required parameters for the tool. The object key is the parameter name, and the value is true/false. | +| `multiple_choice_parameters` | object | :x: | :x: | :white_check_mark: | The parameters that allow more than one selection. The object key is the parameter name, and the value is true/false. | +| `extra_parameters` | object | :x: | :x: | :white_check_mark: | The tool-specific parameters that are not part of the standard brandscape filters. | +| `export_formats` | object | :x: | :x: | :white_check_mark: | The export formats of the tool. The object key is the format name, and the value is true/false. Only available exports are listed. | +| `is_in_preview` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | If true, the tool is not released yet. You can see it because you have preview access. | +| `url` | string | :x: | :x: | :x: | The URL to the tool in The Fount. If you use `fields`, include `slug` and `group_id` to get this value. | +| `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this tool was first created. | +| `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this tool was last updated. | + +## Additional Filters + +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): + +- `favorited_by_me` - Set to `1` to only return the tools that you marked as favorites. ## Relationships & includes diff --git a/docs/metadata/years.md b/docs/metadata/years.md index 124c62b..d329133 100644 --- a/docs/metadata/years.md +++ b/docs/metadata/years.md @@ -30,7 +30,7 @@ Where `123` is the system ID of the year. |---------------------|---------|:-----------------------------------------:|:------------------:|:------------------:|-------------------------------------------------------| | `id` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The system ID. | | `year` | integer | :white_check_mark: (exact) | :white_check_mark: | :white_check_mark: | The year (name). | -| `has_ogilvy_impact` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | If the year should have Ogilvy Impact data available. | | +| `has_ogilvy_impact` | boolean | :white_check_mark: | :white_check_mark: | :white_check_mark: | If true, the year has Ogilvy Impact data. | | `created_at` | string | :x: | :white_check_mark: | :white_check_mark: | A datetime string when this year was first created. | | `updated_at` | string | ([updated since](../customizing/filters)) | :white_check_mark: | :white_check_mark: | A datetime string when this year was last updated. | diff --git a/docs/metrics/metric-groups.md b/docs/metrics/metric-groups.md index 5bee333..d0f1714 100644 --- a/docs/metrics/metric-groups.md +++ b/docs/metrics/metric-groups.md @@ -48,8 +48,8 @@ The API uses the slim relationship schema when the brand metric group is part of ## Additional Filters -For convenience, there are some additional filters for brand metric groups that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `public` - Set to `1` to only return public groups. - `private` - Set to `1` to only return private groups. diff --git a/docs/metrics/metrics.md b/docs/metrics/metrics.md index c184566..fa0a90b 100644 --- a/docs/metrics/metrics.md +++ b/docs/metrics/metrics.md @@ -58,8 +58,8 @@ The API uses the slim relationship schema when the brand metric is part of an in ## Additional Filters -For convenience, there are some additional filters for brand metrics that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `active` - Set to `1` to only return active metrics. - `inactive` - Set to `1` to only return inactive metrics. diff --git a/docs/pagination.md b/docs/pagination.md index 29828ad..c081593 100644 --- a/docs/pagination.md +++ b/docs/pagination.md @@ -28,7 +28,7 @@ The API list response has this structure: { ... } - // Here's the specific request data for the resource. + // The data for the resource is here. ], "links": { "first": "https://fount.wppbav.com/api/v2/brands?page=1", @@ -118,9 +118,9 @@ The API list response has this structure: } ], "path": "https://fount.wppbav.com/api/v2/brands", - "per_page": 15, - "to": 15, - "total": 2434 + "per_page": 25, + "to": 25, + "total": 4062 } } ``` diff --git a/docs/studies/categories.md b/docs/studies/categories.md index 981517c..5c41a71 100644 --- a/docs/studies/categories.md +++ b/docs/studies/categories.md @@ -67,8 +67,8 @@ also contains a `sector` object. ## Additional Filters -For convenience, there are some additional filters for categories that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `sectors` - A comma-separated list of sector IDs. The API filters the categories to only those in the given sectors. diff --git a/docs/studies/studies.md b/docs/studies/studies.md index 6308a55..b3ab90d 100644 --- a/docs/studies/studies.md +++ b/docs/studies/studies.md @@ -200,8 +200,8 @@ The category is always included. The following additional relationships are avai ## Additional filters -For convenience, there are some additional filters for studies that are not available in -the [default filters](../customizing/filters.md) or are part of the columns. These are: +These filters do not match a column, but you use them with the same `filter[name]=value` format as the +[default filters](../customizing/filters.md): - `study_types` - A comma-separated list of study type slugs: `syndicated` (BAV Standard), `custom` (Kaleidoscope and Consumer Eye), `snap` (SnapBAV) or `fused` (AO+BAV Fused). The API ignores unknown slugs. Use the `type` filter to filter diff --git a/docs/webhooks.md b/docs/webhooks.md index 447533d..e4fc415 100644 --- a/docs/webhooks.md +++ b/docs/webhooks.md @@ -159,7 +159,7 @@ To verify the webhook, calculate the signature from the request body with the we compare the calculated signature with the signature in the `BAV-Signature` header. We recommend that you use the raw request body content for the hash, because JSON parsing can change it. -:::warning Securing the webhook secret +:::warning Protect the webhook secret Always keep the webhook secret secure. Do not expose it in your frontend code or in public or private repositories. Do not hardcode it into your code. The secret is as sensitive as a password. From 94a9914b64267571764229e2904fc2f1c415b66c Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Mon, 26 Oct 2026 14:47:33 +0100 Subject: [PATCH 22/23] Use bavsupport@wpp.com, and remove unsent webhook events and unavailable endpoints Co-Authored-By: Claude Opus 5.5 --- blog/2023-02-12-version-2-0.md | 2 +- blog/2023-04-20-upgraded-brandscape-data.md | 2 +- blog/2023-05-19-new-tool-endpoints.md | 2 +- docs/audiences/export.md | 2 +- docs/authentication.md | 8 ++++---- docs/best-countries/raw-data.md | 5 ----- docs/embed/implementation.md | 4 ++-- docs/webhooks.md | 11 +---------- 8 files changed, 11 insertions(+), 25 deletions(-) diff --git a/blog/2023-02-12-version-2-0.md b/blog/2023-02-12-version-2-0.md index 2de339c..accf9d2 100644 --- a/blog/2023-02-12-version-2-0.md +++ b/blog/2023-02-12-version-2-0.md @@ -23,4 +23,4 @@ At a high-level, these are the changes that will affect you: - Ability to scope API keys to specific operations. If you are having problems with using the API, or if you have any questions or feedback, -please [do reach out to us](mailto:support@bernskiold.com). We are happy to help. \ No newline at end of file +please [do reach out to us](mailto:bavsupport@wpp.com). We are happy to help. \ No newline at end of file diff --git a/blog/2023-04-20-upgraded-brandscape-data.md b/blog/2023-04-20-upgraded-brandscape-data.md index 06c51ec..969da40 100644 --- a/blog/2023-04-20-upgraded-brandscape-data.md +++ b/blog/2023-04-20-upgraded-brandscape-data.md @@ -34,4 +34,4 @@ GET /api/v2/brandscape-data/?filter[sectors]=1 You can read more in the [Brandscape Data endpoint docs](/docs/2.x/brand-data/brandscape-data). If you are having problems with using the API, or if you have any questions or feedback, -please [do reach out to us](mailto:support@bernskiold.com). We are happy to help. +please [do reach out to us](mailto:bavsupport@wpp.com). We are happy to help. diff --git a/blog/2023-05-19-new-tool-endpoints.md b/blog/2023-05-19-new-tool-endpoints.md index b8e55c7..c41db3c 100644 --- a/blog/2023-05-19-new-tool-endpoints.md +++ b/blog/2023-05-19-new-tool-endpoints.md @@ -15,4 +15,4 @@ The new endpoints are available for most of the TurboPitch tools. If one that yo out to us, and we are happy to add it for you. If you are having problems with using the API, or if you have any questions or feedback, -please [do reach out to us](mailto:support@bernskiold.com). We are happy to help. +please [do reach out to us](mailto:bavsupport@wpp.com). We are happy to help. diff --git a/docs/audiences/export.md b/docs/audiences/export.md index d81c425..27cc770 100644 --- a/docs/audiences/export.md +++ b/docs/audiences/export.md @@ -61,7 +61,7 @@ Before you start with the Audience Export Integration, learn about: [Managing audiences](managing-audiences.md) for how to create and manage them. - The [Webhooks](../webhooks.md) and how to listen to audience export events. -When you start to plan how to use the Audience Export Integration, [contact us](mailto:support@bernskiold.com). We can +When you start to plan how to use the Audience Export Integration, [contact us](mailto:bavsupport@wpp.com). We can then plan the integration tasks on The Fount side that make your application visible as an export destination. We want to make the integration as smooth as possible for you and your users. diff --git a/docs/authentication.md b/docs/authentication.md index d17f604..8ebcdc2 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -98,7 +98,7 @@ An application always has at least one owner. Only an owner can give, change or ### Application access When the application calls the API as itself, it has its own access to data. This access is separate from the access -of its members. A new application starts with only basic access. [Contact us](mailto:support@bernskiold.com) to get the +of its members. A new application starts with only basic access. [Contact us](mailto:bavsupport@wpp.com) to get the access that it needs. ### Application API keys @@ -306,7 +306,7 @@ application, for example for your office or VPN network. From all other addresse usual. These trusted IP addresses are separate from the [allowed API IP addresses](#restricting-where-api-calls-come-from). -[Contact us](mailto:support@bernskiold.com) if you want us to set up your application as trusted. +[Contact us](mailto:bavsupport@wpp.com) if you want us to set up your application as trusted. ### Client credentials flow @@ -359,7 +359,7 @@ curl https://fount.wppbav.com/api/v2/brands \ All of these conditions must be true: - **The application is trusted and approved to act on behalf of users.** We set this. - [Contact us](mailto:support@bernskiold.com) if your application needs it. + [Contact us](mailto:bavsupport@wpp.com) if your application needs it. - **The token belongs to the application.** Use an [application API key](#application-api-keys) or a [client credentials token](#client-credentials-flow). A token that a user issued to your application through the authorization code flow cannot act as another user. A personal access token also cannot act as another user. @@ -468,4 +468,4 @@ Some scopes are not for general use, and you cannot assign them to yourself. The application [act on behalf of users](#acting-on-behalf-of-users). It is available only on the API keys and client credentials clients of an application. The application must first be approved to act on behalf of users. -[Contact us](mailto:support@bernskiold.com) if you think that your integration needs it. +[Contact us](mailto:bavsupport@wpp.com) if you think that your integration needs it. diff --git a/docs/best-countries/raw-data.md b/docs/best-countries/raw-data.md index f7b4b0d..2442113 100644 --- a/docs/best-countries/raw-data.md +++ b/docs/best-countries/raw-data.md @@ -24,11 +24,6 @@ GET /api/v2/best-countries/countries/raw/2024 If the endpoint cannot find the year, or the year has no Best Countries data, the endpoint returns a `404`. -:::note Cities and Origin Index -The equivalent raw data endpoints for cities (`/api/v2/best-countries/cities/raw/{year}`) and the Origin Index -(`/api/v2/best-countries/origin-index/raw/{year}`) are not available and return a `400` response. -::: - ## Schema The response is [paginated](../pagination.md). Each row contains: diff --git a/docs/embed/implementation.md b/docs/embed/implementation.md index 15d81da..59622a9 100644 --- a/docs/embed/implementation.md +++ b/docs/embed/implementation.md @@ -4,14 +4,14 @@ To bypass the Okta login screen in the embed, you can pre-authenticate your user. There are some dependencies: -- The API key that you use must have a specific set of permissions. Contact support@bernskiold.com to get these +- The API key that you use must have a specific set of permissions. Contact bavsupport@wpp.com to get these permissions. - Your application must use Okta. - You can pass an email address, first name and last name of your user. :::note Access approval To use the embed integration through our auto-login flow and bypass a user connection approval screen, you must -request approval. Contact support@bernskiold.com. +request approval. Contact bavsupport@wpp.com. ::: :::tip Authentication diff --git a/docs/webhooks.md b/docs/webhooks.md index e4fc415..73695e7 100644 --- a/docs/webhooks.md +++ b/docs/webhooks.md @@ -25,15 +25,6 @@ created, updated or deleted in BAV: | `collections_data_change` | `Collection` | A [collection](brands/collections.md) was created, updated or deleted. | | `studies_data_change` | `Study` | A [study](studies/studies.md) was created, updated or deleted. | -You can also add these events to a webhook, but BAV does not send them at this time: - -| Event | Description | -|---------------------------------------|------------------------------------------------| -| `audience_origin_metrics_data_change` | An Audience Origin metric was changed. | -| `tools_data_change` | A tool was changed. | -| `tool_queries_data_change` | A tool query was changed. | -| `audience_export_italy_creator` | An audience was exported to Italy Creator. | - ## How does a webhook work? A webhook is an HTTP POST request to a URL that you specify. BAV triggers the request automatically when data changes @@ -73,7 +64,7 @@ your endpoint before the event occurs in BAV. ## Creating the webhook on The Fount At this time, you cannot create webhooks on The Fount yourself. Contact us -at [support@bernskiold.com](mailto:support@bernskiold.com). We will then add the webhook to the system for you. We will +at [bavsupport@wpp.com](mailto:bavsupport@wpp.com). We will then add the webhook to the system for you. We will also give you the secret key that you need to verify that the webhook requests are authentic. You are welcome to contact us when you start to plan your integration. We can help you with the first steps. From d3a7168c3dc83c06a181e354d97d4b34c4e8536e Mon Sep 17 00:00:00 2001 From: Erik Bernskiold Date: Mon, 26 Oct 2026 14:51:11 +0100 Subject: [PATCH 23/23] Sync package-lock.json with package.json so npm ci passes Co-Authored-By: Claude Opus 5.5 --- package-lock.json | 286 ++++++++++++++-------------------------------- 1 file changed, 88 insertions(+), 198 deletions(-) diff --git a/package-lock.json b/package-lock.json index 8ba27bc..87bff69 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2128,19 +2128,6 @@ "postcss": "^8.4" } }, - "node_modules/@csstools/postcss-cascade-layers/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/@csstools/postcss-color-function": { "version": "4.0.10", "resolved": "https://registry.npmjs.org/@csstools/postcss-color-function/-/postcss-color-function-4.0.10.tgz", @@ -2469,19 +2456,6 @@ "postcss": "^8.4" } }, - "node_modules/@csstools/postcss-is-pseudo-class/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/@csstools/postcss-light-dark-function": { "version": "2.0.9", "resolved": "https://registry.npmjs.org/@csstools/postcss-light-dark-function/-/postcss-light-dark-function-2.0.9.tgz", @@ -2868,19 +2842,6 @@ "postcss": "^8.4" } }, - "node_modules/@csstools/postcss-scope-pseudo-class/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/@csstools/postcss-sign-functions": { "version": "1.1.4", "resolved": "https://registry.npmjs.org/@csstools/postcss-sign-functions/-/postcss-sign-functions-1.1.4.tgz", @@ -6432,19 +6393,6 @@ "postcss": "^8.4" } }, - "node_modules/css-blank-pseudo/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/css-declaration-sorter": { "version": "7.2.0", "resolved": "https://registry.npmjs.org/css-declaration-sorter/-/css-declaration-sorter-7.2.0.tgz", @@ -6484,19 +6432,6 @@ "postcss": "^8.4" } }, - "node_modules/css-has-pseudo/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/css-loader": { "version": "6.11.0", "resolved": "https://registry.npmjs.org/css-loader/-/css-loader-6.11.0.tgz", @@ -12832,19 +12767,6 @@ "postcss": "^8.4" } }, - "node_modules/postcss-attribute-case-insensitive/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/postcss-calc": { "version": "9.0.1", "resolved": "https://registry.npmjs.org/postcss-calc/-/postcss-calc-9.0.1.tgz", @@ -12861,6 +12783,19 @@ "postcss": "^8.2.2" } }, + "node_modules/postcss-calc/node_modules/postcss-selector-parser": { + "version": "6.1.5", + "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.1.5.tgz", + "integrity": "sha512-TEHFzb5KRDKaOgJ4TYE+0jyJtFbjLvkdVOu0fZ2b6MTWzoqZd4Le+61aEppWkvTlYePgOX4ATL1wsAIPMLTw6Q==", + "license": "MIT", + "dependencies": { + "cssesc": "^3.0.0", + "util-deprecate": "^1.0.2" + }, + "engines": { + "node": ">=4" + } + }, "node_modules/postcss-clamp": { "version": "4.1.0", "resolved": "https://registry.npmjs.org/postcss-clamp/-/postcss-clamp-4.1.0.tgz", @@ -13076,19 +13011,6 @@ "postcss": "^8.4" } }, - "node_modules/postcss-custom-selectors/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/postcss-dir-pseudo-class": { "version": "9.0.1", "resolved": "https://registry.npmjs.org/postcss-dir-pseudo-class/-/postcss-dir-pseudo-class-9.0.1.tgz", @@ -13114,19 +13036,6 @@ "postcss": "^8.4" } }, - "node_modules/postcss-dir-pseudo-class/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/postcss-discard-comments": { "version": "6.0.2", "resolved": "https://registry.npmjs.org/postcss-discard-comments/-/postcss-discard-comments-6.0.2.tgz", @@ -13190,6 +13099,19 @@ "postcss": "^8.4.31" } }, + "node_modules/postcss-discard-unused/node_modules/postcss-selector-parser": { + "version": "6.1.5", + "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.1.5.tgz", + "integrity": "sha512-TEHFzb5KRDKaOgJ4TYE+0jyJtFbjLvkdVOu0fZ2b6MTWzoqZd4Le+61aEppWkvTlYePgOX4ATL1wsAIPMLTw6Q==", + "license": "MIT", + "dependencies": { + "cssesc": "^3.0.0", + "util-deprecate": "^1.0.2" + }, + "engines": { + "node": ">=4" + } + }, "node_modules/postcss-double-position-gradients": { "version": "6.0.2", "resolved": "https://registry.npmjs.org/postcss-double-position-gradients/-/postcss-double-position-gradients-6.0.2.tgz", @@ -13242,19 +13164,6 @@ "postcss": "^8.4" } }, - "node_modules/postcss-focus-visible/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/postcss-focus-within": { "version": "9.0.1", "resolved": "https://registry.npmjs.org/postcss-focus-within/-/postcss-focus-within-9.0.1.tgz", @@ -13280,19 +13189,6 @@ "postcss": "^8.4" } }, - "node_modules/postcss-focus-within/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/postcss-font-variant": { "version": "5.0.0", "resolved": "https://registry.npmjs.org/postcss-font-variant/-/postcss-font-variant-5.0.0.tgz", @@ -13476,6 +13372,19 @@ "postcss": "^8.4.31" } }, + "node_modules/postcss-merge-rules/node_modules/postcss-selector-parser": { + "version": "6.1.5", + "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.1.5.tgz", + "integrity": "sha512-TEHFzb5KRDKaOgJ4TYE+0jyJtFbjLvkdVOu0fZ2b6MTWzoqZd4Le+61aEppWkvTlYePgOX4ATL1wsAIPMLTw6Q==", + "license": "MIT", + "dependencies": { + "cssesc": "^3.0.0", + "util-deprecate": "^1.0.2" + }, + "engines": { + "node": ">=4" + } + }, "node_modules/postcss-minify-font-values": { "version": "6.1.0", "resolved": "https://registry.npmjs.org/postcss-minify-font-values/-/postcss-minify-font-values-6.1.0.tgz", @@ -13540,6 +13449,19 @@ "postcss": "^8.4.31" } }, + "node_modules/postcss-minify-selectors/node_modules/postcss-selector-parser": { + "version": "6.1.5", + "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.1.5.tgz", + "integrity": "sha512-TEHFzb5KRDKaOgJ4TYE+0jyJtFbjLvkdVOu0fZ2b6MTWzoqZd4Le+61aEppWkvTlYePgOX4ATL1wsAIPMLTw6Q==", + "license": "MIT", + "dependencies": { + "cssesc": "^3.0.0", + "util-deprecate": "^1.0.2" + }, + "engines": { + "node": ">=4" + } + }, "node_modules/postcss-modules-extract-imports": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/postcss-modules-extract-imports/-/postcss-modules-extract-imports-3.1.0.tgz", @@ -13569,19 +13491,6 @@ "postcss": "^8.1.0" } }, - "node_modules/postcss-modules-local-by-default/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/postcss-modules-scope": { "version": "3.2.1", "resolved": "https://registry.npmjs.org/postcss-modules-scope/-/postcss-modules-scope-3.2.1.tgz", @@ -13597,19 +13506,6 @@ "postcss": "^8.1.0" } }, - "node_modules/postcss-modules-scope/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/postcss-modules-values": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/postcss-modules-values/-/postcss-modules-values-4.0.0.tgz", @@ -13652,19 +13548,6 @@ "postcss": "^8.4" } }, - "node_modules/postcss-nesting/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/postcss-normalize-charset": { "version": "6.0.2", "resolved": "https://registry.npmjs.org/postcss-normalize-charset/-/postcss-normalize-charset-6.0.2.tgz", @@ -14008,19 +13891,6 @@ "postcss": "^8.4" } }, - "node_modules/postcss-pseudo-class-any-link/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/postcss-reduce-idents": { "version": "6.0.3", "resolved": "https://registry.npmjs.org/postcss-reduce-idents/-/postcss-reduce-idents-6.0.3.tgz", @@ -14101,23 +13971,10 @@ "postcss": "^8.4" } }, - "node_modules/postcss-selector-not/node_modules/postcss-selector-parser": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", - "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/postcss-selector-parser": { - "version": "6.1.2", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.1.2.tgz", - "integrity": "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg==", + "version": "7.1.7", + "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.7.tgz", + "integrity": "sha512-wWBro/7hJ40ye6TPiXkUQoXKCw23xSsjriUvqd7Uls9Sso3oLiON1flc18cCdnjgCRXw4fBVqUJJeOdDTh3P3g==", "license": "MIT", "dependencies": { "cssesc": "^3.0.0", @@ -14173,6 +14030,19 @@ "postcss": "^8.4.31" } }, + "node_modules/postcss-unique-selectors/node_modules/postcss-selector-parser": { + "version": "6.1.5", + "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.1.5.tgz", + "integrity": "sha512-TEHFzb5KRDKaOgJ4TYE+0jyJtFbjLvkdVOu0fZ2b6MTWzoqZd4Le+61aEppWkvTlYePgOX4ATL1wsAIPMLTw6Q==", + "license": "MIT", + "dependencies": { + "cssesc": "^3.0.0", + "util-deprecate": "^1.0.2" + }, + "engines": { + "node": ">=4" + } + }, "node_modules/postcss-value-parser": { "version": "4.2.0", "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz", @@ -15278,6 +15148,13 @@ "url": "https://opencollective.com/webpack" } }, + "node_modules/search-insights": { + "version": "2.17.3", + "resolved": "https://registry.npmjs.org/search-insights/-/search-insights-2.17.3.tgz", + "integrity": "sha512-RQPdCYTa8A68uM2jwxoY842xDhvx3E5LFL1LxvxCNMev4o5mLuokczhzjAgGwUZBAmOKZknArSxLKmXtIi2AxQ==", + "license": "MIT", + "peer": true + }, "node_modules/section-matter": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/section-matter/-/section-matter-1.0.0.tgz", @@ -16032,6 +15909,19 @@ "postcss": "^8.4.31" } }, + "node_modules/stylehacks/node_modules/postcss-selector-parser": { + "version": "6.1.5", + "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.1.5.tgz", + "integrity": "sha512-TEHFzb5KRDKaOgJ4TYE+0jyJtFbjLvkdVOu0fZ2b6MTWzoqZd4Le+61aEppWkvTlYePgOX4ATL1wsAIPMLTw6Q==", + "license": "MIT", + "dependencies": { + "cssesc": "^3.0.0", + "util-deprecate": "^1.0.2" + }, + "engines": { + "node": ">=4" + } + }, "node_modules/supports-color": { "version": "7.2.0", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",