Skip to content

filters

Filter objects for WPPBAV Fount API queries based on pydantic.

All endpoint filters are subclasses of FountFilters.

You can use any endpoint filter class with raw_query functions and methods, but you must use endpoint-specific filters for each endpoint function or method.

Examples:

Use BrandsFilters with the brands endpoint:

>>> import bavapi
>>> bavapi.brands("TOKEN", filters=bavapi.filters.BrandsFilters(name="Facebook"))

FountFilters is compatible with all endpoints (including raw_query):

>>> bavapi.brands("TOKEN", filters=bavapi.filters.FountFilters(name="Facebook"))

Using the wrong filter can lead to unexpected results:

>>> bavapi.brands("TOKEN", filters=bavapi.filters.CategoriesFilters(country_codes="UK"))

The above example may work, but it is highly discouraged.

AudienceGroupsFilters

Bases: FountFilters

Filters for the brands endpoint.

See https://developer.wppbav.com/docs/2.x/core-resources/audience-groups for more info.

There are currently no specific filters for the audience-groups endpoint

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None

AudiencesFilters

Bases: FountFilters

Filters for the audiences endpoint.

See https://developer.wppbav.com/docs/2.x/core-resources/audiences for more info.

Attributes:

Name Type Description
active (Literal[0, 1], optional)

Return active audiences only if set to 1, default 0
inactive (Literal[0, 1], optional)

Return inactive audiences only if set to 1, default 0
public (Literal[0, 1], optional)

Return active audiences only if set to 1, default 0
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

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None

BrandMetricGroupsFilters

Bases: FountFilters

Filters for the brand-metric-groups endpoint.

See https://developer.wppbav.com/docs/2.x/core-resources/brand-metric-groups for more info.

Attributes:

Name Type Description
active (Literal[0, 1], optional)

Return active brand metrics when set to 1, default 0
inactive (Literal[0, 1], optional)

Return inactive brand metrics when set to 1, default 0

BrandMetricsFilters

Bases: FountFilters

Filters for the brand-metrics endpoint.

groups filters by the Fount IDs of the specific resources.

See https://developer.wppbav.com/docs/2.x/core-resources/brand-metrics for more info.

Attributes:

Name Type Description
active (Literal[0, 1], optional)

Return active brand metrics when set to 1, default 0
inactive (Literal[0, 1], optional)

Return inactive brand metrics when set to 1, default 0
public (Literal[0, 1], optional)

Return public brand metrics when set to 1, default 0
private (Literal[0, 1], optional)

Return private brand metrics when set to 1, default 0
groups (int or list[int], optional)

Fount brand metric group ID or list of group IDs, default None
current (Literal[0, 1], optional)

Return current brand metrics when set to 1, default 0
legacy (Literal[0, 1], optional)

Return legacy brand metrics when set to 1, default 0
core (Literal[0, 1], optional)

Return core brand metrics when set to 1, default 0
custom (Literal[0, 1], optional)

Return custom brand metrics when set to 1, default 0

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None

BrandsFilters

Bases: FountFilters

Filters for the brands endpoint.

Filters other than country_codes and year_numbers filter by the Fount IDs of the specific resources.

See https://developer.wppbav.com/docs/2.x/core-resources/brands for more info.

Attributes:

Name Type Description
country_codes (str or list[str], optional)

Two-letter ISO-3166 country code or list of country codes, default None
year_numbers (int or list[int], optional)

Study years in numerical format (not IDs), default None
categories (int or list[int], optional)

Fount category ID or list of category IDs, default None
countries (int or list[int], optional)

Fount country ID or list of country IDs, default None
regions (int or list[int], optional)

Fount region ID or list of region IDs, default None
sectors (int or list[int], optional)

Fount sector ID or list of sector IDs, default None
studies (int or list[int], optional)

Fount study ID or list of study IDs, default None
years (int or list[int], optional)

