Getting started¶
Setup¶
Installation¶
The Python SDK can be installed using pip
.
pip install bln
Getting an API Key¶
API keys can be generated at https://biglocalnews.org/.
Log into Big Local News using your Google account.
Expand the Developer menu item in the left sidebar.
Click Manage Keys.
Generate a key and copy it to the clipboard.
Export the token to your environment
export BLN_API_TOKEN = "<Paste your API Key here>"
Initializing the SDK client¶
The client is what will handle calls to the Big Local News API. To set up it you must authorize the client using your API key.
from bln import Client
client = Client()
Working with projects¶
Creating a project¶
To create a project, use the client’s createProject
method. The only argument required to create a project is a name. However, it is helpful to include a description. The createProject
method will return a dictionary of project metadata if it is successful and None
if it fails.
project_name = "Big Local News SDK Demo Project"
project_description = "This is a sample project to show users how the SDK works"
project = client.createProject(project_name, description=project_description)
Get metadata for an existing project¶
Helper methods can assist you with selecting projects by name or id. It will return one and only one project.
client.get_project_by_name("Big Local News SDK Demo Project")
client.get_project_by_id(project_id)
The client’s search_projects
method can be used to for more complex queries. It takes a lambda function that returns True
or False
based on whether or not the project metadata meets the search criteria. The search_projects
method will return a list of project metadata for those projects matching the search query.
client.search_projects(lambda project: "SDK" in project["description"])
Updating project metadata¶
The client’s updateProject
method is used to edit project metadata. It takes the project’s ID as a required argument and optional keyword arguments to update the metadata. The method will return the updated project metadata.
new_name = "Big Local News SDK Demo Project - edited"
new_description = "This is a sample project to show users how the SDK works. The description and name have been edited."
client.updateProject(project_id, name=new_name, description=new_description)
Deleting a project¶
Use the client’s deleteProject
method to delete a project. The method requires a project ID as it’s sole argument.
WARNING: This process is irreversible. Use with caution.
client.deleteProject(project_id)
Working with files¶
The SDK client has a host of methods available for working with files. All of the methods will require a project ID as an argument.
Uploading¶
The client has two different methods for file uploads - one for a single file and a second for batch uploads.
A single file¶
client.upload_file(project_id, "./data/demo_a.csv")
Multiple files¶
The SDK client also has an upload_files
method which takes a list of files as an argument.
client.upload_files(project_id, files_to_upload)
Viewing files in a project¶
# Get the first project returned from a search
project = client.search_projects(lambda project: project["id"] == project_id)[0]
project["files"]
[
{
"createdAt": "2022-01-12T23:40:44.443000+00:00",
"name": "demo_a.csv",
"tags": [],
"updatedAt": "2022-01-12T23:40:44.443000+00:00",
},
{
"createdAt": "2022-01-12T23:40:46.372000+00:00",
"name": "demo_b.csv",
"tags": [],
"updatedAt": "2022-01-12T23:40:46.372000+00:00",
},
]
Downloading a file¶
The client’s download_file
takes three arguments: project ID, filename and an optional output directory. If an output directory is not specified, the client will download to the current working directory.
client.download_file(project_id, "demo_a.csv", output_dir="./data")