A lot of political and institutional knowledge lives in prose: encyclopedia articles, papers and long reports. That is fine for reading, but hard to query. You can't easily ask "which experiments use sortition, and which of the claims about them are disputed?" unless someone has already structured it. Polity Atlas is built the other way round. The pages are views over a graph, and the graph is published through an open API.

This post is a short tour for developers and researchers who would rather start from JSON than from a web page.

The basics

  • Base URL: https://polityatlas.org/api/v1
  • Schema: an OpenAPI 3.1 document at /api/v1/openapi.json, plus interactive docs.
  • Authentication: none for reading. Writing (for signed-in contributors) uses the Django session cookie and a CSRF token.
  • Pagination: list endpoints take page and page_size and return {"items", "count", "page", "page_size"}.
  • Errors: always {"detail": "…"} with a meaningful status code (400, 401, 403, 404, 409, 422, 429).
  • Localisation: add ?lang=ru (or send Accept-Language) for Russian fields. Missing translations fall back to English.
  • Licence: the developers page lists content under CC BY-SA 4.0 and data under ODbL.

One request

The canonical example on the developers page fetches a single entity:

curl "https://polityatlas.org/api/v1/entities/polycentric-law?lang=en" 
import httpx r = httpx.get("https://polityatlas.org/api/v1/entities/polycentric-law?lang=en") entity = r.json()

The response is not just a title and a summary. It returns the entity with its relations grouped by type (for example, which mechanisms implement it), its claims with evidence and sources, and its assessments. Each claim carries two separate fields:

  • epistemic_status: established, theory, disputed, hypothesis or forecast
  • verification_status: unverified, AI-drafted, in review, verified or rejected

Keeping those apart is the useful bit. "Disputed but verified" is a perfectly normal state: the dispute is real and documented, and the record of it has been checked.

What you can query

The endpoint reference on the developers page is grouped by the site's sections:

Knowledge

  • GET /entities with filters for kind, theme, tag and free text
  • GET /entities/{slug}/graph for an ego network, one or two hops deep
  • GET /graph for the whole published graph
  • GET /claims/{id} for a claim, its evidence, sources and open disputes
  • GET /sources, GET /glossary, and GET /search with keyword or semantic mode
  • POST /ask for an answer built only from published claims

Living Atlas

  • GET /experiments with filters including a bounding box, autonomy and whether AI is used
  • GET /experiments/geojson returns a GeoJSON FeatureCollection, ready for a map
  • GET /experiments/network for network polities and shared mechanisms
  • GET /experiments/facets for counts per facet value

Explorer and Observatory

  • GET /criteria and POST /explorer/compare for weighted comparisons over known criteria
  • GET /observatory (signals, news, research, briefings) and GET /scenarios

Polity Lab

  • GET /lab/options for configuration dimensions and stress scenarios
  • GET /repository/components for versioned institution components

And for bulk work there is GET /export/entities.jsonl, the full graph as JSON Lines, refreshed nightly.

The vocabulary

Everything uses one ontology, which is documented on the same page. Entity kinds include concept, mechanism, theory, thinker, experiment, institution type, ideology and organisation. Relations are typed: implements, tested_in, proposed_by, influenced, criticises, alternative_to, part_of, uses_mechanism and related_to.

Typed relations are what make the graph worth querying. "Quadratic voting is tested in these experiments" and "this thinker criticises that concept" are different statements, and the API keeps them apart instead of flattening everything into "see also".

A few things you could build

None of these exist yet as far as we know. They are just the obvious uses:

  • A map layer of operating and closed experiments for a teaching site, straight from the GeoJSON endpoint.
  • A reading list generator that walks proposed_by and influenced edges from a concept to its thinkers.
  • A notebook that pulls the JSONL export and checks how many claims about a mechanism are disputed versus established.
  • A citation helper that resolves an entity slug to its sources.

If you do build something, the licences ask for attribution (CC BY-SA for content, ODbL for data).

Notes and limits

Reading is anonymous with "generous rate limits", and the OpenAPI description documents X-RateLimit-* headers. Be polite with bulk jobs and use the JSONL export rather than paging through everything. Russian is the documented second language for API fields. Governance Explorer scores are described on the methodology page as editorial judgements against stated criteria, so treat them as illustrative rather than as measurements.

Polity Atlas is built by Spicanet. The full reference is on the developers page.

Polity Atlas: polityatlas.org. Originally published on Polity Atlas. Studio write-up on spicanet.dev: Design an institution. Then try to break it.