tools

Module for interacting with the BAV API's tools.

Read more at https://developer.wppbav.com/docs/2.x/tools.

Each tool will return very different results, depending on each of their requirements. Check the return types of each function and method.

Examples:

>>> from bavapi.tools import ToolsClient
>>> async with ToolsClient("TOKEN") as client:  # Replace "TOKEN" with your BAV API key
>>>     result = await client.commitment_funnel(brands=1, studies=1)

ToolsClient(auth_token='', *, base_url='', timeout=30.0, verify=True, headers=None, user_agent='', client=None, retries=3)

Asynchronous API to interact with the WPPBAV Fount API tools.

Read more at https://developer.wppbav.com/docs/2.x/tools.

This class uses asyncio to perform asynchronous requests to the Fount API.

Asynchronous requests allow you to make multiple requests at the same time, extremely helpful for working with a paginated API like the Fount. (returns data in multiple pages or requests instead of one single download)

To use the Client class, you will need to precede calls with await:

bav = Client("TOKEN")  # creating client instance does not use `await`
data = await bav.brands("Swatch")  # must use `await`

For more information, see the asyncio documentation for Python.

Either auth_token or client are required to instantiate a Client.

Parameters:

Name	Type	Description	Default
auth_token	str	WPPBAV Fount API authorization token, default ''	''
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
verify	bool or str	Verify SSL credentials, default True Also accepts a path string to an SSL certificate file.	True
headers	dict[str, str]	Collection of headers to send with each request, default None	None
user_agent	str	The name of the User-Agent to send to the Fount API, default ''. If no user_agent is set, bavapi will use "BAVAPI SDK Python" by default.	''
client	AsyncClient	Authenticated async client, default None If client is passed, all other parameters will be ignored.	None
retries	int	Number of times to retry a request, default 3	3

Raises:

Type	Description
ValueError	If neither auth_token nor client are provided

Examples:

Use async with to get data and close the connection.

This way you get the benefits from httpx speed improvements and closes the connection when exiting the async with block.

>>> async with ToolsClient("TOKEN") as bav:
...     data = await bav.commitment_funnel(brands=1, studies=1)

When not using async with, close the connection manually by awaiting aclose.

>>> bav = ToolsClient("TOKEN")
>>> data = await bav.commitment_funnel(brands=1, studies=1)
>>> await bav.aclose()

If you want to perform multiple endpoint requests with the same Client, it is recommended to use verbose=False to avoid jumping progress bars.

>>> async with ToolsClient("TOKEN", verbose=False) as bav:
...     resp1 = await bav.commitment_funnel(brands=1, studies=1)
...     resp2 = await bav.brand_worth_map(brands=1, studies=1)

Source code in bavapi/tools.py

def __init__(
    self,
    auth_token: str = "",
    *,
    base_url: str = "",
    timeout: float = 30.0,
    verify: Union[bool, str] = True,
    headers: Optional[Dict[str, str]] = None,
    user_agent: str = "",
    client: Optional[AsyncClientType] = None,
    retries: int = 3,
) -> None:
    self.retries = retries

    self.client = client or httpx.AsyncClient(
        headers=headers
        or {
            "Authorization": f"Bearer {auth_token}",
            "Accept": "application/json",
            "User-Agent": user_agent or USER_AGENT,
        },
        timeout=timeout,
        verify=verify,
        base_url=base_url or BASE_URL + "tools",
    )

aclose() async

Asynchronously close all client connections.

Source code in bavapi/tools.py

async def aclose(self) -> None:
    """Asynchronously close all client connections."""
    return await self.client.aclose()

archetypes(brands, studies, audiences=None, *, categories=None, collections=None) async

Retrieve results from the archetypes endpoint

See https://developer.wppbav.com/docs/2.x/tools/archetypes for more info.

Parameters:

Name	Type	Description	Default
brands	ListOrValues[int]	Brand ID or list of brand IDs	required
studies	ListOrValues[int]	Study ID or list of study IDs	required
audiences	OptionalListOr[int]	Audience ID or list of audience IDs, default None	None
categories	OptionalListOr[int]	Category ID or list of category IDs for the target category, default None	None
collections	OptionalListOr[int]	Collection ID or list of collections for the target collection, default None	None

Returns:

Type	Description
DataFrame	Dataframe containing the results

Raises:

Type	Description
ValueError	If category or collection are not specified, or if they are both specified
APIError	If an error occurs with the query

Source code in bavapi/tools.py

@validate_call
async def archetypes(
    self,
    brands: ListOrValues[int],
    studies: ListOrValues[int],
    audiences: OptionalListOr[int] = None,
    *,
    categories: OptionalListOr[int] = None,
    collections: OptionalListOr[int] = None,
) -> pd.DataFrame:
    """Retrieve results from the `archetypes` endpoint

    See <https://developer.wppbav.com/docs/2.x/tools/archetypes> for more info.

    Parameters
    ----------
    brands : ListOrValues[int]
        Brand ID or list of brand IDs
    studies : ListOrValues[int]
        Study ID or list of study IDs
    audiences : OptionalListOr[int], optional
        Audience ID or list of audience IDs, default None
    categories : OptionalListOr[int], optional
        Category ID or list of category IDs for the target category, default None
    collections : OptionalListOr[int], optional
        Collection ID or list of collections for the target collection, default None

    Returns
    -------
    pd.DataFrame
        Dataframe containing the results

    Raises
    ------
    ValueError
        If category or collection are not specified, or if they are both specified
    APIError
        If an error occurs with the query
    """
    if not bool(categories) ^ bool(collections):
        raise ValueError("Either categories OR collections must be specified.")

    params = {
        "brands": brands,
        "studies": studies,
        "audiences": audiences,
        "categories": categories,
        "collections": collections,
    }

    def parse_entry(entry: JSONDict) -> _Params[Union[str, float]]:
        data = entry.pop("data")
        entry_with_data = entry.copy()
        entry_with_data.update(data)  # type: ignore[arg-type]
        parsed = flatten_mapping(entry_with_data)
        return parsed  # type: ignore[return-value]

    resp = await self._get("archetypes", params=_to_url_params(params))

    with _raise_if_fails():
        payload = cast(JSONDict, resp["data"])
        return pd.DataFrame(
            [parse_entry(entry) for entry in payload]  # type: ignore[arg-type]
        )

brand_personality_match(brands, studies, audiences=None) async

Retrieve results from the brand-personality-match endpoint

See https://developer.wppbav.com/docs/2.x/tools/brand-personality-match for more info.

Parameters:

Name	Type	Description	Default
brands	ListOrValues[int]	Brand ID or list of brand IDs	required
studies	ListOrValues[int]	Study ID or list of study IDs	required
audiences	OptionalListOr[int]	Audience ID or list of audience IDs, default None	None

Returns:

Type	Description
DataFrame	Dataframe containing the results

Raises:

Type	Description
APIError	If an error occurs with the query

Source code in bavapi/tools.py

@validate_call
async def brand_personality_match(
    self,
    brands: ListOrValues[int],
    studies: ListOrValues[int],
    audiences: OptionalListOr[int] = None,
) -> pd.DataFrame:
    """Retrieve results from the `brand-personality-match` endpoint

    See <https://developer.wppbav.com/docs/2.x/tools/brand-personality-match> for more info.

    Parameters
    ----------
    brands : ListOrValues[int]
        Brand ID or list of brand IDs
    studies : ListOrValues[int]
        Study ID or list of study IDs
    audiences : OptionalListOr[int], optional
        Audience ID or list of audience IDs, default None

    Returns
    -------
    pd.DataFrame
        Dataframe containing the results

    Raises
    ------
    APIError
        If an error occurs with the query
    """
    params = {
        "brands": brands,
        "studies": studies,
        "audiences": audiences,
    }

    resp = await self._get("brand-personality-match", params=_to_url_params(params))

    with _raise_if_fails():
        payload = cast(List[JSONDict], resp["data"])
        return parse_response(payload)

