sodapy

library2.2.0pypypi✓ verified 85d ago

sodapy is a Python client for the Socrata Open Data API (SODA), enabling programmatic access to datasets from Socrata-powered platforms. While the library is functional, it has been unmaintained since August 31, 2022, with no new features or bug fixes planned. The current version is 2.2.0, and it is compatible with Python 3.5-3.10.

http-networking data

pip install sodapy

github ↗package ↗

INSTALL

IMPORT

SIG · SODAPY

sodapy

http-networkingpythonv2.2.0

Install

2.1s avg

Import

585ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.615s · 21.3MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.1s · import 0.555s · 22MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Socrata

✓ from sodapy import Socrata

Initializes a Socrata client, retrieves the first 5 records from a public dataset (e.g., NYC 311 Service Requests), and fetches its metadata. It demonstrates setting up the client with an optional application token and credentials, and performing a basic data retrieval. Environment variables are used for secure credential handling.

import os from sodapy import Socrata # Get credentials from environment variables or provide directly APP_TOKEN = os.environ.get('SOCRATA_APP_TOKEN', None) # Recommended for higher rate limits USERNAME = os.environ.get('SOCRATA_USERNAME', None) # Only required for creating/modifying data PASSWORD = os.environ.get('SOCRATA_PASSWORD', None) # Only required for creating/modifying data # Example: Connect to a public dataset (e.g., NYC Open Data - 311 Service Requests) # Replace 'data.cityofnewyork.us' with your Socrata domain # Replace 'erm2-nwe9' with your dataset identifier domain = 'data.cityofnewyork.us' dataset_identifier = 'erm2-nwe9' with Socrata(domain, APP_TOKEN, username=USERNAME, password=PASSWORD) as client: # Increase timeout for large datasets if needed # client.timeout = 50 # Example: Retrieve the first 5 records print(f"Retrieving the first 5 records from {dataset_identifier} on {domain}...") results = client.get(dataset_identifier, limit=5) # Results are returned as a list of dictionaries for item in results: print(item) print(f"\nRetrieved {len(results)} records.") # Example: Retrieve metadata for the dataset print(f"\nRetrieving metadata for {dataset_identifier}...") metadata = client.get_metadata(dataset_identifier) print(f"Dataset Name: {metadata.get('name')}") print(f"Description: {metadata.get('description', '')[:100]}...")

Debug

Known issues

breakingThe `sodapy` library is officially unmaintained as of August 31, 2022. No new features or bug fixes will be added. While existing functionality still works, users should proceed with caution and consider the lack of ongoing support for new projects.

fix

Be aware of the unmaintained status; evaluate if the existing functionality meets your long-term needs without requiring future updates or bug fixes. For data management operations (creating/transforming data), consider `socrata-py` which targets the Socrata Data Management API.

affects: 2.2.0 and later

gotchaQueries executed without an application token will be subjected to strict throttling limits by the Socrata API. This can lead to slower responses or request failures for extensive data retrieval.

fix

Always use an application token when initializing the `Socrata` client, especially for frequent or large queries. You can obtain one from the Socrata website after creating an account. Pass it as the `app_token` argument: `Socrata(domain, app_token='YOUR_APP_TOKEN')`.

affects: All versions

gotchaThe Socrata Open Data API (SODA) and `sodapy` are primarily for reading and directly writing to datasets. For write operations that involve data transformations or use the Socrata Data Management Experience (e.g., creating datasets through the UI), the Socrata Data Management API should be used.

fix

Understand the distinction between the SODA API and the Data Management API. If your task involves complex data transformations or is related to the data management user interface, investigate the `socrata-py` SDK which is designed for the Data Management API.

affects: All versions

gotchaSocrata API calls have a default timeout of 10 seconds. For large datasets or slow connections, this can result in `Readtimeout error` exceptions, preventing full data retrieval.

fix

Increase the timeout limit for the `Socrata` client by setting the `timeout` parameter during initialization or by updating the `client.timeout` attribute. Example: `client = Socrata(..., timeout=60)` or `client.timeout = 60`.

affects: All versions

gotchaSODA APIs are paged and typically return a maximum of 50,000 records per request. Without proper pagination, you might only retrieve a subset of the available data.

fix

Use the `$limit` and `$offset` parameters in your `client.get()` calls to request subsequent pages of data. To retrieve all records, you might need to make multiple paginated requests or use the `client.get_all()` method if available and suitable for your dataset.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'sodapy'

The `sodapy` library is not installed in the current Python environment.

fix

pip install sodapy

TypeError: __init__() missing 1 required positional argument: 'domain'

The `SocrataClient` constructor was called without providing the `domain` argument, which is mandatory.

fix

from sodapy import Socrata
client = Socrata("data.cityofnewyork.us", app_token="YOUR_APP_TOKEN")

ValueError: Invalid Socrata dataset identifier

The provided `dataset_identifier` in the `get` method does not conform to the expected Socrata dataset ID format (e.g., 'xxxx-xxxx').

fix

from sodapy import Socrata
client = Socrata("data.cityofnewyork.us")
results = client.get("6wic-ph62") # Example: ensure it's in the format xxxx-xxxx

IndexError: list index out of range

The `sodapy.get()` method returned an empty list because no data matched the query or the dataset was empty, and the code attempted to access an element at index 0.

fix

from sodapy import Socrata
client = Socrata("data.cityofnewyork.us")
data = client.get("dataset_id")
if data:
    print(data[0])
else:
    print("No data found for this query.")

Upgrade

Version history

2.2.0latest on PyPI · released Aug 31, 2022

Audit

Dependencies

requestsrequiredCore dependency for HTTP requests.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/xmunoz/sodapy ↗

packagehttps://pypi.org/project/sodapy/ ↗