Skip to main content

Introducing the BAV MCP Server

Your AI models and agents can now use the official BAV MCP server to access BAV data in both a simple and secure way. An MCP server is a convenient way to connect your AI models and agents to external data sources, such as BAV. The server offers a set of tools that agents can trigger to get the data they need to then process and use in their tasks.

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

New Health Check Endpoint

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.

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.

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.

{
"status": "ok",
"timestamp": "2023-10-01T12:00:00Z"
}

We thank Jakub at Choreograph for the suggestion to add this endpoint, and helping make BAV better.

Improved Searching

Previously you have been able to filter on any text fields returned by all endpoints. The problem with this type of filter is that it relies on common "like" searches which are not quite as good at interpreting various linguistic nuances as you would expect as a user.

To combat this we are introducing support for using our underlying search engine index in select API resources.

The search engine looks across multiple fields and interprets language better. It also prioritizes results, meaning that the more likely result ends up higher.

Each endpoint documentation will show if it supports searching or not. Today the following endpoints have searching support:

  • Audiences
  • Audience Groups
  • Brands
  • Categories
  • Countries
  • Regions
  • Sectors
  • Studies
  • Years

Using searching is as simple as adding the search query parameter to your request. For example on the brands endpoint:

GET https://fount.wppbav.com/api/v2/brands?search=Apple

Take a look at the searching documentation for more details.

New Archetypes Tools API Endpoint

All of the BAV Archetype ranks and scores have been available directly through the Brandscape Data endpoint. The new Archetypes Tools API endpoint offers a more convenient way of accessing the Archetypes data.

It also adds support for getting the "Competitive Archetype" data, which is not available through the Brandscape Data endpoint. Archetypes are divided between the "Cultural Archetype" (against all brands in a study) and the "Competitive Archetype" (against a competitive set). The competitive set can be defined as either a collection or a category.

All the querying details are available in the Archetypes API documentation in the Tools / TurboPitch section.

Introducing Webhooks

We are excited to improve the BAV API with support for webhooks on key platform events. 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.

Webhooks is also a crucial part of our new Audience Export. They are also a core part of upcoming enhancements to allowing other applications to integrate tightly with BAV. Being able to share more data across systems means more convenience for end users and a greater improvement to daily workflows.

Take a look at the comphrehensive webhooks documentation with code examples and recommendations to how best to get started with and implement webhooks.

BAV Python SDK reaches v1.0!

🎉 We are excited to announce the release of the v1.0 (stable) version of the BAV Python SDK!

The latest version of the SDK includes new supported endpoints, new features and many bug fixes.

To update to the latest version of the BAV Python SDK, run the following command:

pip install --upgrade wpp-bavapi
Issues and feature requests

If you encounter any bugs while using the SDK, or if you have any suggestions/requests for new features, we encourage you to open a new issue on GitHub.

Some highlights since our last announcement:

  • 🎉 Full support for many more endpoints, and more versatility for performing endpoint requests.
  • 🚀 bavapi queries should now be faster and more reliable, thanks to various improvements in the requests and response parsing logic.
  • New 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.
  • 📓 Improved SDK documentation and updated with the latest features and functionality.
  • 🐛 Fixed various issues with validation, data parsing and pagination.

Read the detailed changelog on GitHub.

New filter on Brandscape Data - Metric Groups

We strive to make working with the core, raw dataset in the Brandscape Data endpoint as easy as possible. To reduce the complexity in querying the dataset, we have added a new Metric Groups filter.

The filter works the same as the existing metrics filter, but customizes the response to include all the metrics in a given group instead of you having to specify each metric individually.

For example, if you want to retrieve all the metrics in the "Imagery" group, you can use the following request:

GET /api/v2/brandscape-data?metric_group_keys=imagery

You can also specify multiple groups by separating them with a comma:

GET /api/v2/brandscape-data?metric_group_keys=imagery,pillars

For a full list of the available groups you can refer to the UI in The Fount or query the Metric Groups endpoint.

New Cities Endpoint

For some of the data that we track, we need to map it to a city. For this reason we maintain a database of cities in the world with a population over 500 people, based on the GeoNames database.

We have now made this database available through the API. You can find the documentation for the new endpoint in the API reference.

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.

New Python SDK

We are happy to announce the release of our new Python SDK. We use Python scripts quite heavily at BAV and the SDK is a result of our own needs. We hope that it will be useful for others as well.

By using the Python SDK you can easily integrate your Python scripts with BAV without having to spend time creating the necessary API connection overhead.

The SDK is available on GitHub and has been created by Ignacio Maiz at BAV. If you'd like to contribute, we hare more than happy for contributions to the SDK over at GitHub.

The developer tools section has more information on how to get started with the SDK.

New TurboPitch endpoints

While the API has always contained the ability to fetch all the Brandscape Data values, a lot of the time you only need a subset of data in a specific way. This is the philosophy behind the suite of TurboPitch endpoints which are already available in The Fount for you to use.

Today we are opening up the use of these to the API as well, so that you can get the data programatically in the same way as you can graphically in The Fount.

The new endpoints are available for most of the TurboPitch tools. If one that you need isn't yet available, please reach 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. We are happy to help.