Package: lfapi
LfApi: a Python SDKInstallationThe latest version of the library can be installed directly from PyPI:pip install lfapiUsageGetting StartedThelfapi.Clientclass is the main interface with the ListenFirst API:from lfapi import ClientIt requires at minimum an API key as well as a set of client credentials for
access token generation. Token generation is handled by thelfapi.Authclass:from lfapi import Auth
auth = Auth(<CLIENT_ID>, <CLIENT_SECRET>)
token = auth.access_tokenTheClientclass is instantiated with an API key and an instance of theAuthclass:client = Client(<API_KEY>, auth)Alternatively, all three credentials can be loaded directly to theClientclass from a JSON file:client = Client.load(<JSON_FILE_NAME_OR_FILE_OBJECT>)

# The JSON file should follow this schema:
# {
#   "api_key": <api_key>,
#   "client_id": <client_id>
#   "client_secret": <client_secret>
# }These credentials can be retrieved fromthe platform's API settings page.Accessing the APIOnce instantiated, theClientobject can be used to make customized HTTP
requests to various API endpoints. The lowest-level request mechanism is built
around two methods,secure_get()andsecure_post(). Each takes a positional
endpoint argument, as well as aparamsargument as in therequestslibrary.secure_post()additionally takes ajsonargument, again mirroring therequestslibrary. Both returnrequests.Responseobjects upon successful
completion:client.secure_get(endpoint, params=None)Make a secureGETrequest to the ListenFirst API.client.secure_post(endpoint, json=None, params=None)Make a securePOSTrequest to the ListenFirst API.Commonly used endpoints have dedicated instance methods:client.fetch(json)POSTrequest to/analytics/fetchto perform a synchronous query.client.create_fetch_job(json)POSTrequest to/analytics/fetch_jobto create an asynchronous query.client.show_fetch_job(job_id)GETrequest to/analytics/fetch_job/{id}to view a summary of an
existing asynchronous query.client.latest_fetch_job(params=None)GETrequest to/analytics/fetch_job/latestto view a summary of the most
recent asynchronous query.client.list_fetch_jobs(params=None)GETrequest to/analytics/fetch_jobto view an abridged summary for all
asynchronous queries.client.create_schedule_config(json)POSTrequest to/analytics/schedule_configto create an schedule
configuration.client.show_schedule_config(schedule_config_id)GETrequest to/analytics/schedule_config/{id}to view a summary of an
existing schedule configuration.client.list_schedule_configs(params=None)GETrequest to/analytics/schedule_configto view an abridged summary
for all schedule configurations.client.get_brand(brand_id, params=None)GETrequest to/brand_views/{id}to view a summary of a brand view.client.list_brands(params=None)GETrequest to/brand_viewsto view a summary for all brand views.client.get_brand_set(brand_set_id)GETrequest to/brand_view_sets/{id}to view a summary of a brand view
set.client.list_brand_sets(params=None)GETrequest to/brand_view_setsto view a summary for all brand view
sets.client.get_dataset(dataset_id)GETrequest to/dictionary/datasets/{id}to view a summary of a dataset.client.list_datasets()GETrequest to/dictionary/datasetsto view an abridged summary for all
datasets.client.get_field_values(params)GETrequest to/dictionary/field_valuesto view a list of values for a
given field.With the exception ofget_field_values(), these methods wrap the API
responses in instances oflfapi.Modelsubclasses. These wrapper classes offer
some convenient extended functionality, such as JSON and CSV conversion.In addition, theClientobject implements a number of convenience methods
around the/analyticsendpoints for managing data queries:client.poll_fetch_job(job_id)Pull fetch job summary until state is one of 'completed', 'failed'.client.sync_analytic_query(fetch_params, per_page=None, max_pages=inf)Run multiple pages of synchronous analytic queries.client.async_analytic_query(fetch_params, client_context=None, max_rows=None, emails=None)Construct and poll an async analytic query, and download page URLs upon
completion.For code examples, see ourexamples wiki.