Skip to main content

pdc-api-python

A Python client for the Philanthropy Data Commons (PDC) API.

PDC is an access-controlled service where changemakers and funders share funding proposals and organization data. A changemaker can submit a proposal once and share it with any funder it chooses, and the data owner decides who sees what. This package wraps the PDC API in typed Pydantic models, handles pagination, and raises one exception class per HTTP error. It doesn't depend on any web framework.

Install it as pdc-api and import it as pdc_api.

Status: alpha. The API may change between minor versions until 1.0.

Installation

Install it from PyPI:

pip install pdc-api

or with uv:

uv add pdc-api

Two optional extras add test and seeding helpers:

  • testing: helpers for mocking PDC responses in your own tests, built on responses.
  • seeding: helpers for creating PDC and Keycloak test data, built on python-keycloak and Faker.

Add them to the requirement, as in pdc-api[testing,seeding].

Python 3.12 or later is required.

Quickstart

from pdc_api import APISession
from pdc_api.client import get_changemakers, get_proposal
from pdc_api.token import KeycloakClientCredentialsProvider

session = APISession(
    base_url="https://api.philanthropydatacommons.org/",
    token_provider=KeycloakClientCredentialsProvider(
        server_url="https://auth.philanthropydatacommons.org",
        realm="pdc",
        client_id="your-client-id",
        client_secret="your-client-secret",
        timeout=15,
    ),
)

for changemaker in get_changemakers(session):
    print(changemaker.name, changemaker.tax_id)

proposal = get_proposal(session, proposal_id=42)

Every response is parsed into a model from pdc_api.models, with snake_case attributes over PDC's camelCase fields.

Authentication

APISession asks a token provider for a bearer token before each request. A token provider is any object with these two methods:

class TokenProvider(Protocol):
    def get_token(self) -> str: ...
    def refresh_if_necessary(self) -> None: ...

The package ships one: KeycloakClientCredentialsProvider runs the OAuth2 client-credentials grant against PDC's Keycloak and caches the token until 30 seconds before it expires. Use it for a service account.

To call PDC as a signed-in user, write your own provider that returns the user's access token and refreshes it as your app requires. The protocol is structural, so your class doesn't need to import or subclass anything from this package.

PDC applies the caller's permissions to every request. The same call can return different records for different tokens, and a record the caller may not view comes back as a 404, not a 403.

Reading data

There are two ways to read a list.

Iterate everything. get_changemakers, get_funders, get_proposals, get_initiatives, and the other plural get_* functions are generators that walk every page for you. The exception is get_base_fields, which returns a list:

from pdc_api.client import get_changemaker_proposals

for link in get_changemaker_proposals(session, changemaker_id=7):
    print(link.proposal_id)

Fetch one page. get_bundle_page returns a single page as a bundle, which is what a paginated UI needs. It takes the bundle type, a page number, an optional page size, and an optional search string:

from pdc_api.client import get_bundle_page
from pdc_api.models import FunderBundle

page = get_bundle_page(session, FunderBundle, page=2, count_per_page=25, content="climate")
print(page.total, [funder.name for funder in page.entries])

Bundles for nested endpoints take path parameters, such as get_bundle_page(session, FunderCollaborativeMemberBundle, path_params={"funder_collaborative_short_code": "acme"}). Query parameters that get_bundle_page doesn't name go in extra_params.

Writing data

The client covers the writes a proposal workflow needs: creating a proposal, adding a version with field values, linking a changemaker to it, and uploading files.

from pdc_api.client import create_proposal, create_proposal_version
from pdc_api.models import NewProposalFieldValue, NewProposalVersion

proposal = create_proposal(session, data={"opportunityId": 5, "externalId": "app-2026-001"})
version = create_proposal_version(
    session,
    proposal_version=NewProposalVersion(
        proposal_id=proposal.id,
        source_id=3,
        application_form_id=12,
        field_values=[NewProposalFieldValue(application_form_field_id=88, position=1, value="Summer meals")],
    ),
)

A changemaker can also write its own profile values. create_changemaker_source creates a source the changemaker owns, create_changemaker_field_value_batch opens a batch under it, and create_changemaker_field_value adds one value to the batch. PDC ranks changemaker-sourced values above funder and data-provider values.

create_initiative creates an initiative led by a changemaker, and create_initiative_field_value adds a value to it from a given source.

Uploading a file takes two steps. create_file creates the file record and returns a presigned S3 POST, and upload_file_to_s3_presigned_url sends the bytes to it.

Permission grants

PDC controls access with permission grants. Each grant gives a grantee (a user, a Keycloak organization, or every authenticated user) a set of verbs (such as view or edit) over a set of scopes, in the context of one entity such as a changemaker or a proposal. pdc_api.permission_grants models each context as its own class, so a grant parses into, say, ChangemakerPermissionGrant with a typed changemaker_id:

from pdc_api.models import PermissionGrantEntityType, PermissionGrantGranteeType, PermissionGrantVerb
from pdc_api.permission_grants import ChangemakerPermissionGrant, create_permission_grant, list_permission_grants

grant = create_permission_grant(
    session,
    grant=ChangemakerPermissionGrant(
        changemaker_id=7,
        grantee_type=PermissionGrantGranteeType.USER_GROUP,
        grantee_keycloak_organization_id="1f0c6e2a-7d4b-4c55-9a51-0d8c2f0b6a11",
        verbs=[PermissionGrantVerb.VIEW],
        scope=[PermissionGrantEntityType.CHANGEMAKER, PermissionGrantEntityType.PROPOSAL],
    ),
)

page = list_permission_grants(session, changemaker_id=7, verb=PermissionGrantVerb.VIEW)

