Setting Up Your Python Environment for API Interaction

You can run the Python parts of this workshop either in your browser (recommended) or on your own computer. This page helps you get set up so you can focus on the API concepts, not the tooling.

No coding experience required

You can follow along even if you’re new to coding. Some setup steps may feel unfamiliar at first—that’s normal.

Questions? Ask here.
Want a gentle Python intro? Try Python for Everybody.
UCSB Carpentry also offers beginner workshops: upcoming events.

Also, don’t forget your library resources! Library catalogs often include excellent beginner-friendly programming books (print and online).

How to Run Python Code

There are many ways to run Python. For this workshop, we recommend a browser-based option like Google Colab or Binder. No installation required, and it’s easy to share work during a live session.

If you prefer to work locally, you can use an IDE such as VSCodium, Spyder, or VS Code.

This workshop uses a starter notebook that’s already filled in with the code you’ll need. That way you can run cells immediately, follow along in a live workshop, and edit small parts without having to type everything from scratch.

| | |

Libraries Used in This Workshop

Libraries are pre-built code packages that provide specific functionality. In this workshop, we’ll use a few libraries: one to make HTTP requests, one to keep our API key out of the notebook output, and one to extract keywords from text. The first cells in our notebook will be dedicated to installing and importing these libraries.

Installing Libraries

# If you're running in Colab/Binder, you can install everything from inside the notebook.
%pip install httpx tqdm yake matplotlib

Importing Libraries

# Import built-in libraries
import os # For environment variable management
import time # For adding delays between API requests
import json # For working with JSON data
from getpass import getpass # For securely inputting API keys

# Import third-party libraries
import httpx # For making HTTP requests
from urllib.parse import urlsplit, parse_qsl, urlencode, urlunsplit # For URL manipulation
import yake # For keyword extraction
from tqdm import tqdm # For displaying progress bars
import matplotlib.pyplot as plt # For data visualization

Constants

Technically speaking, a constant is a value that shouldn’t change once it’s set. Python doesn’t have a built-in mechanism to strictly enforce immutability, but it does rely on a strong community-adopted naming convention.

The “Pythonic” way to define a constant is to use all uppercase letters with underscores separating words. This signals to other developers that the variable’s value should not be modified after it’s set.

For our exercise, we will define the following constants. You can copy and paste this into your code:

API_BASE_URL = "https://api.dp.la/v2/" 
ENV_VAR_NAME = "DPLA_API_KEY" 
FALLBACK_DATA_URL = "https://raw.githubusercontent.com/UCSB-Library-Research-Data-Services/intro2APIs/main/data/"

Storing Your API Key

Even though this isn’t a public application, it’s still good practice to keep your API key secure and avoid hardcoding it directly. We are going to store the API key as an environment variable (a variable that lives in your system’s environment rather than inside your notebook). This way, you can access it in your code without exposing it.

getpass is a built-in Python module that provides a secure way to handle sensitive information, such as passwords or any other sensitive credentials.

The method we will use is as follows:

# Check if the API key is already set as an environment variable
api_key = os.getenv(ENV_VAR_NAME)

# If the API key is not set, a prompt will ask to enter the API key
if not api_key:
    api_key = getpass(f"Enter your DPLA API key: ").strip()
    if not api_key:
        raise ValueError("No API key provided")
    # Store the API key as an environment variable for the current session
    os.environ[ENV_VAR_NAME] = api_key

print(f"API key set in environment variable '{ENV_VAR_NAME}'")

API key is set in environment variable 'DPLA_API_KEY'

Never print your API key

Note that we printed a message confirming that the API key is set (and the name of the environment variable where it’s stored), but we did not print the API key itself. This matters in notebooks because cell output can be saved and accidentally shared.

Test the API Key

To test that your API key is working, you can make a simple request to the DPLA API. You can copy and paste this code into a cell in your notebook:

# Make a test request to the DPLA API
if not api_key:
    print(
        "No API key found yet. Set the 'DPLA_API_KEY' environment variable (or run the getpass cell above) and re-run this cell."
    )
else:
    test_url = f"{API_BASE_URL}items?api_key={api_key}&page_size=1"
    response = httpx.get(test_url)
    if response.status_code == 200:
        print("API key is valid! Here's a sample response:")
        print(json.dumps(response.json(), indent=2))
    else:
        print(f"Failed to connect to the API. Status code: {response.status_code}")
        print(f"Response: {response.text}")

