Skip to content

Reference classes

bavapi can generate some convenience reference classes which map Fount resource IDs with a more readable name, both for ease of use and for autocompletion in IDEs.

These classes are automatically generated by a console command that becomes available once bavapi is installed.

Protected Access

A Fount API token is required to generate reference files. See the Authentication section for more information and instructions for using .env files.

As of v1.0 the following reference classes will be generated in a folder named bavapi_refs (by default, see below):

  • Audiences: encodes audience IDs
  • Countries: encodes country IDs

A sample reference class would look like this:

class Audiences(Enum):
    ALL_ADULTS = 123
    ...

And could be used to have better visibility and readability when filtering API responses:

Explicit audience filter
from bavapi_refs import Audiences

bavapi.brandscape_data(country_code="US", year=2022, audiences=Audiences.ALL_ADULTS)
Audience filter not human-readable
bavapi.brandscape_data(country_code="US", year=2022, audiences=123)

Warning

Don't commit reference classes to public repositories. Add bavapi_refs/ to your .gitignore file.

Generate Reference classes

New in v0.7

To generate these reference classes, there are two options for authenticating your requests:

  • Specify the Fount API token via the -t/--token argument
  • Use a .env file to store your Fount API token as the BAV_API_KEY environment variable, and install python-dotenv to read the file into your environment. See the Authentication section for more info.

To generate the reference files, run the following command:

bavapi-gen-refs --all

bavapi-gen-refs -t "TOKEN" --all

You can also specify the name of the reference class to generate:

bavapi-gen-refs -t "TOKEN" --name audiences

To update existing reference classes with the latest data, re-run bavapi-gen-refs with the appropriate parameters on your terminal.

Specify destination folder

New in v0.11

Finally, you can specify the destination folder with -d/--dest-folder where you want to store the reference classes. This will determine the name required for import (from {dest_folder} import {Reference}).

It is recommended to leave this as the default ./bavapi_refs/, though if you do want to change it, it is also recommended to store them as a top level folder in your project directory.

bavapi-gen-refs -d "custom_folder/" --name audiences

Warning

If you change the destination folder, remember not to commit it to public repositories. Add {custom_folder}/ to your .gitignore file.

bavapi-gen-refs options

Option Description
-h, --help Show help message and exit
-t, --token TOKEN WPPBAV Fount API token
-a, --all Generate all reference files
-n, --name {audiences,countries} Name of reference to generate
-d, --dest-folder DEST_FOLDER Path to destination folder, default './bavapi_refs/'