brand_vulnerability_map(brand) async

Retrieve results from the brand-vulnerability-map endpoint

See https://developer.wppbav.com/docs/2.x/tools/brand-vulnerability-map for more info.

Parameters:

Name	Type	Description	Default
brand	int	Brand ID	required

Returns:

Type	Description
DataFrame	Dataframe containing the results

Raises:

Type	Description
APIError	If an error occurs with the query

Source code in bavapi/tools.py

@validate_call
async def brand_vulnerability_map(self, brand: int) -> pd.DataFrame:
    """Retrieve results from the `brand-vulnerability-map` endpoint

    See <https://developer.wppbav.com/docs/2.x/tools/brand-vulnerability-map> for more info.

    Parameters
    ----------
    brand : int
        Brand ID

    Returns
    -------
    pd.DataFrame
        Dataframe containing the results

    Raises
    ------
    APIError
        If an error occurs with the query
    """
    params: _Params[Union[str, int]] = {"brand": brand}

    resp = await self._get("brand-vulnerability-map", params=params)

    with _raise_if_fails():
        payload = cast(List[JSONDict], resp["data"])
        return parse_response(payload)

brand_worth_map(brands, studies, audiences=None) async

Retrieve results from the brand-worth-map endpoint

See https://developer.wppbav.com/docs/2.x/tools/brand-worth-map for more info.

Parameters:

Name	Type	Description	Default
brands	ListOrValues[int]	Brand ID or list of brand IDs	required
studies	ListOrValues[int]	Study ID or list of study IDs	required
audiences	OptionalListOr[int]	Audience ID or list of audience IDs, default None	None

Returns:

Type	Description
Tuple[JSONDict, DataFrame]	A tuple containing a JSON dictionary of metadata and a Dataframe with the results

Raises:

Type	Description
APIError	If an error occurs with the query

Source code in bavapi/tools.py

@validate_call
async def brand_worth_map(
    self,
    brands: ListOrValues[int],
    studies: ListOrValues[int],
    audiences: OptionalListOr[int] = None,
) -> Tuple[JSONDict, pd.DataFrame]:
    """Retrieve results from the `brand-worth-map` endpoint

    See <https://developer.wppbav.com/docs/2.x/tools/brand-worth-map> for more info.

    Parameters
    ----------
    brands : ListOrValues[int]
        Brand ID or list of brand IDs
    studies : ListOrValues[int]
        Study ID or list of study IDs
    audiences : OptionalListOr[int], optional
        Audience ID or list of audience IDs, default None

    Returns
    -------
    Tuple[JSONDict, pd.DataFrame]
        A tuple containing a JSON dictionary of metadata and a Dataframe with the results

    Raises
    ------
    APIError
        If an error occurs with the query
    """
    params = {
        "brands": brands,
        "studies": studies,
        "audiences": audiences,
    }

    resp = await self._get("brand-worth-map", params=_to_url_params(params))

    with _raise_if_fails():
        payload = cast(JSONDict, resp["data"])
        data = cast(List[JSONDict], payload.pop("data"))
        return payload, parse_response(data)

category_worth_map(categories, studies, audiences=None) async

Retrieve results from the category-worth-map endpoint

[NOT IMPLEMENTED]

See https://developer.wppbav.com/docs/2.x/tools/category-worth-map for more info.

Parameters:

Name	Type	Description	Default
categories	ListOrValues[int]	Category ID or list of category IDs	required
studies	ListOrValues[int]	Study ID or list of study IDs	required
audiences	OptionalListOr[int]	Audience ID or list of audience IDs, default None	None

Returns:

Type	Description
Tuple[JSONDict, DataFrame]	A tuple containing a JSON dictionary of metadata and a Dataframe with the results

Raises:

Type	Description
APIError	If an error occurs with the query

Source code in bavapi/tools.py

@validate_call
async def category_worth_map(
    self,
    categories: ListOrValues[int],
    studies: ListOrValues[int],
    audiences: OptionalListOr[int] = None,
) -> Tuple[JSONDict, pd.DataFrame]:
    """Retrieve results from the `category-worth-map` endpoint

    [NOT IMPLEMENTED]

    See <https://developer.wppbav.com/docs/2.x/tools/category-worth-map> for more info.

    Parameters
    ----------
    categories : ListOrValues[int]
        Category ID or list of category IDs
    studies : ListOrValues[int]
        Study ID or list of study IDs
    audiences : OptionalListOr[int], optional
        Audience ID or list of audience IDs, default None

    Returns
    -------
    Tuple[JSONDict, pd.DataFrame]
        A tuple containing a JSON dictionary of metadata and a Dataframe with the results

    Raises
    ------
    APIError
        If an error occurs with the query
    """
    # params = {
    #     "categories": categories,
    #     "studies": studies,
    #     "audiences": audiences,
    # }

    # resp = await self._get("category-worth-map", params=_to_url_params(params))

    # with _raise_if_fails():
    #     payload = cast(JSONDict, resp["data"])
    #     data = cast(List[JSONDict], payload.pop("data"))
    #     return payload, parse_response(data)

    raise NotImplementedError

commitment_funnel(brands, studies, audiences=None) async

Retrieve results from the commitment-funnel endpoint

See https://developer.wppbav.com/docs/2.x/tools/commitment-funnel for more info.

Parameters:

Name	Type	Description	Default
brands	ListOrValues[int]	Brand ID or list of brand IDs	required
studies	ListOrValues[int]	Study ID or list of study IDs	required
audiences	OptionalListOr[int]	Audience ID or list of audience IDs, default None	None

Returns:

Type	Description
DataFrame	Dataframe containing the results

Raises:

Type	Description
APIError	If an error occurs with the query

Source code in bavapi/tools.py

@validate_call
async def commitment_funnel(
    self,
    brands: ListOrValues[int],
    studies: ListOrValues[int],
    audiences: OptionalListOr[int] = None,
) -> pd.DataFrame:
    """Retrieve results from the `commitment-funnel` endpoint

    See <https://developer.wppbav.com/docs/2.x/tools/commitment-funnel> for more info.

    Parameters
    ----------
    brands : ListOrValues[int]
        Brand ID or list of brand IDs
    studies : ListOrValues[int]
        Study ID or list of study IDs
    audiences : OptionalListOr[int], optional
        Audience ID or list of audience IDs, default None

    Returns
    -------
    pd.DataFrame
        Dataframe containing the results

    Raises
    ------
    APIError
        If an error occurs with the query
    """
    params: dict[str, OptionalSequenceOr[Union[str, int]]] = {
        "brands": brands,
        "studies": studies,
        "audiences": audiences,
    }

    resp = await self._get("commitment-funnel", params=_to_url_params(params))

    def parse_entry(entry: JSONDict) -> _Params[Union[str, float]]:
        metrics = entry.pop("metrics")
        parsed = flatten_mapping(entry)
        parsed.update(
            {metric["key"]: metric["value"] for metric in metrics}  # type: ignore[arg-type]
        )
        return parsed  # type: ignore[return-value]

    with _raise_if_fails():
        payload = cast(List[JSONDict], resp["data"])
        return pd.DataFrame([parse_entry(entry) for entry in payload])

cost_of_entry(brand, study, audience=None, *, categories=None, collections=None, comparison_name=None) async

Retrieve results from the cost-of-entry endpoint

See https://developer.wppbav.com/docs/2.x/tools/cost-of-entry for more info.

Parameters:

Name	Type	Description	Default
brand	int	Brand ID	required
study	int	Study ID	required
audience	int	Audience ID, default None	None
categories	OptionalListOr[int]	Category ID or list of category IDs for the target category, default None	None
collections	OptionalListOr[int]	Collection ID or list of collections for the target collection, default None	None
comparison_name	str	Custom name to give the comparison, default None Default behavior is to use the category or collection name.	None

Returns:

Type	Description
Tuple[JSONDict, DataFrame]	A tuple containing a JSON dictionary of metadata and a Dataframe with the results

Raises:

Type	Description
ValueError	If category or collection are not specified, or if they are both specified
APIError	If an error occurs with the query

Source code in bavapi/tools.py

@validate_call
async def cost_of_entry(
    self,
    brand: int,
    study: int,
    audience: Optional[int] = None,
    *,
    categories: OptionalListOr[int] = None,
    collections: OptionalListOr[int] = None,
    comparison_name: Optional[str] = None,
) -> Tuple[JSONDict, pd.DataFrame]:
    """Retrieve results from the `cost-of-entry` endpoint

    See <https://developer.wppbav.com/docs/2.x/tools/cost-of-entry> for more info.

    Parameters
    ----------
    brand : int
        Brand ID
    study : int
        Study ID
    audience : int, optional
        Audience ID, default None
    categories : OptionalListOr[int], optional
        Category ID or list of category IDs for the target category, default None
    collections : OptionalListOr[int], optional
        Collection ID or list of collections for the target collection, default None
    comparison_name : str, optional
        Custom name to give the comparison, default None

        Default behavior is to use the category or collection name.

    Returns
    -------
    Tuple[JSONDict, pd.DataFrame]
        A tuple containing a JSON dictionary of metadata and a Dataframe with the results

    Raises
    ------
    ValueError
        If category or collection are not specified, or if they are both specified
    APIError
        If an error occurs with the query
    """
    if not bool(categories) ^ bool(collections):
        raise ValueError("Either categories OR collections must be specified.")

    params = {
        "brand": brand,
        "study": study,
        "audience": audience,
        "categories": categories,
        "collections": collections,
        "comparisonName": comparison_name,
    }

    resp = await self._get("cost-of-entry", params=_to_url_params(params))

    with _raise_if_fails():
        payload = cast(JSONDict, resp["data"])
        data = cast(List[JSONDict], payload.pop("data"))
        return payload, parse_response(data)

love_plus(brands, studies, audiences=None) async

Retrieve results from the love-plus endpoint

See https://developer.wppbav.com/docs/2.x/tools/love-plus for more info.

Parameters:

Name	Type	Description	Default
brands	ListOrValues[int]	Brand ID or list of brand IDs	required
studies	ListOrValues[int]	Study ID or list of study IDs	required
audiences	OptionalListOr[int]	Audience ID or list of audience IDs, default None	None

Returns:

Type	Description
DataFrame	Dataframe containing the results

Raises:

Type	Description
APIError	If an error occurs with the query

Source code in bavapi/tools.py

@validate_call
async def love_plus(
    self,
    brands: ListOrValues[int],
    studies: ListOrValues[int],
    audiences: OptionalListOr[int] = None,
) -> pd.DataFrame:
    """Retrieve results from the `love-plus` endpoint

    See <https://developer.wppbav.com/docs/2.x/tools/love-plus> for more info.

    Parameters
    ----------
    brands : ListOrValues[int]
        Brand ID or list of brand IDs
    studies : ListOrValues[int]
        Study ID or list of study IDs
    audiences : OptionalListOr[int], optional
        Audience ID or list of audience IDs, default None

    Returns
    -------
    pd.DataFrame
        Dataframe containing the results

    Raises
    ------
    APIError
        If an error occurs with the query
    """

    params: dict[str, OptionalSequenceOr[Union[str, int]]] = {
        "brands": brands,
        "studies": studies,
        "audiences": audiences,
    }

    resp = await self._get("love-plus", params=_to_url_params(params))

    def parse_entry(entry: JSONDict) -> _Params[Union[int, str, float]]:
        data = entry.pop("data")
        parsed = flatten_mapping(entry)
        parsed.update(
            {metric: val["value"] for metric, val in data.items()}  # type: ignore
        )
        return parsed  # type: ignore[return-value]

    with _raise_if_fails():
        payload = cast(List[JSONDict], resp["data"])
        return pd.DataFrame([parse_entry(entry) for entry in payload])