API key is valid! Here's a sample response:
{
  "count": 53194696,
  "docs": [
    {
      "@context": "http://dp.la/api/items/context",
      "@id": "http://dp.la/api/items/61730f4fd818bd0626a419ef82a88d40",
      "@type": "ore:Aggregation",
      "aggregatedCHO": "#sourceResource",
      "dataProvider": {
        "@id": "http://dp.la/api/contributor/center-for-sacramento-history",
        "name": "Center for Sacramento History"
      },
      "id": "61730f4fd818bd0626a419ef82a88d40",
      "ingestDate": "2024-02-01T16:27:52.667Z",
      "ingestType": "item",
      "isShownAt": "https://sacramento.pastperfectonline.com/photo/3F9DAD12-BD08-4B41-B6E1-024530408380",
      "object": "https://thumbnails.calisphere.org/clip/150x150/eda2796f3877e7cfe971e54e0dcd7d5f",
      "originalRecord": {
        "stringValue": "{\n  \"collection_url\" : [ \"https://registry.cdlib.org/api/v1/collection/26935/\" ],\n  \"repository_name\" : [ \"Center for Sacramento History\" ],\n  \"url_item\" : \"https://sacramento.pastperfectonline.com/photo/3F9DAD12-BD08-4B41-B6E1-024530408380\",\n  \"repository_data\" : [ \"https://registry.cdlib.org/api/v1/repository/174/::Center for Sacramento History\" ],\n  \"rights\" : [ \"Please contact the contributing institution for more information regarding the copyright status of this object.\" ],\n  \"rights_ss\" : [ \"Please contact the contributing institution for more information regarding the copyright status of this object.\" ],\n  \"reference_image_dimensions\" : \"211:210\",\n  \"collection_name\" : [ \"Center for Sacramento History Photo Collection\" ],\n  \"collection_data\" : [ \"https://registry.cdlib.org/api/v1/collection/26935/::Center for Sacramento History Photo Collection\" ],\n  \"sort_title\" : \"print photographic color\",\n  \"reference_image_md5\" : \"eda2796f3877e7cfe971e54e0dcd7d5f\",\n  \"facet_decade\" : [ \"unknown\" ],\n  \"sort_collection_data\" : [ \"center for sacramento history photo collection:Center for Sacramento History Photo Collection:https://registry.cdlib.org/api/v1/collection/26935/\" ],\n  \"harvest_id_s\" : \"26935--3F9DAD12-BD08-4B41-B6E1-024530408380\",\n  \"repository_url\" : [ \"https://registry.cdlib.org/api/v1/repository/174/\" ],\n  \"title\" : [ \"Print, Photographic, Color\" ],\n  \"title_ss\" : [ \"Print, Photographic, Color\" ],\n  \"identifier\" : [ \"3F9DAD12-BD08-4B41-B6E1-024530408380\", \"1983/001/SBPM08387\" ],\n  \"identifier_ss\" : [ \"3F9DAD12-BD08-4B41-B6E1-024530408380\", \"1983/001/SBPM08387\" ],\n  \"type\" : [ \"Image\" ],\n  \"type_ss\" : [ \"Image\" ],\n  \"id\" : \"d6e9e727a3b58ae727960f7d74d0dd38\",\n  \"subject\" : [ \"McClellan Air Force Base\" ],\n  \"subject_ss\" : [ \"McClellan Air Force Base\" ],\n  \"_version_\" : 1768714413655719936,\n  \"timestamp\" : \"2023-06-14T21:18:29.361Z\"\n}"
      },
      "provider": {
        "@id": "http://dp.la/api/contributor/cdl",
        "exactMatch": [
          "http://www.wikidata.org/entity/Q5020447"
        ],
        "name": "California Digital Library"
      },
      "rightsCategory": "Unspecified Rights Status",
      "sourceResource": {
        "@id": "http://dp.la/api/items/61730f4fd818bd0626a419ef82a88d40#SourceResource",
        "collection": [
          {
            "title": "Center for Sacramento History Photo Collection"
          }
        ],
        "identifier": [
          "3F9DAD12-BD08-4B41-B6E1-024530408380",
          "1983/001/SBPM08387"
        ],
        "rights": [
          "Please contact the contributing institution for more information regarding the copyright status of this object."
        ],
        "subject": [
          {
            "name": "McClellan Air Force Base"
          }
        ],
        "title": [
          "Print, Photographic, Color"
        ],
        "type": [
          "image"
        ]
      }
    }
  ],
  "facets": [],
  "limit": 1,
  "start": 1
}

Having all the libraries in place and the API key securely stored, now it’s time to start querying.