The models check that the grantee fields match grantee_type before anything is sent. Create, get, update, and delete functions exist for grants and for default permission grants. A default permission grant has no context entity; PDC copies it into a real grant on each new entity of its type as that entity is created.

Errors

APISession raises a subclass of pdc_api.PDCException for every failed request. Each exception has .code (the HTTP status) and .detail (the parsed JSON body, or the raw text when the body isn't JSON). Before raising, it retries a GET or HEAD up to three times on a 502, 503, or 504 or a dropped connection.

Status Exception
400 PDCBadRequestError
401 PDCUnauthorizedError
403 PDCForbiddenError
404 PDCNotFoundError
409 PDCConflictError
422 PDCUnprocessableEntityError
5xx, timeout, or connection failure PDCServiceError
Any other non-2xx PDCException

A few lookups raise a subclass of PDCNotFoundError named for the resource:

  • get_proposal and get_changemaker_proposal raise ProposalNotFoundError.
  • get_changemaker raises ChangemakerNotFoundError.
  • get_funder raises FunderNotFoundError.
  • get_changemaker_field_value_batch raises ChangemakerFieldValueBatchNotFoundError.
  • get_application_form_by_name raises ApplicationFormNotFoundError when no form has that name.

KeycloakClientCredentialsProvider raises TokenRequestError when Keycloak rejects the grant.

Models

Most models are generated from PDC's OpenAPI spec, which is pinned in src/pdc_api/openapi.json. Import them from pdc_api.models; pdc_api._generated is an implementation detail.

The models ignore fields they don't declare. When PDC adds a field to a response, parsing keeps working, and the new field appears once the models are regenerated.

The spec doesn't always match what PDC returns. Some fields it marks required are missing or null in real responses, and a few shapes don't generate usable models. codegen/preprocess.py patches each mismatch before generation, one function per problem. Each rule names the mismatch it patches, and should be deleted once PDC's spec matches its responses. We reported the first batch in PhilanthropyDataCommons/service#2451.

What's not covered yet

The client covers most of the API but not all of it:

  • No client functions: /applicationFormFields, /sources (apart from create_changemaker_source), /tasks (bulk uploads and base field copies), /terminologySets, and /users. Their models are generated, and session.get/session.post reach any endpoint directly.
  • Other writes: creating funders, changemakers, opportunities, and funder or data-provider sources is possible only through the seeding helpers in pdc_api.seeding, which aren't meant for production data.
  • Async: the client is synchronous and built on requests.

Issues and pull requests that fill these gaps are welcome.

Testing your code

pdc_api.testing (extra: testing) registers mocked PDC responses with responses. It has payload builders that return valid response bodies, and add_*_response functions that register them for a base URL:

import responses

from pdc_api import APISession, testing
from pdc_api.client import get_bundle_page
from pdc_api.models import ChangemakerBundle

BASE_URL = "https://pdc.test/"


class StaticToken:
    def get_token(self) -> str:
        return "test-token"

    def refresh_if_necessary(self) -> None:
        pass


@responses.activate
def test_lists_changemakers():
    testing.add_page_response(
        ChangemakerBundle,
        base_url=BASE_URL,
        payload=testing.bundle([testing.changemaker_payload(id=1, name="Acme")]),
    )
    session = APISession(base_url=BASE_URL, token_provider=StaticToken())

    page = get_bundle_page(session, ChangemakerBundle)

    assert page.entries[0].name == "Acme"

Seeding a PDC stack

pdc_api.seeding (extra: seeding) creates realistic data on a PDC stack through the public PDC API and the Keycloak admin API. It is for local development and integration tests, not production:

  • pdc_api.seeding.pdc_entities: seed_* functions for funders, collaboratives, changemakers, fiscal sponsorships, data providers, opportunities, application forms, proposals, initiatives, and field values. seed_proposal_bundle creates a full proposal and everything it depends on in one call.
  • pdc_api.seeding.keycloak_admin: KeycloakAdmin, whose ensure_* methods create Keycloak organizations, users, memberships, and realm roles only if they don't already exist, so re-running a seed script is safe.

Contributing

See CONTRIBUTING.md for development setup, tests, and regenerating the models.

License

AGPL-3.0. Maintained by DrivenData.

Metadata

Release files for pdc-api 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pdc-api 0.4.1
File Size Uploaded Provenance Actions
pdc_api-0.4.1.tar.gz 88.2 kB With provenance Details for pdc_api-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pdc-api 0.4.1
File Interpreter ABI Platform Actions
pdc_api-0.4.1-py3-none-any.whl Python 3 none any Details for pdc_api-0.4.1-py3-none-any.whl

Total release size: 132.7 kB

Release files / pdc_api-0.4.1.tar.gz

Download URL pdc_api-0.4.1.tar.gz
Size 88.2 kB
Tags Source
SHA-256 checksum
How to use checksums
2a6fd57851ebd54a2ba8debb406a36b7eb0fd2fe82599dd57138317d83a9ec27
BLAKE2b-256 checksum
How to use checksums
6e4fb06013d4267dc690877779f786b0be94820d91df686233d09c87506bf341
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / pdc_api-0.4.1-py3-none-any.whl

Download URL pdc_api-0.4.1-py3-none-any.whl
Size 44.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
76092cfb646606cb2e1d45a500a96cf2baa9bb5f10fa78b24581ded90962c389
BLAKE2b-256 checksum
How to use checksums
fe5dd5a4d44fae291682270e7b926a527e718c34e4a6ff2db9a31ddd8ed68f53
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for pdc-api 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pdc_api-0.4.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.4.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page