Fount year ID or list of year IDs, default None

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None

BrandscapeFilters

Bases: FountFilters

Filters for the studies endpoint.

audiences, countries, studies, years, brands and categories filter by the Fount IDs of the specific resources.

See https://developer.wppbav.com/docs/2.x/core-resources/brandscape-data for more info.

The brandscape-data endpoint requires the use of, at minimum, these filters:

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

You should read these from left to right. A combination of "Study + Audience" worksjust as well as "Study + Audience + Brand". However, "Category + Audience" will not.

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

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

Attributes:

Name Type Description
country_code (str or list[str], optional)

Two-letter ISO-3166 country code or list of country codes, default None
year_number (int or list[int], optional)

Study years in numerical format (not IDs), default None
audiences (int or list[int], optional)

Fount ID of the desired audience, default None

The Audiences class can help with using audience IDs.
brand_name (str, optional)

Perform a search on the brand name, default None
brands (int or list[int], optional)

Fount brand ID or list of brand IDs, default None
categories (int or list[int], optional)

Fount category ID or list of category IDs, default None
countries (int or list[int], optional)

Fount country ID or list of country IDs, default None

The Countries class can help with using country IDs.
studies (int or list[int], optional)

Fount study ID or list of study IDs, default None
years (int or list[int], optional)

Fount year ID or list of year IDs, default None

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None

CategoriesFilters

Bases: FountFilters

Filters for the categories endpoint.

See https://developer.wppbav.com/docs/2.x/core-resources/categories for more info.

Attributes:

Name Type Description
sectors (int or list[int], optional)

Fount sector ID or list of sector IDs, default None

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None

CitiesFilters

Bases: FountFilters

Filters for the cities endpoint.

See https://developer.wppbav.com/docs/2.x/core-resources/cities for more info.

Attributes:

Name Type Description
capitals (Literal[0, 1], optional)

Return capitals only, default 0
regions (int or list[int], optional)

Fount region ID or list of region IDs, default None
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

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None

CollectionsFilters

Bases: FountFilters

Filters for the collections endpoint.

See https://developer.wppbav.com/docs/2.x/core-resources/collections for more info.

Attributes:

Name Type Description
public (Literal[0, 1], optional)

Return public collections only, default 0
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

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None

CompaniesFilters

Bases: FountFilters

Filters for the companies endpoint.

See https://developer.wppbav.com/docs/2.x/core-resources/companies for more info.

Attributes:

Name Type Description
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

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None

CountriesFilters

Bases: FountFilters

Filters for the countries endpoint.

See https://developer.wppbav.com/docs/2.x/core-resources/countries for more info.

Attributes:

Name Type Description
active (Literal[0, 1], optional)

Return active countries only, default 0
regions (int or list[int], optional)

Fount region ID or list of region IDs, default None
with_studies (Literal[0, 1], optional)

Only return countries which have had a BAV study, default 0
with_recent_studies (int, optional)

Years of recency of studies in a specific country, default None

Only return countries which have had a BAV study in the past X years

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None

FountFilters

Bases: BaseModel

Base class for Fount API Filters.

Can be used with raw_query endpoints.

Attributes:

Name Type Description
updated_since (str, date or datetime, optional)

Request items that have been updated since the specified date, default None
**kwargs str, int or float, or list of str, int or floats, optional

Any additional filters to apply to the request, including for columns within the response data.

ensure(filters, **addl_filters) classmethod

Ensure FountFilters class from dictionary or other FountFilters class.

Defaults to values passed to filters when any additional filters overlap.

Parameters:

Name Type Description Default
filters FountFilters or dict of filter values

Dictionary of filters or FountFilters class.

 required
**addl_filters SequenceOrValues

Additional filters to add to the new FountFilters instance.

 {}

Returns:

Type Description
(FountFilters, optional)