partnership_exchange_map(brands, studies, comparison_brands) async

Retrieve results from the partnership-exchange-map endpoint

See https://developer.wppbav.com/docs/2.x/tools/partnership-exchange-map for more info.

Parameters:

Name	Type	Description	Default
brands	ListOrValues[int]	Brand ID or list of brand IDs	required
studies	ListOrValues[int]	Study ID or list of study IDs	required
comparison_brands	ListOrValues[int]	Brand ID for comparison with the brand specified in `brands	required

Returns:

Type	Description
Tuple[JSONDict, DataFrame]	A tuple containing a JSON dictionary of metadata and a Dataframe with the results

Raises:

Type	Description
APIError	If an error occurs with the query

Source code in bavapi/tools.py

@validate_call
async def partnership_exchange_map(
    self,
    brands: ListOrValues[int],
    studies: ListOrValues[int],
    comparison_brands: ListOrValues[int],
) -> Tuple[JSONDict, pd.DataFrame]:
    """Retrieve results from the `partnership-exchange-map` endpoint

    See <https://developer.wppbav.com/docs/2.x/tools/partnership-exchange-map> for more info.

    Parameters
    ----------
    brands : ListOrValues[int]
        Brand ID or list of brand IDs
    studies : ListOrValues[int]
        Study ID or list of study IDs
    comparison_brands : ListOrValues[int]
        Brand ID for comparison with the brand specified in `brands

    Returns
    -------
    Tuple[JSONDict, pd.DataFrame]
        A tuple containing a JSON dictionary of metadata and a Dataframe with the results

    Raises
    ------
    APIError
        If an error occurs with the query
    """

    params: _Params[OptionalSequenceOr[Union[int, str]]] = {
        "brands": brands,
        "studies": studies,
        "comparison_brands": comparison_brands,
    }

    resp = await self._get(
        "partnership-exchange-map", params=_to_url_params(params)
    )

    with _raise_if_fails():
        payload = cast(JSONDict, resp["data"])
        data = cast(List[JSONDict], payload.pop("data"))
        return payload, parse_response(data)

swot(brands, studies, audiences=None, *, categories=None, collections=None, comparison_name=None) async

Retrieve results from the swot endpoint

[NOT IMPLEMENTED]

See https://developer.wppbav.com/docs/2.x/tools/swot for more info.

Parameters:

Name	Type	Description	Default
brands	ListOrValues[int]	Brand ID or list of brand IDs	required
studies	ListOrValues[int]	Study ID or list of study IDs	required
audiences	OptionalListOr[int]	Audience ID or list of audience IDs, default None	None
categories	OptionalListOr[int]	Category ID or list of category IDs for the target category, default None	None
collections	OptionalListOr[int]	Collection ID or list of collections for the target collection, default None	None
comparison_name	str	Custom name to give the comparison, default None Default behavior is to use "Category" or "Collection", depending on whether categories or collections were specified in the method call.	None

Returns:

Type	Description
Tuple[JSONDict, DataFrame]	A tuple containing a JSON dictionary of metadata and a Dataframe with the results

Raises:

Type	Description
ValueError	If category or collection are not specified, or if they are both specified
APIError	If an error occurs with the query

Source code in bavapi/tools.py

@validate_call
async def swot(
    self,
    brands: ListOrValues[int],
    studies: ListOrValues[int],
    audiences: OptionalListOr[int] = None,
    *,
    categories: OptionalListOr[int] = None,
    collections: OptionalListOr[int] = None,
    comparison_name: Optional[str] = None,
) -> Tuple[JSONDict, pd.DataFrame]:
    """Retrieve results from the `swot` endpoint

    [NOT IMPLEMENTED]

    See <https://developer.wppbav.com/docs/2.x/tools/swot> for more info.

    Parameters
    ----------
    brands : ListOrValues[int]
        Brand ID or list of brand IDs
    studies : ListOrValues[int]
        Study ID or list of study IDs
    audiences : OptionalListOr[int], optional
        Audience ID or list of audience IDs, default None
    categories : OptionalListOr[int], optional
        Category ID or list of category IDs for the target category, default None
    collections : OptionalListOr[int], optional
        Collection ID or list of collections for the target collection, default None
    comparison_name : str, optional
        Custom name to give the comparison, default None

        Default behavior is to use "Category" or "Collection", depending on whether
        categories or collections were specified in the method call.

    Returns
    -------
    Tuple[JSONDict, pd.DataFrame]
        A tuple containing a JSON dictionary of metadata and a Dataframe with the results

    Raises
    ------
    ValueError
        If category or collection are not specified, or if they are both specified
    APIError
        If an error occurs with the query
    """
    # if not bool(categories) ^ bool(collections):
    #     raise ValueError("Either categories OR collections must be specified.")

    # params = {
    #     "brands": brands,
    #     "studies": studies,
    #     "audiences": audiences,
    #     "categories": categories,
    #     "collections": collections,
    #     "comparisonName": comparison_name,
    # }

    # resp = await self._get("swot", params=_to_url_params(params))

    # with _raise_if_fails():
    #     payload = cast(JSONDict, resp["data"])
    #     data = cast(List[JSONDict], payload.pop("data"))
    #     return payload, parse_response(data)

    raise NotImplementedError

toplist_market(brands, studies, audiences=None, *, metrics=None, metric_keys=None) async

Retrieve results from the toplist-market endpoint

[NOT IMPLEMENTED]

See https://developer.wppbav.com/docs/2.x/tools/toplist-market for more info.

Parameters:

Name	Type	Description	Default
brands	ListOrValues[int]	Brand ID or list of brand IDs	required
studies	ListOrValues[int]	Study ID or list of study IDs	required
audiences	OptionalListOr[int]	Audience ID or list of audience IDs, default None	None
metrics	OptionalListOr[int]	Metric ID or list of metric IDs, default None	None
metric_keys	OptionalListOr[str]	Metric key or list of metric keys, default None	None

Returns:

Type	Description
DataFrame	Dataframe containing the results

Raises:

Type	Description
ValueError	If metrics or metric_keys are not specified, or if they are both specified
APIError	If an error occurs with the query

Source code in bavapi/tools.py

@validate_call
async def toplist_market(
    self,
    brands: ListOrValues[int],
    studies: ListOrValues[int],
    audiences: OptionalListOr[int] = None,
    *,
    metrics: OptionalListOr[int] = None,
    metric_keys: OptionalListOr[str] = None,
) -> pd.DataFrame:
    """Retrieve results from the `toplist-market` endpoint

    [NOT IMPLEMENTED]

    See <https://developer.wppbav.com/docs/2.x/tools/toplist-market> for more info.

    Parameters
    ----------
    brands : ListOrValues[int]
        Brand ID or list of brand IDs
    studies : ListOrValues[int]
        Study ID or list of study IDs
    audiences : OptionalListOr[int], optional
        Audience ID or list of audience IDs, default None
    metrics : OptionalListOr[int], optional
        Metric ID or list of metric IDs, default None
    metric_keys : OptionalListOr[str], optional
        Metric key or list of metric keys, default None

    Returns
    -------
    pd.DataFrame
        Dataframe containing the results

    Raises
    ------
    ValueError
        If metrics or metric_keys are not specified, or if they are both specified
    APIError
        If an error occurs with the query
    """

    # if not bool(metrics) ^ bool(metric_keys):
    #     raise ValueError("Either metrics OR metric_keys must be specified.")

    raise NotImplementedError