client

Asynchronous BAV API client interface.

Similar to requests.Session or httpx.AsyncClient (uses the latter as dependency).

Examples:

Create a client instance and make a request to the brands endpoint.

>>> async with bavapi.Client("TOKEN") as bav:
...     result = await bav.brands("Facebook")

A more complex query:

>>> from bavapi_refs import Audiences
>>> async with bavapi.Client("TOKEN") as bav:
...     bss = await bav.brandscape_data(
...         country_code="UK",
...         year_number=2022,
...         audiences=Audiences.ALL_ADULTS,
...     )

Multiple queries will share the client connection for better performance:

>>> async with bavapi.Client("TOKEN") as bav:
...     result1 = await bav.brands("Facebook")
...     result2 = await bav.brands("Instagram")

Use Client.raw_query (with bavapi.Query) for endpoints that aren't fully supported:

>>> query = bavapi.Query(filters=bavapi.filters.FountFilters(name="Meta"))
>>> async with bavapi.Client("TOKEN") as bav:
...     result = await bav.raw_query("companies", query=query)

Client(auth_token='', per_page=100, timeout=30.0, verify=True, user_agent='', *, client=None, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn')

Asynchronous API to interact with the WPPBAV Fount API.

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 ''	''
per_page	int	Default number of entries per page, default 100	100
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
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	HTTPClient	Authenticated async client from bavapi.http, default None If client is passed, all other parameters will be ignored.	None
verbose	bool	Set to False to disable progress bar, default True	True
batch_size	int	Size of batches to make requests with, default 10	10
n_workers	int	Number of workers to make requests, default 2	2
retries	int	Number of times to retry a request, default 3	3
on_errors	Literal['warn', 'raise']	Warn about failed requests or raise immediately on failure, default "warn"	'warn'

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 Client("TOKEN") as bav:
...     data = await bav.brands("Swatch")

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

>>> bav = Client("TOKEN")
>>> data = await bav.brands("Swatch")
>>> 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 Client("TOKEN", verbose=False) as bav:
...     resp1 = await bav.brands("Facebook")
...     resp2 = await bav.brands("Microsoft")

Source code in bavapi/client.py

def __init__(
    self,
    auth_token: str = "",
    per_page: int = 100,
    timeout: float = 30.0,
    verify: Union[bool, str] = True,
    user_agent: str = "",
    *,
    client: Optional[HTTPClientType] = None,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
) -> None:
    if client is not None:
        self._client = client
    else:
        if not auth_token:
            raise ValueError("You must provide `auth_token` or `client`.")
        self._client = HTTPClient(
            base_url=BASE_URL,
            per_page=per_page,
            timeout=timeout,
            verify=verify,
            headers={
                "Authorization": f"Bearer {auth_token}",
                "Accept": "application/json",
                "User-Agent": user_agent or USER_AGENT,
            },
            verbose=verbose,
            batch_size=batch_size,
            n_workers=n_workers,
            retries=retries,
            on_errors=on_errors,
        )

batch_size: int property writable

Size of batches to make requests with.

n_workers: int property writable

Number of workers to make requests.

on_errors: Literal['warn', 'raise'] property writable

Raise immediately on errors or warn at the end of the request.

per_page: int property writable

Default number of items to retrieve per page.

retries: int property writable

Number of times to retry a request.

verbose: bool property writable

Show progress bar when making requests.

aclose() async

Close existing HTTP connections.

Source code in bavapi/client.py

async def aclose(self) -> None:
    """Close existing HTTP connections."""
    return await self._client.aclose()

audience_groups(name=None, *, audience_group_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount audience-groups endpoint.

Parameters:

Name	Type	Description	Default
name	str	Search audiences by name, default None	None
audience_group_id	int	Fount audience group ID, default None If an audience group ID is provided, only that audience group will be returned	None
filters	AudienceGroupsFilters or dict[str, Any]	AudienceGroupsFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[AudienceGroupsFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with audience-groups endpoint results.

Source code in bavapi/client.py

async def audience_groups(
    self,
    name: Optional[str] = None,
    *,
    audience_group_id: Optional[int] = None,
    filters: OptionalFiltersOrMapping[_filters.AudienceGroupsFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.AudienceGroupsFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `audience-groups` endpoint.

    Parameters
    ----------
    name : str, optional
        Search audiences by name, default None
    audience_group_id : int, optional
        Fount audience group ID, default None

        If an audience group ID is provided, only that audience group will be returned
    filters : AudienceGroupsFilters or dict[str, Any], optional
        AudienceGroupsFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[AudienceGroupsFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `audience-groups` endpoint results.
    """
    filters = _filters.AudienceGroupsFilters.ensure(
        filters,
        name=name,
    )

    query = Query.ensure(
        query,
        id=audience_group_id,
        filters=filters,
        fields=fields,
        include=include,
        **kwargs,
    )

    items = await self._client.query("audience-groups", query)

    return parse_response(items, expand=stack_data)

audiences(name=None, active=0, public=0, *, audience_id=None, private=0, groups=None, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount audiences endpoint.

Parameters:

Name	Type	Description	Default
name	str	Search audiences by name, default None	None
active	Literal[0, 1]	Return active audiences only if set to 1, default 0	0
public	Literal[0, 1]	Return active audiences only if set to 1, default 0	0
audience_id	int	Fount audience ID, default None If an audience ID is provided, only that audience will be returned	None
private	Literal[0, 1]	Return inactive audiences only if set to 1, default 0	0
groups	int or list[int]	Audience group ID or list of audience group IDs, default None	None
filters	AudiencesFilters or dict[str, Any]	AudiencesFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[AudiencesFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with audiences endpoint results.

Source code in bavapi/client.py

async def audiences(
    self,
    name: Optional[str] = None,
    active: Literal[0, 1] = 0,
    public: Literal[0, 1] = 0,
    *,
    audience_id: Optional[int] = None,
    private: Literal[0, 1] = 0,
    groups: OptionalListOr[int] = None,
    filters: OptionalFiltersOrMapping[_filters.AudiencesFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.AudiencesFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `audiences` endpoint.

    Parameters
    ----------
    name : str, optional
        Search audiences by name, default None
    active : Literal[0, 1], optional
        Return active audiences only if set to `1`, default 0
    public : Literal[0, 1], optional
        Return active audiences only if set to `1`, default 0
    audience_id : int, optional
        Fount audience ID, default None

        If an audience ID is provided, only that audience will be returned
    private : Literal[0, 1], optional
        Return inactive audiences only if set to `1`, default 0
    groups : int or list[int], optional
        Audience group ID or list of audience group IDs, default None
    filters : AudiencesFilters or dict[str, Any], optional
        AudiencesFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[AudiencesFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `audiences` endpoint results.
    """
    filters = _filters.AudiencesFilters.ensure(
        filters,
        name=name,
        active=active,
        public=public,
        private=private,
        groups=groups,
    )

    query = Query.ensure(
        query,
        id=audience_id,
        filters=filters,
        fields=fields,
        include=include,
        **kwargs,
    )

    items = await self._client.query("audiences", query)

    return parse_response(items, expand=stack_data)

brand_metric_groups(name=None, active=0, *, group_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount brand-metric-groups endpoint.

Parameters:

Name	Type	Description	Default
name	str	Search brand metric groups by name, default None	None
active	Literal[0, 1]	Return active brand metric groups only if set to 1, default 0	0
group_id	int	Fount metric group ID, default None If a metric group ID is provided, only that metric group will be returned	None
filters	BrandMetricGroupsFilters or dict[str, Any]	BrandMetricGroupsFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[BrandMetricGroupsFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with brand-metric-groups endpoint results.

Source code in bavapi/client.py

async def brand_metric_groups(
    self,
    name: Optional[str] = None,
    active: Literal[0, 1] = 0,
    *,
    group_id: Optional[int] = None,
    filters: OptionalFiltersOrMapping[_filters.BrandMetricGroupsFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.BrandMetricGroupsFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `brand-metric-groups` endpoint.

    Parameters
    ----------
    name : str, optional
        Search brand metric groups by name, default None
    active : Literal[0, 1], optional
        Return active brand metric groups only if set to `1`, default 0
    group_id : int, optional
        Fount metric group ID, default None

        If a metric group ID is provided, only that metric group will be returned
    filters : BrandMetricGroupsFilters or dict[str, Any], optional
        BrandMetricGroupsFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[BrandMetricGroupsFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `brand-metric-groups` endpoint results.
    """
    filters = _filters.BrandMetricGroupsFilters.ensure(
        filters,
        name=name,
        active=active,
    )

    query = Query.ensure(
        query,
        id=group_id,
        filters=filters,
        fields=fields,
        include=include,
        **kwargs,
    )

    items = await self._client.query("brand-metric-groups", query)

    return parse_response(items, expand=stack_data)

brand_metrics(name=None, active=0, public=0, *, metric_id=None, private=0, groups=None, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount brand-metrics endpoint.

Parameters:

Name	Type	Description	Default
name	str	Search brand metrics by name, default None	None
active	Literal[0, 1]	Return active brand metrics only if set to 1, default 0	0
public	Literal[0, 1]	Return active brand metrics only if set to 1, default 0	0
metric_id	int	Fount metric ID, default None If a metric ID is provided, only that metric will be returned	None
private	Literal[0, 1]	Return inactive brand metrics only if set to 1, default 0	0
groups	int or list[int]	Brand metrics group ID or list of brand metrics group IDs, default None	None
filters	BrandMetricsFilters or dict[str, Any]	BrandMetricsFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[BrandMetricsFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with brand-metrics endpoint results.

Source code in bavapi/client.py

async def brand_metrics(
    self,
    name: Optional[str] = None,
    active: Literal[0, 1] = 0,
    public: Literal[0, 1] = 0,
    *,
    metric_id: Optional[int] = None,
    private: Literal[0, 1] = 0,
    groups: OptionalListOr[int] = None,
    filters: OptionalFiltersOrMapping[_filters.BrandMetricsFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.BrandMetricsFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `brand-metrics` endpoint.

    Parameters
    ----------
    name : str, optional
        Search brand metrics by name, default None
    active : Literal[0, 1], optional
        Return active brand metrics only if set to `1`, default 0
    public : Literal[0, 1], optional
        Return active brand metrics only if set to `1`, default 0
    metric_id : int, optional
        Fount metric ID, default None

        If a metric ID is provided, only that metric will be returned
    private : Literal[0, 1], optional
        Return inactive brand metrics only if set to `1`, default 0
    groups : int or list[int], optional
        Brand metrics group ID or list of brand metrics group IDs, default None
    filters : BrandMetricsFilters or dict[str, Any], optional
        BrandMetricsFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[BrandMetricsFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `brand-metrics` endpoint results.
    """
    filters = _filters.BrandMetricsFilters.ensure(
        filters,
        name=name,
        active=active,
        public=public,
        private=private,
        groups=groups,
    )

    query = Query.ensure(
        query,
        id=metric_id,
        filters=filters,
        fields=fields,
        include=include,
        **kwargs,
    )

    items = await self._client.query("brand-metrics", query)

    return parse_response(items, expand=stack_data)

brands(name=None, country_codes=None, year_numbers=None, *, brand_id=None, studies=None, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount brands endpoint.

Parameters:

Name	Type	Description	Default
name	str	Search brands by name, default None	None
country_codes	OptionalListOr[str]	ISO-3166-1 alpha-2 country codes, default None	None
year_numbers	int or list[int]	Study years, default None	None
brand_id	int	Fount brand ID, default None If a brand ID is provided, only that brand will be returned	None
studies	int or list[int]	Fount study IDs, default None	None
filters	BrandsFilters or dict[str, Any]	BrandsFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[BrandsFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with brands endpoint results.

Source code in bavapi/client.py

async def brands(
    self,
    name: Optional[str] = None,
    country_codes: OptionalListOr[str] = None,
    year_numbers: OptionalListOr[int] = None,
    *,
    brand_id: Optional[int] = None,
    studies: OptionalListOr[int] = None,
    filters: OptionalFiltersOrMapping[_filters.BrandsFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.BrandsFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `brands` endpoint.

    Parameters
    ----------
    name : str, optional
        Search brands by name, default None
    country_codes: str or list[str], optional
        ISO-3166-1 alpha-2 country codes, default None
    year_numbers : int or list[int], optional
        Study years, default None
    brand_id : int, optional
        Fount brand ID, default None

        If a brand ID is provided, only that brand will be returned
    studies : int or list[int], optional
        Fount study IDs, default None
    filters : BrandsFilters or dict[str, Any], optional
        BrandsFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[BrandsFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `brands` endpoint results.
    """
    filters = _filters.BrandsFilters.ensure(
        filters,
        name=name,
        country_codes=country_codes,
        year_numbers=year_numbers,
        studies=studies,
    )

    query = Query.ensure(
        query,
        id=brand_id,
        filters=filters,
        fields=fields,
        include=include,
        **kwargs,
    )

    items = await self._client.query("brands", query)

    return parse_response(items, expand=stack_data)

brandscape_data(country_code=None, year_number=None, audiences=None, brand_name=None, *, studies=None, filters=None, fields=None, include=None, metric_keys=None, metric_group_keys=None, query=None, stack_data=False, **kwargs) async

Query the Fount brandscape-data endpoint.

This endpoint requires at least one of the following combinations of filters:

• Study + Audience + Brand + Category
• Country + Year + Audience
• Brand + Audience + Country + Year

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.

If you use Country or Year filters, you must use both filters together.

An audience filter is also highly recommended, as otherwise the API will return data for all audiences (there are more than 100 standard audiences).

The Audiences class is provided to make it easier to filter audiences.

Note that this endpoint has a default set of include resources: - brand - study - category - audience

Any additional valid includes will be added to the default set.

Also note that due to a name clash in the "brand" include, brand columns will be prefixed with "global_". Thus, these columns will refer to the global brand, while the brand_name column will refer to the local brand/spelling.

If any of the default includes are used in include, then only that resource will be retrieved. This is to allow requesting individual includes if they are part of the default.

To suppress default includes, set include to "no_default".

Parameters:

Name	Type	Description	Default
country_code	str or list[str]	ISO-3166-1 alpha-2 country codes, default None	None
year_number	int or list[int]	Study years, default None	None
audiences	int or list[int]	Audiences to retrieve by audience ID, default None The Audiences class can help with this filter.	None
brand_name	str	Search by brand name, default None	None
studies	int or list[int]	Fount studies IDs, default None	None
filters	BrandscapeFilters or dict[str, Any]	BrandscapeFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
metric_keys	OptionalListOr[str]	Key or list of keys for the metrics included in the response, default None	None
metric_group_keys	OptionalListOr[str]	Key or list of keys for the metric groups included in the response, default None Currently, this parameter is only available for the brandscape-data endpoint.	None
query	Query[BrandscapeFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with brandscape-data endpoint results.

Raises:

Type	Description
ValidationError	If used with an invalid combination of parameters (see above)

Source code in bavapi/client.py

async def brandscape_data(
    self,
    country_code: OptionalListOr[str] = None,
    year_number: OptionalListOr[int] = None,
    audiences: OptionalListOr[int] = None,
    brand_name: Optional[str] = None,
    *,
    studies: OptionalListOr[int] = None,
    filters: OptionalFiltersOrMapping[_filters.BrandscapeFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    metric_keys: OptionalListOr[str] = None,
    metric_group_keys: OptionalListOr[str] = None,
    query: Optional[Query[_filters.BrandscapeFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `brandscape-data` endpoint.

    This endpoint requires at least one of the following combinations of filters:

    - Study + Audience + Brand + Category
    - Country + Year + Audience
    - Brand + Audience + Country + Year

    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.

    If you use Country or Year filters, you must use both filters together.

    An audience filter is also highly recommended, as otherwise the API will return
    data for all audiences (there are more than 100 standard audiences).

    The `Audiences` class is provided to make it easier to filter audiences.

    Note that this endpoint has a default set of `include` resources:
    - `brand`
    - `study`
    - `category`
    - `audience`

    Any additional valid includes will be added to the default set.

    Also note that due to a name clash in the "brand" `include`, brand columns
    will be prefixed with `"global_"`. Thus, these columns will refer to the global
    brand, while the `brand_name` column will refer to the local brand/spelling.

    If any of the default includes are used in `include`, then only that resource
    will be retrieved. This is to allow requesting individual includes if they are
    part of the default.

    To suppress default includes, set `include` to `"no_default"`.

    Parameters
    ----------
    country_code : str or list[str], optional
        ISO-3166-1 alpha-2 country codes, default None
    year_number : int or list[int], optional
        Study years, default None
    audiences : int or list[int], optional
        Audiences to retrieve by audience ID, default None

        The `Audiences` class can help with this filter.
    brand_name : str, optional
        Search by brand name, default None
    studies : int or list[int], optional
        Fount studies IDs, default None
    filters : BrandscapeFilters or dict[str, Any], optional
        BrandscapeFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    metric_keys: str or list[str], optional
        Key or list of keys for the metrics included in the response, default None
    metric_group_keys: str or list[str], optional
        Key or list of keys for the metric groups included in the response, default None

        Currently, this parameter is only available for the `brandscape-data` endpoint.
    query : Query[BrandscapeFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `brandscape-data` endpoint results.

    Raises
    ------
    ValidationError
        If used with an invalid combination of parameters (see above)
    """
    filters = _filters.BrandscapeFilters.ensure(
        filters,
        country_code=country_code,
        year_number=year_number,
        audiences=audiences,
        brand_name=brand_name,
        studies=studies,
    )

    query = Query.ensure(
        query,
        filters=filters,
        fields=fields,
        include=_default_include(include, BRANDSCAPE_DEFAULTS),
        metric_keys=metric_keys,
        metric_group_keys=metric_group_keys,
        **kwargs,
    )

    items = await self._client.query("brandscape-data", query)

    # Prefix 'global' to avoid clashing with 'brand_name' on 'brand' includes
    return parse_response(items, "global", expand=stack_data)

categories(name=None, sectors=None, *, category_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount categories endpoint.

Note that this endpoint has a default set of include resources: - sector

Any additional valid includes will be added to the default set.

If any of the default includes are used in include, then only that resource will be retrieved. This is to allow requesting individual includes if they are part of the default.

Parameters:

Name	Type	Description	Default
name	str	Search categories by name, default None	None
sectors	int or list[int]	Filter categories by sector ID, default None	None
category_id	int	Fount category ID, default None If a category ID is provided, only that category will be returned	None
filters	CategoriesFilters or dict[str, Any]	CategoriesFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[CategoriesFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with categories endpoint results.

Source code in bavapi/client.py

async def categories(
    self,
    name: Optional[str] = None,
    sectors: OptionalListOr[int] = None,
    *,
    category_id: Optional[int] = None,
    filters: OptionalFiltersOrMapping[_filters.CategoriesFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.CategoriesFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `categories` endpoint.

    Note that this endpoint has a default set of `include` resources:
    - `sector`

    Any additional valid includes will be added to the default set.

    If any of the default includes are used in `include`, then only that resource
    will be retrieved. This is to allow requesting individual includes if they are
    part of the default.

    Parameters
    ----------
    name : str, optional
        Search categories by name, default None
    sectors : int or list[int], optional
        Filter categories by sector ID, default None
    category_id : int, optional
        Fount category ID, default None

        If a category ID is provided, only that category will be returned
    filters : CategoriesFilters or dict[str, Any], optional
        CategoriesFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[CategoriesFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `categories` endpoint results.
    """
    filters = _filters.CategoriesFilters.ensure(
        filters,
        name=name,
        sectors=sectors,
    )

    query = Query.ensure(
        query,
        id=category_id,
        filters=filters,
        fields=fields,
        include=_default_include(include, CATEGORIES_DEFAULTS),
        **kwargs,
    )

    items = await self._client.query("categories", query)

    return parse_response(items, expand=stack_data)

cities(name=None, capitals=0, countries=None, in_best_countries=None, *, city_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount cities endpoint.

Parameters:

Name	Type	Description	Default
name	str	Search cities by name, default None	None
capitals	Literal[0, 1]	Return capitals only, default 0	0
countries	OptionalListOr[int]	Fount country ID or list of country IDs, default None	None
in_best_countries	OptionalListOr[int]	Year number(s) of the Best Countries reports, default None Only return cities that appear in the Best Countries reports for those years	None
city_id	int	Fount city ID, default None If a city ID is provided, only that city will be returned	None
filters	CitiesFilters or dict[str, Any]	CitiesFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[CitiesFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with cities endpoint results.

Source code in bavapi/client.py

async def cities(
    self,
    name: Optional[str] = None,
    capitals: Literal[0, 1] = 0,
    countries: OptionalListOr[int] = None,
    in_best_countries: OptionalListOr[int] = None,
    *,
    city_id: Optional[int] = None,
    filters: OptionalFiltersOrMapping[_filters.CitiesFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.CitiesFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `cities` endpoint.

    Parameters
    ----------
    name : str, optional
        Search cities by name, default None
    capitals: Literal[0, 1], optional
        Return capitals only, default 0
    countries: int or list[int], optional
        Fount country ID or list of country IDs, default None
    in_best_countries: int or list[int], optional
        Year number(s) of the Best Countries reports, default None

        Only return cities that appear in the Best Countries reports for those years
    city_id : int, optional
        Fount city ID, default None

        If a city ID is provided, only that city will be returned
    filters : CitiesFilters or dict[str, Any], optional
        CitiesFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[CitiesFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `cities` endpoint results.
    """
    filters = _filters.CitiesFilters.ensure(
        filters,
        name=name,
        capitals=capitals,
        countries=countries,
        in_best_countries=in_best_countries,
    )

    query = Query.ensure(
        query,
        id=city_id,
        filters=filters,
        fields=fields,
        include=include,
        **kwargs,
    )

    items = await self._client.query("cities", query)

    return parse_response(items, expand=stack_data)

collections(name=None, public=0, *, collection_id=None, shared_with_me=0, mine=0, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount collections endpoint.

Parameters:

Name	Type	Description	Default
name	str	Search collections by name, default None	None
public	Literal[0, 1]	Return public collections only, default 0	0
collection_id	int	Fount collection ID, default None If a collection ID is provided, only that collection will be returned	None
shared_with_me	Literal[0, 1]	Only return collections that have been shared with the user, default 0	0
mine	Literal[0, 1]	Only return collections created by the user, default 0	0
filters	CollectionsFilters or dict[str, Any]	CollectionsFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[CollectionsFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with collections endpoint results.

Source code in bavapi/client.py

async def collections(
    self,
    name: Optional[str] = None,
    public: Literal[0, 1] = 0,
    *,
    collection_id: Optional[int] = None,
    shared_with_me: Literal[0, 1] = 0,
    mine: Literal[0, 1] = 0,
    filters: OptionalFiltersOrMapping[_filters.CollectionsFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.CollectionsFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `collections` endpoint.

    Parameters
    ----------
    name : str, optional
        Search collections by name, default None
    public : Literal[0, 1], optional
        Return public collections only, default 0
    collection_id : int, optional
        Fount collection ID, default None

        If a collection ID is provided, only that collection will be returned
    shared_with_me : Literal[0, 1], optional
        Only return collections that have been shared with the user, default 0
    mine : Literal[0, 1], optional
        Only return collections created by the user, default 0
    filters : CollectionsFilters or dict[str, Any], optional
        CollectionsFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[CollectionsFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `collections` endpoint results.
    """
    filters = _filters.CollectionsFilters.ensure(
        filters,
        name=name,
        public=public,
        shared_with_me=shared_with_me,
        mine=mine,
    )

    query = Query.ensure(
        query,
        id=collection_id,
        filters=filters,
        fields=fields,
        include=include,
        **kwargs,
    )

    items = await self._client.query("collections", query)

    return parse_response(items, expand=stack_data)

companies(name=None, public=0, private=0, brands=None, *, company_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount companies endpoint.

Parameters:

Name	Type	Description	Default
name	str	Search companies by name, default None	None
public	Literal[0, 1]	Return public (listed) companies only, default 0	0
private	Literal[0, 1]	Return private (not listed) companies only, default 0	0
brands	OptionalListOr[int]	Fount brand ID or list of brand IDs, default None Only return companies that own the specified brands	None
company_id	int	Fount company ID, default None If a company ID is provided, only that company will be returned	None
filters	CompaniesFilters or dict[str, Any]	CompaniesFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[CompaniesFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with companies endpoint results.

Source code in bavapi/client.py

async def companies(
    self,
    name: Optional[str] = None,
    public: Literal[0, 1] = 0,
    private: Literal[0, 1] = 0,
    brands: OptionalListOr[int] = None,
    *,
    company_id: Optional[int] = None,
    filters: OptionalFiltersOrMapping[_filters.CompaniesFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.CompaniesFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `companies` endpoint.

    Parameters
    ----------
    name : str, optional
        Search companies by name, default None
    public: Literal[0, 1], optional
        Return public (listed) companies only, default 0
    private: Literal[0, 1], optional
        Return private (not listed) companies only, default 0
    brands: int or list[int], optional
        Fount brand ID or list of brand IDs, default None

        Only return companies that own the specified brands
    company_id : int, optional
        Fount company ID, default None

        If a company ID is provided, only that company will be returned
    filters : CompaniesFilters or dict[str, Any], optional
        CompaniesFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[CompaniesFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `companies` endpoint results.
    """
    filters = _filters.CompaniesFilters.ensure(
        filters,
        name=name,
        public=public,
        private=private,
        brands=brands,
    )

    query = Query.ensure(
        query,
        id=company_id,
        filters=filters,
        fields=fields,
        include=include,
        **kwargs,
    )

    items = await self._client.query("companies", query)

    return parse_response(items, expand=stack_data)

countries(name=None, active=0, regions=None, with_studies=0, *, country_id=None, with_recent_studies=None, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount countries endpoint.

Parameters:

Name	Type	Description	Default
name	str	Search countries by name, default None	None
active	Literal[0, 1]	Return active countries only, default 0	0
regions	OptionalListOr[int]	Fount region ID or list of region IDs, default None	None
with_studies	Literal[0, 1]	Only return countries which have had a BAV study, default 0	0
with_recent_studies	Optional[int]	Years of recency of studies in a specific country, default None Only return countries which have had a BAV study in the past X years	None
country_id	int	Fount country ID, default None If a country ID is provided, only that country will be returned	None
filters	CountriesFilters or dict[str, Any]	CountriesFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[CountriesFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with countries endpoint results.

Source code in bavapi/client.py

async def countries(
    self,
    name: Optional[str] = None,
    active: Literal[0, 1] = 0,
    regions: OptionalListOr[int] = None,
    with_studies: Literal[0, 1] = 0,
    *,
    country_id: Optional[int] = None,
    with_recent_studies: Optional[int] = None,
    filters: OptionalFiltersOrMapping[_filters.CountriesFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.CountriesFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `countries` endpoint.

    Parameters
    ----------
    name : str, optional
        Search countries by name, default None
    active : Literal[0, 1], optional
        Return active countries only, default 0
    regions: int or list[int], optional
        Fount region ID or list of region IDs, default None
    with_studies: Literal[0, 1], optional
        Only return countries which have had a BAV study, default 0
    with_recent_studies: int, optional
        Years of recency of studies in a specific country, default None

        Only return countries which have had a BAV study in the past X years
    country_id : int, optional
        Fount country ID, default None

        If a country ID is provided, only that country will be returned
    filters : CountriesFilters or dict[str, Any], optional
        CountriesFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[CountriesFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `countries` endpoint results.
    """
    filters = _filters.CountriesFilters.ensure(
        filters,
        name=name,
        active=active,
        regions=regions,
        with_studies=with_studies,
        with_recent_studies=with_recent_studies,
    )

    query = Query.ensure(
        query,
        id=country_id,
        filters=filters,
        fields=fields,
        include=include,
        **kwargs,
    )

    items = await self._client.query("countries", query)

    return parse_response(items, expand=stack_data)

raw_query(endpoint, query) async

Perform a raw GET query to the WPPBAV Fount API, returning the response JSON data instead of a pandas DataFrame.

Parameters:

Name	Type	Description	Default
endpoint	str	Endpoint name	required
query	Query	bavapi.Query object with query parameters.	required

Returns:

Type	Description
list[dict[str, Any]]	List of JSON response data

Source code in bavapi/client.py

async def raw_query(self, endpoint: str, query: Query[F]) -> List[JSONDict]:
    """Perform a raw GET query to the WPPBAV Fount API, returning
    the response JSON data instead of a `pandas` DataFrame.

    Parameters
    ----------
    endpoint : str
        Endpoint name
    query : Query
        bavapi.Query object with query parameters.

    Returns
    -------
    list[dict[str, Any]]
        List of JSON response data
    """
    return list(await self._client.query(endpoint, query))

regions(name=None, *, region_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount regions endpoint.

Parameters:

Name	Type	Description	Default
name	str	Search regions by name, default None	None
region_id	int	Fount region ID, default None If a region ID is provided, only that region will be returned	None
filters	RegionsFilters or dict[str, Any]	RegionsFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[RegionsFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with regions endpoint results.

Source code in bavapi/client.py

async def regions(
    self,
    name: Optional[str] = None,
    *,
    region_id: Optional[int] = None,
    filters: OptionalFiltersOrMapping[_filters.RegionsFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.RegionsFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `regions` endpoint.

    Parameters
    ----------
    name : str, optional
        Search regions by name, default None
    region_id : int, optional
        Fount region ID, default None

        If a region ID is provided, only that region will be returned
    filters : RegionsFilters or dict[str, Any], optional
        RegionsFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[RegionsFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `regions` endpoint results.
    """
    filters = _filters.RegionsFilters.ensure(
        filters,
        name=name,
    )

    query = Query.ensure(
        query,
        id=region_id,
        filters=filters,
        fields=fields,
        include=include,
        **kwargs,
    )

    items = await self._client.query("regions", query)

    return parse_response(items, expand=stack_data)

sectors(name=None, in_most_influential=0, *, sector_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount sectors endpoint.

Parameters:

Name	Type	Description	Default
name	str	Search sectors by name, default None	None
in_most_influential	Literal[0, 1]	Sectors that are part of the Most Influential lists, default 0	0
sector_id	int	Fount sectors ID, default None If a sector ID is provided, only that sector will be returned	None
filters	SectorsFilters or dict[str, Any]	SectorsFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[SectorsFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with sectors endpoint results.

Source code in bavapi/client.py

async def sectors(
    self,
    name: Optional[str] = None,
    in_most_influential: Literal[0, 1] = 0,
    *,
    sector_id: Optional[int] = None,
    filters: OptionalFiltersOrMapping[_filters.SectorsFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.SectorsFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `sectors` endpoint.

    Parameters
    ----------
    name : str, optional
        Search sectors by name, default None
    in_most_influential : Literal[0, 1], optional
        Sectors that are part of the Most Influential lists, default 0
    sector_id : int, optional
        Fount sectors ID, default None

        If a sector ID is provided, only that sector will be returned
    filters : SectorsFilters or dict[str, Any], optional
        SectorsFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[SectorsFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `sectors` endpoint results.
    """
    filters = _filters.SectorsFilters.ensure(
        filters,
        name=name,
        in_most_influential=in_most_influential,
    )

    query = Query.ensure(
        query,
        id=sector_id,
        filters=filters,
        fields=fields,
        include=include,
        **kwargs,
    )

    items = await self._client.query("sectors", query)

    return parse_response(items, expand=stack_data)

studies(country_codes=None, year_numbers=None, full_year=0, released=0, bav_study=0, *, study_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount studies endpoint.

Parameters:

Name	Type	Description	Default
country_codes	OptionalListOr[str]	ISO-3166-1 alpha-2 country codes, default None	None
year_numbers	int or list[int]	Study years, default None	None
full_year	Literal[0, 1]	Include or exclude studies which are not "full year" studies, such as US quarterly studies or special studies, default 0 A value of 1 will filter non-full-year studies.	0
released	Literal[0, 1]	Return released studies when set to 1, default 0	0
bav_study	Literal[0, 1]	Return full BAV studies when set to 1, default 0	0
study_id	int	Fount study ID, default None If a study ID is provided, only that study will be returned	None
filters	StudiesFilters or dict[str, Any]	StudiesFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[StudiesFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with studies endpoint results.

Source code in bavapi/client.py

async def studies(
    self,
    country_codes: OptionalListOr[str] = None,
    year_numbers: OptionalListOr[int] = None,
    full_year: Literal[0, 1] = 0,
    released: Literal[0, 1] = 0,
    bav_study: Literal[0, 1] = 0,
    *,
    study_id: Optional[int] = None,
    filters: OptionalFiltersOrMapping[_filters.StudiesFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.StudiesFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `studies` endpoint.

    Parameters
    ----------
    country_codes: str or list[str], optional
        ISO-3166-1 alpha-2 country codes, default None
    year_numbers : int or list[int], optional
        Study years, default None
    full_year : Literal[0, 1], optional
        Include or exclude studies which are not "full year" studies,
        such as US quarterly studies or special studies, default 0

        A value of 1 will filter non-full-year studies.
    released : Literal[0, 1], optional
        Return released studies when set to `1`, default 0
    bav_study : Literal[0, 1], optional
        Return full BAV studies when set to `1`, default 0
    study_id : int, optional
        Fount study ID, default None
        If a study ID is provided, only that study will be returned
    filters : StudiesFilters or dict[str, Any], optional
        StudiesFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[StudiesFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `studies` endpoint results.
    """
    filters = _filters.StudiesFilters.ensure(
        filters,
        country_codes=country_codes,
        year_numbers=year_numbers,
        full_year=full_year,
        released=released,
        bav_study=bav_study,
    )

    query = Query.ensure(
        query,
        id=study_id,
        filters=filters,
        fields=fields,
        include=include,
        **kwargs,
    )

    items = await self._client.query("studies", query)

    return parse_response(items, expand=stack_data)

years(year=None, *, year_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, **kwargs) async

Query the Fount years endpoint.

Parameters:

Name	Type	Description	Default
year	int	Search years by year number, default None	None
year_id	int	Fount year ID, default None If a year ID is provided, only that year will be returned	None
filters	YearsFilters or dict[str, Any]	YearsFilters object or dictionary of filter parameters, default None	None
fields	str or list[str]	Fields to retrieve in API response, default None Only specified fields are returned. If fields is None, all fields are returned.	None
include	str or list[str]	Additional resources to include in API response, default None	None
query	Query[YearsFilters]	Query object to perform request with, default None If query is used, all parameters listed before query will be ignored.	None
stack_data	bool	Whether to expand nested lists into new dictionaries, default False	False
**kwargs	Unpack[CommonQueryParams]	Additional parameters to pass to the Query. See Other Parameters. For any filters, use the filters parameter.	{}

Other Parameters:

Name	Type	Description
page	int	Page number to fetch, default None
per_page	int	Number of results per page, default None
max_pages	int	Max number of results to return, default None
sort	str	Sort response by field, default None To sort in descending (highest first) order, use a - before the field name: sort="-differentiation_rank" Sorts by item ID by default.

Returns:

Type	Description
DataFrame	DataFrame with years endpoint results.

Source code in bavapi/client.py

async def years(
    self,
    year: Optional[int] = None,
    *,
    year_id: Optional[int] = None,
    filters: OptionalFiltersOrMapping[_filters.YearsFilters] = None,
    fields: OptionalListOr[str] = None,
    include: OptionalListOr[str] = None,
    query: Optional[Query[_filters.YearsFilters]] = None,
    stack_data: bool = False,
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `years` endpoint.

    Parameters
    ----------
    year : int, optional
        Search years by year number, default None
    year_id : int, optional
        Fount year ID, default None

        If a year ID is provided, only that year will be returned
    filters : YearsFilters or dict[str, Any], optional
        YearsFilters object or dictionary of filter parameters, default None
    fields : str or list[str], optional
        Fields to retrieve in API response, default None

        Only specified fields are returned.
        If `fields` is None, all fields are returned.
    include : str or list[str], optional
        Additional resources to include in API response, default None
    query : Query[YearsFilters], optional
        Query object to perform request with, default None

        If query is used, all parameters listed before `query` will be ignored.
    stack_data : bool, optional
        Whether to expand nested lists into new dictionaries, default False
    **kwargs
        Additional parameters to pass to the Query. See `Other Parameters`.
        For any filters, use the `filters` parameter.

    Other Parameters
    ----------------
    page : int, optional
        Page number to fetch, default None
    per_page : int, optional
        Number of results per page, default None
    max_pages : int, optional
        Max number of results to return, default None
    sort : str, optional
        Sort response by field, default None

        To sort in descending (highest first) order, use a `-` before the field name:

        `sort="-differentiation_rank"`

        Sorts by item ID by default.

    Returns
    -------
    pandas.DataFrame
        DataFrame with `years` endpoint results.
    """
    filters = _filters.YearsFilters.ensure(
        filters,
        year=year,
    )

    query = Query.ensure(
        query,
        id=year_id,
        filters=filters,
        fields=fields,
        include=include,
        **kwargs,
    )

    items = await self._client.query("years", query)

    return parse_response(items, expand=stack_data)