Practical Guide: Building with the Presidents.Cloud API

Developers and civic technologists want reliable programmatic access to presidential records. This guide covers authentication, common endpoints, rate limits, best practices for caching, and sample queries to accelerate your integration.

Authentication and keys

Sign up for a free developer account to receive an API key. Free plans allow modest usage for prototyping; academic and newsroom partners can request elevated access.

Keys are sent as a header in requests:

Authorization: Bearer YOUR_API_KEY

Core endpoints

Our most-used endpoints are:

• /v1/presidents — search and filters (country, dates, party)
• /v1/presidents/{id} — full record with sources
• /v1/speeches — text index and metadata
• /v1/approval — harmonized time series
• /v1/events — annotated timeline events linked to actors

Practical examples

Example 1: Create a timeline widget that shows presidential terms for a country. Use /v1/presidents?country=US&fields=slug,name,term_start,term_end to get lightweight payloads suitable for fast rendering.

Example 2: Display the most-cited speeches by a president. Query /v1/speeches?president=theodore-roosevelt&sort=citations_desc&limit=5 and render titles with links to our transcript pages.

Rate limits and caching

We enforce rate limits to ensure fair use. Implement an exponential backoff for retries. For dashboards, cache stable resources (biographical records, term metadata) for longer intervals; dynamic resources like polls may require hourly refreshing.

Data model tips

Our records include nested objects for sources and identifiers. When designing your database schema, normalize entities like persons, offices, and sources to avoid duplication. Use our canonical IDs to maintain referential integrity across datasets.

Handling multilingual sources

Presidential records may link to sources in many languages. We include language metadata and automatic language-tags for text fields. For user-facing apps, you can show the original text with a machine-translated preview, but always surface the original for verification.

Error handling and provenance

When a field is disputed or uncertain, our API returns a provenance block describing the source confidence and alternate values. Surface this to power users so they can understand the uncertainty rather than hide it.

Community and contribution

Found a missing source or discrepancy? Use our contribution endpoint to submit citations and notes. All community contributions are tracked and curators review them against existing evidence.

Sample code snippet (pseudo)

// Fetch lightweight president list
fetch('https://api.presidents.cloud/v1/presidents?country=US&fields=slug,name,term_start,term_end', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
})
.then(r => r.json())
.then(data => renderTimeline(data))