LfApi: a Python SDK
=====
Installation
------------
The latest version of the library can be installed directly from PyPI:
pip install lfapi
Usage
-----
### Getting Started
The `lfapi.Client` class is the main interface with the ListenFirst API:
from lfapi import Client
It requires at minimum an API key as well as a set of client credentials for
access token generation. Token generation is handled by the `lfapi.Auth` class:
from lfapi import Auth
auth = Auth(<CLIENT_ID>, <CLIENT_SECRET>)
token = auth.access_token
The `Client` class is instantiated with an API key and an instance of the
`Auth` class:
client = Client(<API_KEY>, auth)
Alternatively, all three credentials can be loaded directly to the `Client`
class 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 from [the platform's API settings page](
https://app.listenfirstmedia.com/#api).
### Accessing the API
Once instantiated, the `Client` object can be used to make customized HTTP
requests to various API endpoints. The lowest-level request mechanism is built
around two methods, `secure_get()` and `secure_post()`. Each takes a positional
endpoint argument, as well as a `params` argument as in the `requests` library.
`secure_post()` additionally takes a `json` argument, again mirroring the
`requests` library. Both return `requests.Response` objects upon successful
completion:
* `client.secure_get(endpoint, params=None)`
Make a secure `GET` request to the ListenFirst API.
* `client.secure_post(endpoint, json=None, params=None)`
Make a secure `POST` request to the ListenFirst API.
Commonly used endpoints have dedicated instance methods:
* `client.fetch(json)`
`POST` request to `/analytics/fetch` to perform a synchronous query.
* `client.create_fetch_job(json)`
`POST` request to `/analytics/fetch_job` to create an asynchronous query.
* `client.show_fetch_job(job_id)`
`GET` request to `/analytics/fetch_job/{id}` to view a summary of an
existing asynchronous query.
* `client.latest_fetch_job(params=None)`
`GET` request to `/analytics/fetch_job/latest` to view a summary of the most
recent asynchronous query.
* `client.list_fetch_jobs(params=None)`
`GET` request to `/analytics/fetch_job` to view an abridged summary for all
asynchronous queries.
* `client.create_schedule_config(json)`
`POST` request to `/analytics/schedule_config` to create an schedule
configuration.
* `client.show_schedule_config(schedule_config_id)`
`GET` request to `/analytics/schedule_config/{id}` to view a summary of an
existing schedule configuration.
* `client.list_schedule_configs(params=None)`
`GET` request to `/analytics/schedule_config` to view an abridged summary
for all schedule configurations.
* `client.get_brand(brand_id, params=None)`
`GET` request to `/brand_views/{id}` to view a summary of a brand view.
* `client.list_brands(params=None)`
`GET` request to `/brand_views` to view a summary for all brand views.
* `client.get_brand_set(brand_set_id)`
`GET` request to `/brand_view_sets/{id}` to view a summary of a brand view
set.
* `client.list_brand_sets(params=None)`
`GET` request to `/brand_view_sets` to view a summary for all brand view
sets.
* `client.get_dataset(dataset_id)`
`GET` request to `/dictionary/datasets/{id}` to view a summary of a dataset.
* `client.list_datasets()`
`GET` request to `/dictionary/datasets` to view an abridged summary for all
datasets.
* `client.get_field_values(params)`
`GET` request to `/dictionary/field_values` to view a list of values for a
given field.
With the exception of `get_field_values()`, these methods wrap the API
responses in instances of `lfapi.Model` subclasses. These wrapper classes offer
some convenient extended functionality, such as JSON and CSV conversion.
In addition, the `Client` object implements a number of convenience methods
around the `/analytics` endpoints 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 our [examples wiki](
https://github.com/ListenFirstMedia/lf-api-examples/wiki/Using-the-ListenFirst-API-Python-SDK).
Raw data
{
"_id": null,
"home_page": "https://github.com/ListenFirstMedia/lf-python-sdk",
"name": "lfapi",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "listenfirst api sdk",
"author": "Joseph Masom",
"author_email": "joseph.masom@listenfirstmedia.com",
"download_url": "https://files.pythonhosted.org/packages/de/dd/4b9314987039014224753d5fad6b469028ea1b00f8c9787fd189cabb27b7/lfapi-0.10.0.tar.gz",
"platform": null,
"description": "\nLfApi: a Python SDK\n=====\n\nInstallation\n------------\n\nThe latest version of the library can be installed directly from PyPI:\n\n pip install lfapi\n\nUsage\n-----\n\n### Getting Started\n\nThe `lfapi.Client` class is the main interface with the ListenFirst API:\n\n from lfapi import Client\n\nIt requires at minimum an API key as well as a set of client credentials for\naccess token generation. Token generation is handled by the `lfapi.Auth` class:\n\n from lfapi import Auth\n auth = Auth(<CLIENT_ID>, <CLIENT_SECRET>)\n token = auth.access_token\n\nThe `Client` class is instantiated with an API key and an instance of the\n`Auth` class:\n\n client = Client(<API_KEY>, auth)\n\nAlternatively, all three credentials can be loaded directly to the `Client`\nclass from a JSON file:\n\n client = Client.load(<JSON_FILE_NAME_OR_FILE_OBJECT>)\n\n # The JSON file should follow this schema:\n # {\n # \"api_key\": <api_key>,\n # \"client_id\": <client_id>\n # \"client_secret\": <client_secret>\n # }\n\nThese credentials can be retrieved from [the platform's API settings page](\nhttps://app.listenfirstmedia.com/#api).\n\n### Accessing the API\n\nOnce instantiated, the `Client` object can be used to make customized HTTP\nrequests to various API endpoints. The lowest-level request mechanism is built\naround two methods, `secure_get()` and `secure_post()`. Each takes a positional\nendpoint argument, as well as a `params` argument as in the `requests` library.\n`secure_post()` additionally takes a `json` argument, again mirroring the\n`requests` library. Both return `requests.Response` objects upon successful\ncompletion:\n* `client.secure_get(endpoint, params=None)` \n Make a secure `GET` request to the ListenFirst API.\n\n* `client.secure_post(endpoint, json=None, params=None)` \n Make a secure `POST` request to the ListenFirst API.\n\nCommonly used endpoints have dedicated instance methods:\n* `client.fetch(json)` \n `POST` request to `/analytics/fetch` to perform a synchronous query.\n \n* `client.create_fetch_job(json)` \n `POST` request to `/analytics/fetch_job` to create an asynchronous query.\n\n* `client.show_fetch_job(job_id)` \n `GET` request to `/analytics/fetch_job/{id}` to view a summary of an\n existing asynchronous query. \n \n* `client.latest_fetch_job(params=None)` \n `GET` request to `/analytics/fetch_job/latest` to view a summary of the most\n recent asynchronous query.\n\n* `client.list_fetch_jobs(params=None)` \n `GET` request to `/analytics/fetch_job` to view an abridged summary for all\n asynchronous queries.\n \n* `client.create_schedule_config(json)` \n `POST` request to `/analytics/schedule_config` to create an schedule\n configuration.\n \n* `client.show_schedule_config(schedule_config_id)` \n `GET` request to `/analytics/schedule_config/{id}` to view a summary of an\n existing schedule configuration.\n \n* `client.list_schedule_configs(params=None)` \n `GET` request to `/analytics/schedule_config` to view an abridged summary\n for all schedule configurations.\n \n* `client.get_brand(brand_id, params=None)` \n `GET` request to `/brand_views/{id}` to view a summary of a brand view.\n\n* `client.list_brands(params=None)` \n `GET` request to `/brand_views` to view a summary for all brand views.\n \n* `client.get_brand_set(brand_set_id)` \n `GET` request to `/brand_view_sets/{id}` to view a summary of a brand view\n set.\n \n* `client.list_brand_sets(params=None)` \n `GET` request to `/brand_view_sets` to view a summary for all brand view\n sets.\n \n* `client.get_dataset(dataset_id)` \n `GET` request to `/dictionary/datasets/{id}` to view a summary of a dataset.\n \n* `client.list_datasets()` \n `GET` request to `/dictionary/datasets` to view an abridged summary for all\n datasets.\n \n* `client.get_field_values(params)` \n `GET` request to `/dictionary/field_values` to view a list of values for a\n given field.\n\nWith the exception of `get_field_values()`, these methods wrap the API\nresponses in instances of `lfapi.Model` subclasses. These wrapper classes offer\nsome convenient extended functionality, such as JSON and CSV conversion.\n\nIn addition, the `Client` object implements a number of convenience methods\naround the `/analytics` endpoints for managing data queries:\n* `client.poll_fetch_job(job_id)` \n Pull fetch job summary until state is one of 'completed', 'failed'.\n\n* `client.sync_analytic_query(fetch_params, per_page=None, max_pages=inf)` \n Run multiple pages of synchronous analytic queries.\n\n* `client.async_analytic_query(fetch_params, client_context=None, max_rows=None, emails=None)` \n Construct and poll an async analytic query, and download page URLs upon\n completion.\n\nFor code examples, see our [examples wiki](\nhttps://github.com/ListenFirstMedia/lf-api-examples/wiki/Using-the-ListenFirst-API-Python-SDK).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The Python library for the ListenFirst API",
"version": "0.10.0",
"project_urls": {
"Download": "https://pypi.org/project/lfapi",
"Homepage": "https://github.com/ListenFirstMedia/lf-python-sdk"
},
"split_keywords": [
"listenfirst",
"api",
"sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0e088fb96051ed5c38f0a952ad0f9d1fc98c07f494d8140035f4daac29384fea",
"md5": "fdca340cd8ebaf93bb4e24b8a297a455",
"sha256": "2aa4640a33dd2104341d8e8ccd2483464257707777afe7baeb1f045debe850c7"
},
"downloads": -1,
"filename": "lfapi-0.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fdca340cd8ebaf93bb4e24b8a297a455",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 12619,
"upload_time": "2024-08-12T14:07:01",
"upload_time_iso_8601": "2024-08-12T14:07:01.566849Z",
"url": "https://files.pythonhosted.org/packages/0e/08/8fb96051ed5c38f0a952ad0f9d1fc98c07f494d8140035f4daac29384fea/lfapi-0.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dedd4b9314987039014224753d5fad6b469028ea1b00f8c9787fd189cabb27b7",
"md5": "1f8afefcf529fa6e8cd9f8fba544c376",
"sha256": "4ed54b837d064ef6533eb42a17b726da48b9c80e3c57a70cb50b912ac3c5c717"
},
"downloads": -1,
"filename": "lfapi-0.10.0.tar.gz",
"has_sig": false,
"md5_digest": "1f8afefcf529fa6e8cd9f8fba544c376",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 14205,
"upload_time": "2024-08-12T14:07:02",
"upload_time_iso_8601": "2024-08-12T14:07:02.567014Z",
"url": "https://files.pythonhosted.org/packages/de/dd/4b9314987039014224753d5fad6b469028ea1b00f8c9787fd189cabb27b7/lfapi-0.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-12 14:07:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ListenFirstMedia",
"github_project": "lf-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "build",
"specs": [
[
"==",
"0.10.0"
]
]
},
{
"name": "bump2version",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "flake8",
"specs": [
[
"==",
"6.0.0"
]
]
},
{
"name": "isort",
"specs": [
[
"==",
"5.12.0"
]
]
},
{
"name": "pre-commit",
"specs": [
[
"==",
"3.0.4"
]
]
},
{
"name": "pytest",
"specs": [
[
"~=",
"7.2.1"
]
]
},
{
"name": "pytest-recording",
"specs": [
[
"~=",
"0.12.1"
]
]
},
{
"name": "pytest-runner",
"specs": [
[
"~=",
"6.0.0"
]
]
},
{
"name": "requests",
"specs": [
[
"~=",
"2.31.0"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"65.5.1"
]
]
},
{
"name": "twine",
"specs": [
[
"==",
"4.0.2"
]
]
}
],
"lcname": "lfapi"
}
JSON