FountFilters class or None if filters is None and no additional filters are passed.
Source code in bavapi/filters.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
@classmethod
def ensure(
    cls: Type[F],
    filters: Optional[FiltersOrMapping["FountFilters"]],
    **addl_filters: InputSequenceOrValues,
) -> Optional[F]:
    """Ensure `FountFilters` class from dictionary or other `FountFilters` class.

    Defaults to values passed to `filters` when any additional filters overlap.

    Parameters
    ----------
    filters : FountFilters or dict of filter values, optional
        Dictionary of filters or `FountFilters` class.
    **addl_filters : SequenceOrValues, optional
        Additional filters to add to the new `FountFilters` instance.

    Returns
    -------
    FountFilters, optional
        `FountFilters` class or `None` if `filters` is `None`
        and no additional filters are passed.
    """
    new_filters: Dict[str, InputSequenceOrValues] = {
        k: v for k, v in addl_filters.items() if v
    }

    # if addl_filters:
    #     warnings.warn(
    #         f"Using the {list(new_filters.keys())} function parameter(s) is deprecated. "
    #         f"Use the `filters` parameter with a {cls.__name__} instance instead.",
    #         DeprecationWarning,
    #         2,
    #     )

    if filters is None:
        if not new_filters:
            return None
        return cls(**new_filters)  # type: ignore[arg-type]

    if isinstance(filters, FountFilters):
        if not new_filters:
            return cls(**filters.model_dump(exclude_defaults=True))
        new_filters.update(filters.model_dump(exclude_defaults=True))
    else:
        new_filters.update(filters)

    return cls(**new_filters)  # type: ignore[arg-type]

RegionsFilters

Bases: FountFilters

Filters for the regions endpoint.

See https://developer.wppbav.com/docs/2.x/core-resources/regions for more info.

There are currently no specific filters for the regions endpoint

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None

SectorsFilters

Bases: FountFilters

Filters for the sectors endpoint.

See https://developer.wppbav.com/docs/2.x/core-resources/sectors for more info.

Attributes:

Name Type Description
in_most_influential (Literal[0, 1], optional)

Sectors that are part of the Most Influential lists, default 0
not_in_most_influential (Literal[0, 1], optional)

Sectors that are not part of the Most Influential lists, default 0

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None

StudiesFilters

Bases: FountFilters

Filters for the studies endpoint.

years, countries and regions filter by the Fount IDs of the specific resources.

See https://developer.wppbav.com/docs/2.x/core-resources/studies for more info.

Attributes:

Name Type Description
country_codes (str or list[str], optional)

Two-letter ISO-3166 country code or list of country codes, default None
year_numbers (int or list[int], optional)

Study years in numerical format (not IDs), default None
full_year (Literal[0, 1], optional)

Return full year studies when set to 1 (excludes US quarterly), default 0
released (Literal[0, 1], optional)

Return released studies when set to 1, default 0
unreleased (Literal[0, 1], optional)

Return unreleased studies when set to 1, default 0
open_survey (Literal[0, 1], optional)

Return studies with open brand requests when set to 1, default 0
active (Literal[0, 1], optional)

Return active audiences when set to 1, default 0
inactive (Literal[0, 1], optional)

Return inactive audiences when set to 1, default 0
bav_study (Literal[0, 1], optional)

Return full BAV studies when set to 1, default 0
data_updated_since (DTValues, optional)

Return studies updated since datetime value, default None
countries (int or list[int], optional)

Fount country ID or list of country IDs, default None
regions (int or list[int], optional)

Fount region ID or list of region IDs, default None
years (int or list[int], optional)

Fount year ID or list of year IDs, default None

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None

YearsFilters

Bases: FountFilters

Filters for the years endpoint.

See https://developer.wppbav.com/docs/2.x/core-resources/years for more info.

There are currently no specific filters for the years endpoint

Other Parameters:

Name Type Description
updated_since (str, date or datetime)

Request items that have been updated since the specified date, default None