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/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. diff --git a/docs/ai/agents.md b/docs/ai/agents.md index 5d344e0..b3b39b0 100644 --- a/docs/ai/agents.md +++ b/docs/ai/agents.md @@ -4,21 +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 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 2443522..37347c6 100644 --- a/docs/ai/intro.md +++ b/docs/ai/intro.md @@ -4,29 +4,28 @@ 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. [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 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/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..b87699a 100644 --- a/docs/ai/mcp/access-authorization.md +++ b/docs/ai/mcp/access-authorization.md @@ -6,34 +6,99 @@ 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. +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 + +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 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. -All our MCP servers work with OAuth 2.0 using the -standard [MCP authorization flow](https://modelcontextprotocol.io/docs/tutorials/security/authorization). +### OAuth -We highly recommend OAuth as the authorization mechanism as it allows you to act as the user and access data on their +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 do this flow for you automatically. Thus, you only need to give the server URL. + +We strongly recommend OAuth as the authorization mechanism. With OAuth, you can act as the user and get 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. 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 with the registration endpoint. Thus, you do not + need to create an OAuth client before you start. -If you are using an API key, just pass it as a Bearer token in the Authorization header when making requests to the MCP +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 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 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``` +``` +Authorization: Bearer YOUR_API_KEY +``` + +### Applications + +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. Your application then acts on + their behalf with their permissions. +- **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. + +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 +X-Act-As-User: jane.doe@wpp.com +``` + +:::note +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** 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. -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 +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 2905778..1d643de 100644 --- a/docs/ai/mcp/bav.md +++ b/docs/ai/mcp/bav.md @@ -4,76 +4,245 @@ 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 both research data on brands, as well as metadata around coverage, imagery, and -other assets. +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 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, 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. -## Available Tools - -The BAV MCP server provides two sets of tools: - -- **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. - -**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. +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. -### 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 +## Available Tools -- `get-brands` -- `get-markets` -- `get-sectors` -- `get-categories` -- `get-audiences` +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:** Get the BAV brand data, one data model for each tool. +- **Collection tools:** Create, update and share brand collections. +- **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:** Show interactive charts in clients that support [MCP Apps](./mcp-apps.md). + +### Which tools you will see + +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 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. + +### 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 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. 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). 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` + +`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. 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. 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 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` | 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. | +| `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 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 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 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` 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). + +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. 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. It sets the metrics that the tool uses to rank the brands. + +#### 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 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 + +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 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. 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 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 + +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 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 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 (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 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. 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. | +| `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`. | -### Tool Parameters +All AURA tools require access to AURA. + +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 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 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. | -Each tool accepts a set of parameters that your agent will try to extract from the user input. This includes: +The media performance tools are available only to users who have access to media performance data for one or more +brands. -- Brands -- Countries (with a note to prefer using ISO 3166-1 alpha-2 codes) -- Years -- Audiences +### Display Tools -Behind the scenes the BAV systems will automatically handle fallbacks and make assumptions should a parameter not be -provided. +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 | +|-------------------------------------|----------------------------------------------------------------------|------------| +| `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 -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 b7d13ba..479819c 100644 --- a/docs/ai/mcp/best-countries.md +++ b/docs/ai/mcp/best-countries.md @@ -4,66 +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 the rich brand data collected -by BAV 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 supports both SSE (Server-Sent Events) and Streamable HTTP. -To connect to the Best Countries MCP server, you need to use the following URL: +Our remote MCP server uses the Streamable HTTP transport. +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 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 BAV 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. -**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 -defined in the MCP specification. This will return the full tool definitions including parameters and descriptions. +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. 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 -- `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 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` | 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 -- `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` | 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 -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. Your agent tries to find the values in 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. 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 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 new file mode 100644 index 0000000..7f74eb9 --- /dev/null +++ b/docs/ai/mcp/concepts.md @@ -0,0 +1,121 @@ +--- +sidebar_label: Concepts for Agents +--- + +# Concepts for Agents + +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, 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. + +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. 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. 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. | + +Thus, the brand data tools select data by **study ID**, not by market and year. The usual procedure is: + +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 +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. + +Also remember these points: + +- 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 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). 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. + +Give this guidance to your agent for ranks: + +- 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**. 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 + +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** - 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 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 that it tries again after a short wait and does not end the task. + +## Brand names and variations + +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 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. + +The response does not include empty fields. Thus, some rows do not have all of these fields. + +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 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`. + +Send `studies` when possible. Then the agent sees only the items that its studies measured. + +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 new file mode 100644 index 0000000..af5af6b --- /dev/null +++ b/docs/ai/mcp/connecting-clients.md @@ -0,0 +1,156 @@ +--- +sidebar_label: Connecting Clients +--- + +# Connecting Clients + +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 +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 + +| 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 will tell you about this change a sufficient time before +it occurs, so that you can update your applications. +::: + +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 through Creative Studio and its agent builder. + +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 start to use the BAV MCP servers in WPP Open, do these steps: + +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. + +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 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 + +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 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, 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: + +```bash +claude mcp add --transport http wpp-bav https://mcp-beta.wppbav.com/v1/bav +``` + +Then run `/mcp` in Claude Code to sign in and authorize the server. + +## ChatGPT + +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). 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`. 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**. +7. Sign in with your WPP account and authorize access. +8. Select **Add to agent**. + +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. + +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. This file can be 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 tells you to sign in and authorize it. The tools are then available to Copilot in +agent mode. + +## Other clients + +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 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 8a52750..225d608 100644 --- a/docs/ai/mcp/financial-data.md +++ b/docs/ai/mcp/financial-data.md @@ -4,47 +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. +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 supports both SSE (Server-Sent Events) and Streamable HTTP. -To connect to the Financial Data MCP server, you need to use the following URL: +Our remote MCP server uses the Streamable HTTP transport. +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 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. +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-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-11-25/server/tools#listing-tools) mechanism from +the MCP specification. This mechanism returns the full tool definitions, with 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, 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 parameter, including the exchange suffix where -applicable (e.g., `AAPL.US` for Apple Inc. on NASDAQ). +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. + +`get-stock-prices` also accepts two optional parameters to limit the date range: + +- `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 + +`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. + +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 b7c8943..b318033 100644 --- a/docs/ai/mcp/intro.md +++ b/docs/ai/mcp/intro.md @@ -1,38 +1,54 @@ +--- +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 Control Protocol) is a standard protocol 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 | +|-------------------------------------------------|-----------------------------------------------|-------------------------------------------------------------------| +| [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 will tell you about this change a sufficient time before +it occurs, so that you can update your applications. +::: + +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 -- [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 +- **[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? -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 new file mode 100644 index 0000000..1cec7c7 --- /dev/null +++ b/docs/ai/mcp/market-share.md @@ -0,0 +1,117 @@ +--- +sidebar_label: Market Share Server +--- + +# Market Share MCP Server + +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, use this URL: + +``` +https://mcp-beta.wppbav.com/v1/market-share +``` + +:::note +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, 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. 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 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 has two sets of tools: + +- **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 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. 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. 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. 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. A data type is what a share row measures, such as retail value or retail volume. | `industries` (Euromonitor industry IDs), `categories` (Euromonitor category IDs) | + +Remember these points when you use the catalogs: + +- 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 + +| 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 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. 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. 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, 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). + +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 +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 new file mode 100644 index 0000000..549ca5c --- /dev/null +++ b/docs/ai/mcp/mcp-apps.md @@ -0,0 +1,81 @@ +--- +sidebar_label: MCP Apps (Charts) +--- + +# MCP Apps + +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. 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 do not need to get the resources yourself. A client with MCP Apps support does this automatically. + +## Client support + +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 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 + +| 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 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 have more parameters: + +- `display-imagery-chart` + - `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 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`. + +### 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. + +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 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) | +|------------------------------------|----------------------------------------------------------------------| +| `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..8d174a3 100644 --- a/docs/ai/mcp/social.md +++ b/docs/ai/mcp/social.md @@ -1,23 +1,39 @@ +--- +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. +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. 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, and optional search terms -- **YouTube Intelligence**: Search YouTube videos and channels from a curated dataset with filtering by language, country, categories, and engagement metrics -- **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: -- **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 +The server puts data in a hierarchical structure: + +- **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 --- @@ -32,24 +48,75 @@ 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 + +All parameters that this page shows as arrays also accept a string. This is for clients that cannot send real JSON +arrays: + +- 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. + +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 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**: 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 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 for each related entity +- `[OPINION_QUESTIONS]`, `[SCENARIO_QUESTIONS]`: one `question → answer` line for each question + +If the tool does not find an applicable profile, 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). +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) -- `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 -- `limit` (int, optional): Results per search term (default: 3, max: 5) +- `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). 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` (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 @@ -68,8 +135,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 +147,24 @@ 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 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): 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 -- `limit` (int, optional): Results per search term (default: 8, max: 20) +- `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 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 @@ -94,21 +172,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 +210,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 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): 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 -- `limit` (int, optional): Results per search term (default: 8, max: 20) +- `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"]`. 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 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 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 @@ -133,22 +242,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 +268,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 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) +- `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 country: United States, United Kingdom, Canada -- `limit` (int, optional): Results per search term (default: 10, max: 50) +- `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`. The response +does not include fields with no value. **Example with search terms**: ```json @@ -180,6 +296,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 +326,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 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 -- `limit` (int, optional): Results per search term (default: 10, max: 50) +- `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 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 @@ -210,7 +355,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 +374,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. 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 (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) +- `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. 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`, +`created_at`, `top_country_list`, `audience_ages`, and `trending_history`. **Example**: ```json @@ -252,13 +431,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 } } @@ -266,12 +446,12 @@ Get trending TikTok hashtags. Can optionally filter by search terms or get top h ### 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` +- `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**: @@ -279,17 +459,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 -**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 +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. 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 @@ -317,21 +500,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, 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) -- `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 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 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): Sort order when no search terms provided. Options: "size" (view count - most viewed) or "recency" (publish date - newest videos). Only valid without search terms -- `limit` (int, optional): Results per search term (default: 10, max: 50) +- `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 +`channel_subscribers`. **Example with search terms**: ```json @@ -374,20 +564,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, 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) -- `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 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 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): 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 -- `limit` (int, optional): Results per search term (default: 10, max: 50) +- `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`. **Example with search terms**: ```json @@ -429,66 +625,236 @@ Search YouTube channels from the Brand Mentality curated YouTube dataset. } ``` +### get_youtube_creator_insights + +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. 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` | 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 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"`). 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 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 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 +{ + "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 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 that the creator is eligible for) + +**Reading trends**: +- 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` 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 -All search tools return results with clear distinction between total matches and sample results: +### Output Format + +All tools return their result as one text block: + +- **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` use 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 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` -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 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: + +- `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 -**Social Media Posts**, **News Articles**, **YouTube Videos**, and **YouTube Channels** return full aggregate statistics per search term: +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`, `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`. The tool calculates these for the returned rows only, not for the full dataset + +How to read these statistics: + +- **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`. -**News Moments**, **Social Media Narratives**, and **Trends** return `total_matches` count per search term. +### Timelines + +`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 +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`): 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 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 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 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 (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 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 to all tools: + +- 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 all tools) -- 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"]` -- **Without search terms**: Tools return results sorted by a logical default, customizable with `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) @@ -499,13 +865,26 @@ 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 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 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. 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. diff --git a/docs/audience-origin/frequencies.md b/docs/audience-origin/frequencies.md new file mode 100644 index 0000000..e6a5361 --- /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 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 through the API, use the list endpoint: + +```http request +GET /api/v2/audience-origin/frequencies +``` + +## Get a frequency + +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 +``` + +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 API uses the slim relationship schema when the frequency is 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 + +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. + +## 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 +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..e46d7fa --- /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 has two parts: + +- **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). + +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. 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 +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 + +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 new file mode 100644 index 0000000..46c3634 --- /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. + +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 through the API, use the list endpoint: + +```http request +GET /api/v2/audience-origin/metric-groups +``` + +## Get an Audience Origin metric group + +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 +``` + +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 API uses the slim relationship schema when the metric group is 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 you include it. | + +## 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): + +- `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, 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: + +- `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..81b1d82 --- /dev/null +++ b/docs/audience-origin/metrics.md @@ -0,0 +1,102 @@ +# 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). + +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 through the API, use the list endpoint: + +```http request +GET /api/v2/audience-origin/metrics +``` + +## Get an Audience Origin metric + +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 +``` + +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 API uses the slim relationship schema when the metric is 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 + +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. +- `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, the response does not include relationships. 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..cab6dda --- /dev/null +++ b/docs/audience-origin/query.md @@ -0,0 +1,138 @@ +--- +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 endpoint returns the data for an [audience](../audiences/audiences.md). The default audience is All +Adults. + +## Creating a query + +Send the query 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 + } +} +``` + +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 + +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. 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`. 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 +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. 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. | + +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 + 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..cbadd69 --- /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 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 through the API, use the list endpoint: + +```http request +GET /api/v2/audience-origin/touchpoints +``` + +## Get a touchpoint + +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 +``` + +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 API uses the slim relationship schema when the touchpoint is 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 + +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. + +## 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 +are available: + +- `metrics` - The [metrics](metrics.md) that measure this touchpoint. diff --git a/docs/audiences/audience-groups.md b/docs/audiences/audience-groups.md index 3351c30..199d312 100644 --- a/docs/audiences/audience-groups.md +++ b/docs/audiences/audience-groups.md @@ -2,21 +2,21 @@ ## What are audience groups? -[Audiences](audiences.md) are cuts of respondents that can be used ta 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 ``` -## 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. +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 @@ -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 @@ -34,11 +36,11 @@ Where `123` is the system ID of the audience group. | `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 -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 | |--------|---------|-----------------------------------------| @@ -47,12 +49,13 @@ 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 -the [includes section](../customizing/includes) for more information on how this works. The following relationships +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: -- `audiences` - The [audiences](audiences.md) that belong to this audience group. +- `audiences` - The [audiences](audiences.md) that belong to this audience group, with the + [audience relationship schema](audiences.md#relationship-response-schema). ## 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 94d038c..1a39672 100644 --- a/docs/audiences/audiences.md +++ b/docs/audiences/audiences.md @@ -1,30 +1,40 @@ # 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. 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. 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 audiences only accessible by the current user. +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 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. +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 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 + +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: +To list all of the audiences and browse them through the API, use the list endpoint: ```http request GET /api/v2/audiences @@ -32,70 +42,129 @@ 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 ``` -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 +:::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. ::: +## Get the studies for an audience + +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 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. The API calculates it when you deploy the audience. `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 (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`, 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 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. +`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. +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_public` | boolean | Whether this audience is publicly available to everyone (true) or just the current user (false). | +| `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. | -## Additional Filters +### Definition Schema -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: +The `definitions` include returns a list of definitions. You cannot deploy an audience without definitions. -- `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. -- `groups` - A comma-separated list of audience group IDs. This will only return audiences that belong to the +| 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 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. | + +See [Managing audiences](managing-audiences.md) for the full segment and metric schemas. + +## 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): + +- `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. 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 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, 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. +- `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..27cc770 100644 --- a/docs/audiences/export.md +++ b/docs/audiences/export.md @@ -4,83 +4,101 @@ 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 Honeycomb studies. 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. + +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 [Audiences API](audiences.md) and how to use it to create and manage audiences. +- 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: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 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 +### 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 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 { @@ -91,7 +109,7 @@ see 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": { @@ -115,20 +133,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 { @@ -139,7 +155,7 @@ see 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": { @@ -163,17 +179,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 Italy Audience Creator is its primary user. GroupM in Italy uses this tool. :::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 { @@ -184,7 +200,7 @@ see 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": { @@ -206,4 +222,53 @@ see the [Audience API schema](audiences.md). "810_2x_4" ] } -``` \ No newline at end of file +``` + +## Fetching respondents from the API + +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 + +```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. The response does not include +respondents without an Audience Origin ID. + +### 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. The response +does not include respondents without a progressive number. + +### 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`), for the related endpoint. This permission requires specific approval. + +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 + +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/audiences/managing-audiences.md b/docs/audiences/managing-audiences.md new file mode 100644 index 0000000..969d5cf --- /dev/null +++ b/docs/audiences/managing-audiences.md @@ -0,0 +1,400 @@ +--- +sidebar_label: Managing Audiences +--- + +# Managing Audiences + +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 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`). 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` + requires any of them). The `between_segments_operator` decides how the segment combines with the segment before it. + 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. 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. + +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 + +To read audiences, segments and segment metrics, you need the `bav:shared-resources` scope, the same as for the other +[Audiences](audiences.md) endpoints. + +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. + +The usual audience permissions also apply: + +- 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 + +To create an audience, send a `POST` request to the audiences endpoint: + +```http request +POST /api/v2/audiences +``` + +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 +{ + "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). The response includes the +definitions, segments and metrics of the audience. + +### 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 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. 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: + +| Key | Type | Required | Description | +|-----------------------|---------|:------------------:|-------------------------------------------------------------------------------------------------------------------------------------| +| `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. | +| `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 + +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. +- You cannot set `brands` on an Audience Origin metric. + +## Update an audience + +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 +``` + +Where `123` is the system ID 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). The response includes the definitions, segments, metrics, +user and group of the audience. + +## 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 + +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 +``` + +### 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 can create the metrics of the segment +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 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 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. + +### Update a segment + +```http request +PUT /api/v2/audiences/123/segments/456 +``` + +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 + +```http request +DELETE /api/v2/audiences/123/segments/456 +``` + +When you delete a segment, the API 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.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: + +- `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 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. 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 +You cannot deploy an audience if one of its segment metrics has no selected values. +::: + +### Update a segment metric + +```http request +PUT /api/v2/audiences/123/segments/456/metrics/789 +``` + +The request accepts the same fields as the create request. + +### 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 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. | +| `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 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 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 + +When your audience has a definition, deploy it to build its data: + +```http request +GET /api/v2/audiences/123/deploy +``` + +Where `123` is the system ID of the audience. + +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: + +```json +{ + "data": { + "message": "The audience has been deployed." + } +} +``` + +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. + +```json +{ + "data": { + "message": "The audience has no definitions and cannot be deployed." + } +} +``` diff --git a/docs/authentication.md b/docs/authentication.md index e96538a..8ebcdc2 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -1,57 +1,471 @@ # 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. Send the token in the +`Authorization` header with the `Bearer` scheme: + +```bash +curl https://fount.wppbav.com/api/v2/brands \ + -H "Accept: application/json" \ + -H "Authorization: Bearer YOUR_TOKEN" +``` + +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 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. +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. ::: -## 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 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 method to start with. If you build something that other people will use, create +an [application](#applications) instead. + +:::tip We recommend OAuth +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. +::: + +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. 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. + +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 that you have access to. See [scopes](#scopes). + +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: -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). +- **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. -When using a personal access token to authenticate to the API, you should use the `Bearer` authentication scheme. For -example: +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 -H "Authorization: Bearer TOKEN" +curl https://fount.wppbav.com/api/v2/brands \ + -H "Accept: application/json" \ + -H "Authorization: Bearer 1|AbCdEfGhIjKlMnOpQrStUvWxYz0123456789" ``` -## Application Access +## Applications -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. +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: -This flow is currently in beta. [Contact us](mailto:support@bernskiold.com) for more information. +- 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, after we approve it for this. -:::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: +### Members and roles -- 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. +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: -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. +| 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. | + +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. This access is separate from the access +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 + +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. 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 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) 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 \ + -H "Accept: application/json" \ + -H "Authorization: Bearer 2|ZyXwVuTsRqPoNmLkJiHgFeDcBa9876543210" +``` + +:::note Service accounts +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 + +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. 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 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 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 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 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 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` | 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 the available scopes. The authorization code +flow ignores the `*` scope. + +### Authorization code flow + +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.** + +``` +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 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 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 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. You can use it only one time. + +**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 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 works only 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 +} +``` + +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. 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:bavsupport@wpp.com) if you want us to set up your application as trusted. + +### Client credentials flow + +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 \ + -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. 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 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. 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 \ + -H "Accept: application/json" \ + -H "Authorization: Bearer 2|ZyXwVuTsRqPoNmLkJiHgFeDcBa9876543210" \ + -H "X-Act-As-User: jane.doe@example.com" +``` + +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: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. +- **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, you get a `422` error. + +The Fount records this activity against the user. The record also shows that your application made the request. + +## 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. Does not block requests. | Us | + +## Errors + +The API always returns authentication errors as JSON with a `message`, even if you do not 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 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 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` 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 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: + +```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. +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 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 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, 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 (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 | 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 does not require authentication or a scope. + +### Scopes and permissions + +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. 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. -Generally each endpoint has its own scope. For example to list all brands using the `/brands` endpoint, you will need -the `Brands: Read` scope. +### System scopes -Scopes for your API keys and applications are managed from -you [profile settings page in The Fount](https://fount.wppbav.com/profile?tab=api). +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. -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:bavsupport@wpp.com) if you think that your integration needs it. diff --git a/docs/best-countries/country-data.md b/docs/best-countries/country-data.md index dc8fde7..4d79a1a 100644 --- a/docs/best-countries/country-data.md +++ b/docs/best-countries/country-data.md @@ -5,28 +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 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. 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/{yearNumber}/{dataType}/{scoreType} +GET /api/v2/best-countries/countries/{year}/{dataType}/{scoreType} ``` -For example, getting the factor ranks for 2024 would look like this: +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, to get the factor ranks for 2024, send this request: ```http GET /api/v2/best-countries/countries/2024/factors/ranks @@ -34,23 +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. 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 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: +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 @@ -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 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 9ee569f..d2fe78e 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? + +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 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). + +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 through the API, use the list endpoint: + +```http request +GET /api/v2/best-countries-factors +``` + +## Get a best countries factor + +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 +``` + +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. 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. 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 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, 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 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 94a2e62..3437792 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 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 through the API, use the list endpoint: + +```http request +GET /api/v2/best-countries-metric-groups +``` + +## Get a best countries metric group + +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 +``` + +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. The +endpoint returns them 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. 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. | + +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 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, 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 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..9cad79c 100644 --- a/docs/best-countries/metrics.md +++ b/docs/best-countries/metrics.md @@ -6,12 +6,14 @@ 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. + +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 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,12 +21,39 @@ 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 ``` -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/best-countries/models.md b/docs/best-countries/models.md new file mode 100644 index 0000000..f9c0325 --- /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 + +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. 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). | + +### 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. 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). | + +### 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. The [table above](#available-models) shows the default for each model. + +### 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`, with 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 for illustration only. The example shows only some of the metrics. + +## 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 give the overall +ranking. Returns one field per factor `key` and 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..2442113 --- /dev/null +++ b/docs/best-countries/raw-data.md @@ -0,0 +1,59 @@ +# Raw Data + +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 +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. + +## 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 +``` + +If the endpoint cannot find the year, or the year has no Best Countries data, the endpoint returns a `404`. + +## 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, 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 + +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 +``` + +## Sorting + +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/brand-data/agency-change-predictor.md b/docs/brand-data/agency-change-predictor.md new file mode 100644 index 0000000..dcf5d58 --- /dev/null +++ b/docs/brand-data/agency-change-predictor.md @@ -0,0 +1,129 @@ +# Agency Change Predictor + +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 + +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 [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 | +|---------------|:------------------------------:|---------|---------------------------------------------------------------------------------------------------------------------| +| `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 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. | +| `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 the standard vulnerability score uses. + +| 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. 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"). The API keeps this name for backwards compatibility. +::: + +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 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 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 +``` + +### 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` 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 +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. 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 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 + +| 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) 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 b1e3a45..932d552 100644 --- a/docs/brand-data/archetypes.md +++ b/docs/brand-data/archetypes.md @@ -1,13 +1,16 @@ # Archetypes -Archetypes data are split across two types: +Archetypes show how strongly a brand is associated with each of the twelve BAV brand archetypes, such as Inventor, +Expert and Rebel. Each archetype has a percentile rank and a construct score. + +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 @@ -17,13 +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. 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 -| 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 +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. 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 030be76..4d139ee 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. The tool considers only brands with a knowledge percentile rank of 50 or above. + ## 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 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 6798326..f08fcfe 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. It returns the +vulnerability assessment that the Agency Change Predictor uses, 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..87e3f68 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". 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 ```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/brand-worth.md b/docs/brand-data/brand-worth.md new file mode 100644 index 0000000..70dd051 --- /dev/null +++ b/docs/brand-data/brand-worth.md @@ -0,0 +1,38 @@ +# 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. + +For the Brand Worth Map tool, see the [Brand Worth Map](brand-worth-map.md) endpoint. + +## Creating a query + +```http request +POST /api/v2/brandscape/brand-worth +``` + +Send the parameters as a JSON body. + +This endpoint requires the `bav:brand-data` scope. + +## 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 + +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. If a study examines a brand in more +than one category, the model includes the brand only once. + +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 b28a1bf..46e5384 100644 --- a/docs/brand-data/brandscape-data.md +++ b/docs/brand-data/brandscape-data.md @@ -2,123 +2,210 @@ ## 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". -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 that gets 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: +Scope each request 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 +If you filter by a country without a year, or by a year without a country, the API returns a `400` error. -You may also directly retrieve a brandscape data's details if you already have its system ID. +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. -```http request -GET /api/v2/brandscape-data/123 +If you do not give an `audiences` filter, the API returns the data for the All Adults audience (ID `1`). + +### Study types + +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: + +- `syndicated` - The syndicated BAV study (default). +- `snap` - SnapBAV studies. +- `fused` - Fused studies. +- `custom` - Custom studies. + +The API ignores unknown values. The `study_types` filter has no effect when you use the `studies` filter. + +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 +{ + "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 + } +} +``` + +This endpoint never returns data from BAV AURA studies. + +### Data generation + +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 +{ + "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 ### 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 +- 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: +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. -In addition to this, there are two special fields: +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). -- `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. +Each row also has the following fields, together with the metric data: -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 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. 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 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 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: +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: -- `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). 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). 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. It uses 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. + +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 a helper parameter. This is used as a top-level query -parameter. +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: `differentation,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_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`). 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 -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. +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. +- `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..4936992 100644 --- a/docs/brand-data/category-worth-map.md +++ b/docs/brand-data/category-worth-map.md @@ -1,5 +1,9 @@ # Category Worth Map +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 ```http request @@ -12,4 +16,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..933a07f 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,36 +23,49 @@ GET /api/v2/cee-opinions/123 Where `123` is the system ID of the cee opinion. +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. It consists of both metadata columns (study details) and the opinion and -value columns. 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. + +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 brands 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): -- `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. -- `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 +- `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 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_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 filters the opinions to only those for the given countries. +- `updated_since` - A date. Include only 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, the API does not include relationships. For more information, see the +[includes section](../customizing/includes). 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..756b77a 100644 --- a/docs/brand-data/commitment-funnel.md +++ b/docs/brand-data/commitment-funnel.md @@ -1,15 +1,45 @@ # Commitment Funnel +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 ```http request GET /api/v2/tools/commitment-funnel ``` +This endpoint takes the same filters as the [data models](data-models.md). Pass array parameters with +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 +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. 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` can resolve to: `syndicated` (the standard BAV study), `snap`, `fused` or `custom`. The API ignores this parameter when `studies` is set. | + +:::note + +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. + +::: + +## 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`). 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 fa0c852..539bf2e 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 + +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 new file mode 100644 index 0000000..0d92f2b --- /dev/null +++ b/docs/brand-data/data-models.md @@ -0,0 +1,243 @@ +--- +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. 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: + +| 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. + +## Category specific and category agnostic models + +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. 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}`. Send the parameters as a JSON body. + +```http request +POST /api/v2/brandscape/pillars +``` + +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. If you pass a name, the system tries to find the correct record from 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 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. + +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: + +```json +{ + "brands": ["148", "149"], + "countries": ["US"], + "years": ["2025"], + "audiences": ["1"] +} +``` + +### Benchmarks + +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. +- `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 that describe + the model), `data` (the data as a CSV string) and `prompt` (a finished prompt that combines the instructions and the + data, which you can 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 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. The page of each model lists these keys. + +### 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 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 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). | +| `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 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 + +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) 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. 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 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. Use it for conditional logic. | +| `label` | string | The human-readable name of the classification, as The Fount labels it. | +| `description` | string\|null | Copy that describes 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/brand-data/imagery.md b/docs/brand-data/imagery.md new file mode 100644 index 0000000..2f53845 --- /dev/null +++ b/docs/brand-data/imagery.md @@ -0,0 +1,37 @@ +# 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 +``` + +Send the parameters as a JSON body. + +This endpoint requires the `bav:brand-data` scope. + +## 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 + +The response follows the [standard data model schema](data-models.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) 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 ce80d58..68953aa 100644 --- a/docs/brand-data/index.md +++ b/docs/brand-data/index.md @@ -1,14 +1,15 @@ # 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. \ No newline at end of file +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 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 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 new file mode 100644 index 0000000..1d9ce19 --- /dev/null +++ b/docs/brand-data/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. + +## Creating a query + +```http request +POST /api/v2/brandscape/influence +``` + +Send the parameters as a JSON body. + +This endpoint requires the `bav:brand-data` scope. + +## 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 + +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`. This model does not include the overall +`mib_influential` metric. 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..9143c40 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 brand can 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. If you swap the two +brands, you get 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/personality.md b/docs/brand-data/personality.md new file mode 100644 index 0000000..53ff77b --- /dev/null +++ b/docs/brand-data/personality.md @@ -0,0 +1,34 @@ +# Personality + +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. + +Personality is category agnostic. + +## Creating a query + +```http request +POST /api/v2/brandscape/personality +``` + +Send the parameters as a JSON body. + +This endpoint requires the `bav:brand-data` scope. + +## 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 + +The response follows the [standard data model schema](data-models.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) 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 new file mode 100644 index 0000000..294e4fe --- /dev/null +++ b/docs/brand-data/pillars.md @@ -0,0 +1,46 @@ +# Pillars + +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** +- **Relevance** +- **Esteem** +- **Knowledge** + +If you chart the pillars, show them as a column chart in the order above. + +Pillars are category agnostic. + +## Creating a query + +```http request +POST /api/v2/brandscape/pillars +``` + +Send the parameters as a JSON body. + +This endpoint requires the `bav:brand-data` scope. + +## 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 + +The response follows the [standard data model schema](data-models.md#schema). + +### Metrics + +The data points include the `differentiation`, `relevance`, `esteem` and `knowledge` metrics, each with: + +- `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 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 new file mode 100644 index 0000000..5f2a8e0 --- /dev/null +++ b/docs/brand-data/powergrid.md @@ -0,0 +1,61 @@ +# Powergrid + +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 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. 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. + +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**. + +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. + +## Creating a query + +```http request +POST /api/v2/brandscape/powergrid +``` + +Send the parameters as a JSON body. + +This endpoint requires the `bav:brand-data` scope. + +## 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 + +The response follows the [standard data model schema](data-models.md#schema). + +### Metrics + +The data points include the `brand_strength` and `brand_stature` metrics, each with: + +- `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. Do not derive the quadrant from the ranks yourself. + +### Meta + +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 new file mode 100644 index 0000000..d8bb3ae --- /dev/null +++ b/docs/brand-data/preferences.md @@ -0,0 +1,41 @@ +# 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. You can use them to understand how likely consumers are to choose a brand. + +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 + +```http request +POST /api/v2/brandscape/preferences +``` + +Send the parameters as a JSON body. + +This endpoint requires the `bav:brand-data` scope. + +## 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 + +The response follows the [standard data model schema](data-models.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 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 new file mode 100644 index 0000000..789a76b --- /dev/null +++ b/docs/brand-data/recommendation.md @@ -0,0 +1,34 @@ +# Recommendation + +Recommendation shows how likely consumers are to recommend a brand to a friend. It is consistent across all studies. + +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 + +```http request +POST /api/v2/brandscape/recommendation +``` + +Send the parameters as a JSON body. + +This endpoint requires the `bav:brand-data` scope. + +## 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 + +The response follows the [standard data model schema](data-models.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) 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 new file mode 100644 index 0000000..51509a0 --- /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 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. 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). + +## 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 the example shows only some of the metrics. diff --git a/docs/brand-data/super-cx.md b/docs/brand-data/super-cx.md new file mode 100644 index 0000000..35dd2ee --- /dev/null +++ b/docs/brand-data/super-cx.md @@ -0,0 +1,31 @@ +# Super CX + +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. 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, because it shares its parameters and response with the other [data models](data-models.md). + +## Creating a query + +```http request +POST /api/v2/brandscape/super-cx +``` + +Send the parameters as a JSON body. + +This endpoint requires the `bav:brand-data` scope. + +## 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 + +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). diff --git a/docs/brand-data/swot.md b/docs/brand-data/swot.md index 1f9f2bb..e9cf1e1 100644 --- a/docs/brand-data/swot.md +++ b/docs/brand-data/swot.md @@ -1,5 +1,8 @@ # SWOT +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 ```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). 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 new file mode 100644 index 0000000..b31388c --- /dev/null +++ b/docs/brand-data/tools.md @@ -0,0 +1,55 @@ +--- +sidebar_label: Overview +--- + +# Tools + +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 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. 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`. 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 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 + +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 | +|-------------------------------------|-----------------------------------|------------------------------------------| +| [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/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/brand-data/usage.md b/docs/brand-data/usage.md new file mode 100644 index 0000000..81e887f --- /dev/null +++ b/docs/brand-data/usage.md @@ -0,0 +1,41 @@ +# 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. 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 + +```http request +POST /api/v2/brandscape/usage +``` + +Send the parameters as a JSON body. + +This endpoint requires the `bav:brand-data` scope. + +## 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 + +The response follows the [standard data model schema](data-models.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 are in each usage level. +- `rank` - The percentile rank (0-100) that compares the brand to all other brands in the market. diff --git a/docs/brands/brand-tags.md b/docs/brands/brand-tags.md new file mode 100644 index 0000000..77b0e83 --- /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 through the API, use the list endpoint: + +```http request +GET /api/v2/brand-tags +``` + +By default, the API sorts the tags by category and name. + +## Get a brand tag + +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 +``` + +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 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 | +|-------------------|---------|--------------------------------------------------------------------------------------------------------| +| `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, 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) 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..eb92f29 --- /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 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 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 through the API, use the list endpoint: + +```http request +GET /api/v2/brand-variations +``` + +## Get a brand variation + +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 +``` + +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 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 | +|---------|---------|---------------------------------------------------------------------| +| `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 + +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. +- `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, the response does not include relationships. 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 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 2c5791d..282617b 100644 --- a/docs/brands/brands.md +++ b/docs/brands/brands.md @@ -1,19 +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](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. 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 @@ -21,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 @@ -33,63 +38,105 @@ 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 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. | +| `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 + +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. +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 | -|----------|---------|--------------------------------------------------------------| -| `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 -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: - -- `years` - A comma-separated list of year IDs. 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. -- `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. -- `regions` - A comma-separated list of region IDs. This will filter the brands to only those that are studied in - the specified regions. -- `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. +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. +- `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. 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, 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, 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 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 if AI assigned the tag or a person assigned it 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 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. You can also sort on only one column. diff --git a/docs/brands/collections.md b/docs/brands/collections.md index eb04b99..80659ad 100644 --- a/docs/brands/collections.md +++ b/docs/brands/collections.md @@ -2,22 +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. +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. + +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. 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 @@ -25,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 @@ -41,19 +53,30 @@ 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. 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: +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. +- `mine` - Set to `1` to return only collections that the user created. + +Any value turns these filters on. + +## 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 are available: -- `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. +- `brands` - The [brands](brands.md) in the collection, with the brand relationship schema (`id`, `name`, `sector` + and `signalai_id`). ## Searching diff --git a/docs/company-data/companies.md b/docs/company-data/companies.md index 20aa9a1..4cecc15 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 @@ -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). 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 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 ### Full response schema @@ -44,10 +63,11 @@ 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 -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 | |--------|---------|----------------------------------| @@ -56,22 +76,24 @@ 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 -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. -- `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..2def8dd 100644 --- a/docs/company-data/stock-prices.md +++ b/docs/company-data/stock-prices.md @@ -2,59 +2,123 @@ ## 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. 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. -## List all stock prices +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. -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 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`. 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 can name up to 25 companies and tickers in total in each 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). | + +If a ticker duplicates the primary listing of a requested company, the response contains that ticker only once. + +### Intervals + +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 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 that describes the response. The API +groups the rows by ticker and sorts them 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 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 can 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 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 + +- 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/customizing/fields.md b/docs/customizing/fields.md index 658114d..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](../brand-data/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..ed2b0ff 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,20 @@ 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 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 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 on or 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 8b893c2..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 @@ -13,3 +12,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 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/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..ffcca2a 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 `bavapi.parsing.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,58 +123,65 @@ 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. +- `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 have been updated since 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. -For more information on the behavior of each of these parameters, see the [customizing fields](/customizing/fields.md) +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. ### 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( ... 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", } ``` -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 `3`). 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 +215,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..c5d546c 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 | ... | |----:|:-------|:-------|:----| @@ -36,82 +36,86 @@ 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") ``` :::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. +:::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. -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 | |-------------------------|----------------------------| +| `"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 -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. +:::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. -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. ```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"]} ) ``` @@ -128,11 +132,10 @@ 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"}) +result = bavapi.brands("TOKEN", name="Swatch", filters={"name": "Facebook"}) ``` The request will use `name="Facebook"`, because values specified in the `filters` parameter take precedence. @@ -140,60 +143,59 @@ 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 +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 ``` -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")) +bavapi.brands("TOKEN", filters=bavapi.filters.BrandsFilters(name="Swatch", sector_name="Watches")) ``` ### 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"]) +result = bavapi.brands("TOKEN", name="Swatch", fields=["id", "name"]) 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 -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") ``` -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 -result = bavapi.brands(name="Swatch", includes="company") +result = bavapi.brands("TOKEN", name="Swatch", include="company") ``` :::note Default Includes @@ -202,36 +204,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 +bavapi.studies("TOKEN", 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,41 +255,40 @@ 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. -bavapi.brands(name="Swatch", query=bavapi.Query(filters={"name":"Facebook"})) +bavapi.brands("TOKEN", 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,11 +297,11 @@ 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) +bavapi.brands("TOKEN", "Facebook", include="studies", stack_data=True) ``` | | id | name | studies_id | studies_name | ... | @@ -311,10 +312,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 +336,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 +365,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`. @@ -393,27 +393,27 @@ 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"`: +:::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"`: -- 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..81a08e5 100644 --- a/docs/developer-tools/python/endpoints/audience-groups.md +++ b/docs/developer-tools/python/endpoints/audience-groups.md @@ -4,10 +4,10 @@ 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, 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..e83248e 100644 --- a/docs/developer-tools/python/endpoints/brands.md +++ b/docs/developer-tools/python/endpoints/brands.md @@ -4,10 +4,10 @@ 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, 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..364993f 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 | | ------------------- | ----------------- | ------------------------ | ------------------- | @@ -21,7 +21,7 @@ The `brandscape-data` endpoint has full support, including query validation. ```py title="Using top-level functions" import bavapi -result = bavapi.brandscape_data("TOKEN", name="Facebook") +result = bavapi.brandscape_data("TOKEN", brand_name="Facebook") ``` @@ -31,14 +31,14 @@ 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") ``` :::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 @@ -71,21 +70,20 @@ 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 ``` ## 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,31 @@ 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 +## Metric and metric group keys -`brandscape-data` provides a special filter to specify the data *columns* that the response should -contain: `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 that your response should contain, and the API will include all score types for that metric. +- 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 -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` @@ -133,3 +132,14 @@ columns: - 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 4ee32ba..fa94f64 100644 --- a/docs/developer-tools/python/endpoints/categories.md +++ b/docs/developer-tools/python/endpoints/categories.md @@ -4,10 +4,10 @@ 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, including query validation. +The `categories` endpoint has full support. This support includes query validation. | Endpoint | Function | `Client` method | Filters class | | -------------- | ------------ | ------------------- | ------------------- | @@ -44,17 +44,17 @@ 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 -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 6624281..abe5643 100644 --- a/docs/developer-tools/python/endpoints/cities.md +++ b/docs/developer-tools/python/endpoints/cities.md @@ -4,10 +4,10 @@ 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, 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..4dbd1da 100644 --- a/docs/developer-tools/python/endpoints/companies.md +++ b/docs/developer-tools/python/endpoints/companies.md @@ -4,10 +4,10 @@ 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, 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..3618a6c 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,14 +80,14 @@ 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 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 421d2c3..8c77def 100644 --- a/docs/developer-tools/python/endpoints/regions.md +++ b/docs/developer-tools/python/endpoints/regions.md @@ -4,10 +4,10 @@ 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, 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..589115e 100644 --- a/docs/developer-tools/python/endpoints/sectors.md +++ b/docs/developer-tools/python/endpoints/sectors.md @@ -4,10 +4,10 @@ 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, 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..172010b 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 [Endpoints](python/endpoints/) section. +The behavior of each Fount API endpoint can be slightly different. You can find detailed explanations in +the [Endpoints](endpoints/index.md) section. ## Example usage -:::info "Protected access" -:lock: To use `bavapi`, you will 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 @@ -57,20 +58,21 @@ 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) - - 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..2083efb 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](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,34 +30,34 @@ 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: ```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) ``` :::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) 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` 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..59622a9 100644 --- a/docs/embed/implementation.md +++ b/docs/embed/implementation.md @@ -2,39 +2,37 @@ ## 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 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 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. +:::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 bavsupport@wpp.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: -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" } ``` -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 { @@ -42,28 +40,27 @@ Your request will return an access token for the user that you will need to pass } ``` -:::caution Access Token Expiration +:::caution Access token expiry 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 ``` -:::caution Parameters Format -The supported parameters should always be passed 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/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 6fab316..737474e 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -1,34 +1,51 @@ # 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 -| 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 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 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 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 ```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..084a944 100644 --- a/docs/health-check.md +++ b/docs/health-check.md @@ -1,27 +1,29 @@ # 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 +```http request +GET /api/v2/health ``` -GET /health -``` + +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. +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 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. +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 { "status": "ok", - "timestamp": "2023-10-01T12:00:00Z" + "timestamp": "2026-10-01 12:00:00" } ``` diff --git a/docs/intro.md b/docs/intro.md index 7608331..414690d 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. +:::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 +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/market-share/brand-shares.md b/docs/market-share/brand-shares.md new file mode 100644 index 0000000..92eff86 --- /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 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). + +## 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`) 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 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 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 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. The API rejects a request without any of these with a validation error. + +### Score types + +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 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. + +## 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 +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 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` 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 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. | +| `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. Do not sum or average them. + +```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. 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 new file mode 100644 index 0000000..20d930b --- /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. 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 +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 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. | + +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 +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 +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 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 and not 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` 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, 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 +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. 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 +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). 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 +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 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. +- `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..fb39981 --- /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. + +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 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). + +## 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`) 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 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. 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 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. The API rejects +a request without any of these 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 +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` when there is no record to refer to, 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. 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 new file mode 100644 index 0000000..58f3865 --- /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. 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: + +| 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](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. + +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. Read these concepts before you +start to build on 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 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) + 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 +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 + +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. 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. 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 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 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. 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 new file mode 100644 index 0000000..f0f5c7c --- /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. 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 through the API, use the list endpoint: + +```http request +GET /api/v2/bav-question-groups +``` + +## Get a BAV question group + +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 +``` + +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 API uses the slim relationship schema when the BAV question group is 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 + +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. + +## 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..945224f --- /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 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. + +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 through the API, use the list endpoint: + +```http request +GET /api/v2/bav-questions +``` + +## Get a BAV question + +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 +``` + +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 API uses the slim relationship schema when the BAV question is 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. 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. Use it 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. + +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. + +By default, the results are sorted by `study_id`. You can 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 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 new file mode 100644 index 0000000..eca527f --- /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 through the API, use the list endpoint: + +```http request +GET /api/v2/brand-measure-groups +``` + +## Get a brand measure group + +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 +``` + +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 API uses the slim relationship schema when the brand measure group is 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 + +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. + +## 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..75b9af1 --- /dev/null +++ b/docs/measures/brand-measures.md @@ -0,0 +1,99 @@ +# Brand Measures + +## What are brand measures? + +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). 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 +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 through the API, use the list endpoint: + +```http request +GET /api/v2/brand-measures +``` + +## Get a brand measure + +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 +``` + +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 API uses the slim relationship schema when the brand measure is 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. + +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. + +By default, the results are sorted by `study_id`. You can 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..487905a --- /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 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). +- **[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 + +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 new file mode 100644 index 0000000..3ad93ee --- /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. + +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 | +|------------------------|---------|:--------------------------:|:------------------:|----------------------------------------------------------------------------------------------| +| `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. + +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 | +|---------------------------|---------|:--------------------------:|:------------------:|-------------------------------------------------------------------------------------| +| `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 that you use. 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 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. The endpoint lists only the studies that you have access to. + +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 | +|--------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| `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/cities.md b/docs/metadata/cities.md index e6655fe..1853749 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 @@ -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. 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. | + +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: +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 `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..c83a9bc 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 @@ -29,56 +29,58 @@ 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 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. | +| `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 -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 | |----------------|---------|------------------------------------------------------------------------------------------| | `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 -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: +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. -- `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 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. ## 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/country-indicators.md b/docs/metadata/country-indicators.md new file mode 100644 index 0000000..7aa3572 --- /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 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 +GET /api/v2/countries/GB/indicators +``` + +## Get the indicators for a year + +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 +``` + +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, with 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 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 +GET /api/v2/countries/GB/indicators?sort=-year.year +``` 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 1994189..d3183a3 100644 --- a/docs/metadata/operating-companies.md +++ b/docs/metadata/operating-companies.md @@ -2,22 +2,22 @@ ## 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 ``` -## Get a operating company +## Get an 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 @@ -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 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. + +| Key | Type | Description | +|--------|---------|------------------------------------------| +| `id` | integer | The system ID for the operating company. | +| `name` | string | The name of the operating company. | ## 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: +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](companies.md) that owns another company. -- `brand` - The [brand](brands.md) that the operating company has. +- `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 870a118..d102c1e 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 @@ -32,22 +32,21 @@ 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 slim relationship schema is used when the region is used as 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: -- `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 57e7df9..8939c67 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](categories.md). You -can read more about the categories and what they represent on the [categories endpoint](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,15 +33,15 @@ 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. | +| `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. | ### 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,19 +50,19 @@ 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 -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: -- `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..c2e700f 100644 --- a/docs/metadata/stock-exchanges.md +++ b/docs/metadata/stock-exchanges.md @@ -2,11 +2,11 @@ ## 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 -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,20 +39,20 @@ 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 -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 756bb72..9838f72 100644 --- a/docs/metadata/tools.md +++ b/docs/metadata/tools.md @@ -2,27 +2,32 @@ ## 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 ``` -## Get a year +## Get a tool -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 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 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. | -| `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 d4eded6..d329133 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 @@ -30,13 +30,13 @@ 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. | ### 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 a7d6633..d0f1714 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 @@ -31,15 +31,15 @@ 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. | -| `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. | +| `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 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,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 -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 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..fa0a90b 100644 --- a/docs/metrics/metrics.md +++ b/docs/metrics/metrics.md @@ -2,20 +2,20 @@ ## 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 ``` -## Get a brand +## Get a brand metric -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 metric, you can also get its details directly. ```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. | +| `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. | -| `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. | +| `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. | +| `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 API uses the slim relationship schema when the brand metric is 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 -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. - `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. 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. - `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..c081593 100644 --- a/docs/pagination.md +++ b/docs/pagination.md @@ -1,15 +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. +- `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: @@ -19,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 { @@ -27,7 +28,7 @@ The structure of the API list response is as follows: { ... } - // 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", @@ -117,8 +118,9 @@ The structure of the API list response is as follows: } ], "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/rate-limiting.md b/docs/rate-limiting.md index 3e2a453..993d6ac 100644 --- a/docs/rate-limiting.md +++ b/docs/rate-limiting.md @@ -1,16 +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. +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 requsts 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/studies/categories.md b/docs/studies/categories.md index 7dafb8c..5c41a71 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,12 +32,16 @@ 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 ``` +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 @@ -50,26 +55,29 @@ GET /api/v2/categories/123 ### 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 | |--------|---------|-----------------------------------| | `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 -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. 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 -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..b3ab90d 100644 --- a/docs/studies/studies.md +++ b/docs/studies/studies.md @@ -2,16 +2,18 @@ ## 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. +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](./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 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 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 @@ -19,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 @@ -29,140 +31,231 @@ 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. +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 + +To get a list of the categories in a study, use 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 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. Be careful when you compare +studies that were run on different ones. + +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 | +|-------------------|----------------------|---------------| +| `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. +The API uses the slim relationship schema when the study is 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` | 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 -| 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. | +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 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 | |--------------|---------|:-----------------------------------------:|:------------------:|:------------------:|---------------------------------------------------------| | `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: +When you get the categories in a study, the API uses the following schema: -| 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 -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. +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 + by type number instead. +- `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. +- `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. -- `regions` - A comma-separated list of region IDs. This will filter the studies to only those that are in the given +- `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. 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 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 +- `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. 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 +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. +- `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. The API filters the categories to only those + that have the given brand variations in the study. + +:::caution Filter naming + +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`. + +::: ## 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..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 not 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 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..73695e7 100644 --- a/docs/webhooks.md +++ b/docs/webhooks.md @@ -3,85 +3,92 @@ 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 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 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. -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 subscribes to one or more events. BAV triggers the data change events 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: +## How does a webhook work? -- `Audience Export` - [Documentation](#) +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. -## How does a webhook work? +To receive data from the webhook, you need only an HTTP endpoint that: -A webhook is simple 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. +- 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. -To receive data from the webhook all you need is a simple HTTP endpoint that: +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: -- Is available on a publicly accessible HTTPS, non-localhost URL. -- Responds with a `HTTP 200` status code to the Webhook POST request. +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 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 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. -- Respond to the request with a `HTTP 200` status code. +- 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 [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 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 @@ -92,22 +99,22 @@ BAV-Signature: d0e1c26711234ca18e4c7c879d5c41a5221db7ea5349c07073573341378aa2b4 User-Agent: BAV-Webhook ``` -The custom headers sent by BAV are: +The custom headers that BAV sends 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: +BAV sends the payload with this 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 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. | -| `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 +123,7 @@ For example: ```json { - "action": "create", + "action": "created", "data": { "id": 1, "name": "BAV@WPP" @@ -124,31 +131,31 @@ 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" } ``` ## 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. +:::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. -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. ::: @@ -204,5 +211,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 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/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", diff --git a/sidebars.js b/sidebars.js index 2f427b0..c4d244c 100644 --- a/sidebars.js +++ b/sidebars.js @@ -42,6 +42,8 @@ const sidebars = { items: [ 'brands/brands', 'brands/collections', + 'brands/brand-tags', + 'brands/brand-variations', ], }, { @@ -58,6 +60,26 @@ const sidebars = { items: [ 'brand-data/index', 'brand-data/brandscape-data', + 'brand-data/data-models', + 'brand-data/brand-worth', + 'brand-data/cee-opinions', + 'brand-data/imagery', + 'brand-data/influence', + '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', @@ -67,9 +89,9 @@ const sidebars = { '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/cee-opinions', ], }, { @@ -78,9 +100,22 @@ const sidebars = { 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 +125,8 @@ const sidebars = { 'best-countries/metric-groups', 'best-countries/factors', 'best-countries/country-data', + 'best-countries/models', + 'best-countries/raw-data', ], }, { @@ -100,6 +137,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 +155,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 +178,7 @@ const sidebars = { 'metadata/gics-sectors', 'metadata/stock-exchanges', 'metadata/countries', + 'metadata/country-indicators', 'metadata/cities', ], }, @@ -135,13 +195,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' ], } 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', } ];