sync

Top level functions to perform queries to the Fount.

You will need your BAV API token to use these functions.

Examples:

Use top level functions for one-off downloads:

>>> import bavapi
>>> result = bavapi.brands("TOKEN", "Facebook")  # Replace TOKEN with your API key

A more complex query:

>>> from bavapi_refs import Audiences
>>> bss = bavapi.brandscape_data(
...     "TOKEN",  # Replace TOKEN with your API key
...     country_code="UK",
...     year_number=2022,
...     audiences=Audiences.ALL_ADULTS,
... )

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

>>> query = bavapi.Query(filters=bavapi.filters.FountFilters(name="Meta"))
>>> result = bavapi.raw_query("companies", query=query)

If you want to make multiple requests or embed bavapi into applications, consider using the bavapi.Client interface.

audience_groups(token, name=None, *, audience_group_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount audience-groups endpoint.

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def audience_groups(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `audience-groups` endpoint.

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.audience_groups(
            name,
            audience_group_id=audience_group_id,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

audiences(token, name=None, active=0, public=0, *, audience_id=None, private=0, groups=None, filters=None, fields=None, include=None, query=None, stack_data=False, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount audiences endpoint.

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def audiences(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `audiences` endpoint.

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.audiences(
            name,
            active,
            public,
            audience_id=audience_id,
            private=private,
            groups=groups,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

brand_metric_groups(token, name=None, active=0, *, group_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount brand-metric-groups endpoint.

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
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 brand 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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def brand_metric_groups(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `brand-metric-groups` endpoint.

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    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 brand 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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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.
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.brand_metric_groups(
            name,
            active,
            group_id=group_id,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

brand_metrics(token, name=None, active=0, public=0, *, metric_id=None, private=0, groups=None, filters=None, fields=None, include=None, query=None, stack_data=False, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount brand-metrics endpoint.

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def brand_metrics(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `brand-metrics` endpoint.

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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.
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.brand_metrics(
            name,
            active,
            public,
            metric_id=metric_id,
            private=private,
            groups=groups,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

brands(token, name=None, country_codes=None, year_numbers=None, *, brand_id=None, studies=None, filters=None, fields=None, include=None, query=None, stack_data=False, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount brands endpoint

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def brands(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `brands` endpoint

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.brands(
            name,
            country_codes,
            year_numbers,
            brand_id=brand_id,
            studies=studies,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

brandscape_data(token, 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, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount brandscape-data endpoint.

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

• 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

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
token	str	WPPBAV Fount API token	required
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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def brandscape_data(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `brandscape-data` endpoint.

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

    - 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`

    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
    ----------
    token : str
        WPPBAV Fount API token
    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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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)
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.brandscape_data(
            country_code,
            year_number,
            audiences,
            brand_name,
            studies=studies,
            filters=filters,
            fields=fields,
            metric_keys=metric_keys,
            metric_group_keys=metric_group_keys,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

categories(token, name=None, sectors=None, *, category_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount categories endpoint.

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

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

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
name	str	Search categories by name, default None	None
sectors	int or list[int]	Filter categories by sector ID, default 0	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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def categories(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `categories` endpoint.

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

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

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    name : str, optional
        Search categories by name, default None
    sectors : int or list[int], optional
        Filter categories by sector ID, default 0
    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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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.
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.categories(
            name,
            sectors,
            category_id=category_id,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

cities(token, name=None, capitals=0, countries=None, in_best_countries=None, *, city_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount cities endpoint.

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def cities(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `cities` endpoint.

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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.
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.cities(
            name,
            capitals,
            countries,
            in_best_countries,
            city_id=city_id,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

collections(token, name=None, public=0, *, collection_id=None, shared_with_me=0, mine=0, filters=None, fields=None, include=None, query=None, stack_data=False, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount collections endpoint.

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
name	str	Search collections by name, default None	None
public	Literal[0, 1]	Return public collections only if set to 1, 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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def collections(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `collections` endpoint.

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    name : str, optional
        Search collections by name, default None
    public : Literal[0, 1], optional
        Return public collections only if set to `1`, 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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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.
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.collections(
            name,
            public,
            collection_id=collection_id,
            shared_with_me=shared_with_me,
            mine=mine,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

companies(token, name=None, public=0, private=0, brands=None, *, company_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount countries endpoint.

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def companies(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `countries` endpoint.

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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.
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.companies(
            name,
            public,
            private,
            brands,
            company_id=company_id,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

countries(token, 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, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount countries endpoint.

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
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
country_id	int	Fount country ID, default None If a country ID is provided, only that country will be returned	None
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
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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def countries(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `countries` endpoint.

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    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
    country_id : int, optional
        Fount country ID, default None

        If a country ID is provided, only that country will be returned
    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
    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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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.
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.countries(
            name,
            active,
            regions,
            with_studies,
            country_id=country_id,
            with_recent_studies=with_recent_studies,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

raw_query(token, endpoint, query, *, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn') async

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

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
endpoint	str	Endpoint name	required
query	Query	bavapi.Query object with query parameters.	required
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'

Returns:

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

Source code in bavapi/sync.py

@_coro
async def raw_query(
    token: str,
    endpoint: str,
    query: Query[F],
    *,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
) -> List[JSONDict]:
    """Perform a raw GET query to the Fount API, returning the response JSON data
    instead of a `pandas` DataFrame.

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    endpoint : str
        Endpoint name
    query : Query
        bavapi.Query object with query parameters.
    timeout : float
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`

    Returns
    -------
    list[dict[str, Any]]
        List of JSON response data
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.raw_query(endpoint, query)

regions(token, name=None, *, region_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount regions endpoint.

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def regions(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `regions` endpoint.

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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.
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.regions(
            name,
            region_id=region_id,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

sectors(token, name=None, in_most_influential=0, *, sector_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount sectors endpoint.

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
name	str	Search categories 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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def sectors(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `sectors` endpoint.

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    name : str, optional
        Search categories 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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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.
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.sectors(
            name,
            in_most_influential,
            sector_id=sector_id,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

studies(token, 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, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount studies endpoint.

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def studies(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `studies` endpoint.

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.studies(
            country_codes,
            year_numbers,
            full_year,
            released,
            bav_study,
            study_id=study_id,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )

years(token, year=None, *, year_id=None, filters=None, fields=None, include=None, query=None, stack_data=False, timeout=30.0, verbose=True, batch_size=10, n_workers=2, retries=3, on_errors='warn', **kwargs) async

Query the Fount years endpoint.

Parameters:

Name	Type	Description	Default
token	str	WPPBAV Fount API token	required
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
timeout	float	Maximum timeout for requests in seconds, default 30.0	30.0
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'
**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/sync.py

@_coro
async def years(
    token: str,
    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,
    timeout: float = 30.0,
    verbose: bool = True,
    batch_size: int = 10,
    n_workers: int = 2,
    retries: int = 3,
    on_errors: Literal["warn", "raise"] = "warn",
    **kwargs: Unpack[CommonQueryParams],
) -> "DataFrame":
    """Query the Fount `years` endpoint.

    Parameters
    ----------
    token : str
        WPPBAV Fount API token
    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
    timeout : float, optional
        Maximum timeout for requests in seconds, default 30.0
    verbose : bool, optional
        Set to False to disable progress bar, default True
    batch_size : int, optional
        Size of batches to make requests with, default 10
    n_workers : int, optional
        Number of workers to make requests, default 2
    retries : int, optional
        Number of times to retry a request, default 3
    on_errors : Literal["warn", "raise"], optional
        Warn about failed requests or raise immediately on failure, default `"warn"`
    **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
    """

    async with Client(
        token,
        timeout=timeout,
        verbose=verbose,
        batch_size=batch_size,
        n_workers=n_workers,
        retries=retries,
        on_errors=on_errors,
    ) as client:
        return await client.years(
            year,
            year_id=year_id,
            filters=filters,
            fields=fields,
            include=include,
            query=query,
            stack_data=stack_data,
            **kwargs,
        )