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/.

  1. Log into Big Local News using your Google account.

  2. Expand the Developer menu item in the left sidebar.

  3. Click Manage Keys.

  4. Generate a key and copy it to the clipboard.

  5. 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")