API Reference

Entity and report counts on this page are a snapshot as of when it was last built. The corpus rebuilds daily; for the current totals see meta/last-updated.json, whose built_at field names the build they belong to. This source repository is private, so to report an error in the data, email api@ungovr.org naming the entity or report and what looks wrong.

Entity Endpoints

Browse and search government entities across 200+ countries.

Endpoint	Description	Auth
/entities/index.json	List all countries with entity counts	Open
/entities/{cc}.json	List first-tier entities for a country (e.g., us)	Open
/entities/{cc}/{state}.json	List entities within a state or province	Open
/entities/detail/{id}.json	Full detail for a single entity	Open
/entities/children/{id}.json	List child entities of a parent	Open
/entities/boundaries/{id}.geojson	GeoJSON boundary for an entity	Open

Product Endpoints

Which UnGovr products (UnGovr Request, Civil Grand Jury) are offered where. Every entity detail record also carries this as a products array, each item an id, name, and availability of direct or descendants (with a supported_count when it is descendants).

Endpoint	Description	Auth
/products.json	Every product, with the total count of entities where it is offered directly	Open
/products/{id}.json	Full supported-entity hierarchy for one product (e.g. request, cgj)	Open

Law Endpoints

Government transparency laws as data: public records laws with deadlines, fees, exemptions and appeal processes, plus a cross-domain index spanning records, meetings, fiscal transparency, accessibility, and oversight statutes.

Endpoint	Description	Auth
/laws/records/index.json	Full records-law corpus, compact index	Open
/laws/records/{jurisdiction}.json	One records law in full ('us--ca'; national laws use the country code, US federal is 'us')	Open
/laws/transparency/index.json	Transparency laws across five domains, one uniform index	Open

CGJ Endpoints

Access California Civil Grand Jury reports, findings, and recommendations.

Endpoint	Description	Auth
/cgj/index.json	CGJ collection summary and statistics	Open
/cgj/counties.json	List all 58 counties with report counts	Open
/cgj/counties/{code}.json	Reports for a specific county (e.g., ventura)	Open
/cgj/reports/{id}.json	Full report detail with findings & recommendations	API Key

AI and Crawling Law

Verdict-level summaries of how each jurisdiction's law treats automated access: crawl policy, a per-scenario access matrix, and fields such as robots.txt legal weight and text-and-data-mining opt-out status. Every response carries as_of_date, confidence, and stale flags. These files are a research summary, not legal advice and not authorization to access any system.

Endpoint	Description	Auth
GET /v1/ai-laws/index.json	Covered jurisdictions with freshness metadata	API Key
GET /v1/ai-laws/{jurisdiction}.json	One jurisdiction; slugs are lowercase, for example us, us/ca, eu	API Key
GET /v1/ai-laws/vocab.json	Definitions for every verdict and field value	API Key

Metadata

Schema definitions, versioning, and update timestamps.

Endpoint	Description	Auth
/meta/countries.json	Country code registry with names and coverage status	Open
/meta/schema.json	JSON Schema definitions for all response types	Open
/meta/openapi.yaml	OpenAPI 3.1 specification	Open
/meta/last-updated.json	Timestamp of the most recent data refresh	Open

Bulk Downloads

Download complete datasets as JSON files for offline analysis, research, or integration into your own systems. All files are available at the same base URL.

Entity Data

Government entity listings by country and state. Each file contains entity names, types, parent relationships, and website URLs.

File	Description
entities/index.json	Country index with entity counts
entities/us.json	United States: states and federal entities
entities/us/ca.json	California: counties, cities, special districts
entities/ie.json	Ireland: local authorities, counties
entities/uk.json	United Kingdom: councils, devolved bodies

Replace the country code in the URL to download data for any supported country. Use index.json to see all available country codes.

CGJ Reports

File	Description
cgj/index.json	Collection summary and statistics
cgj/counties.json	All 58 counties with report counts
cgj/counties/ventura.json	Ventura County reports
cgj/counties/los-angeles.json	Los Angeles County reports

Schema & Metadata

File	Description
meta/countries.json	Country code registry with names and coverage
meta/schema.json	JSON Schema definitions for all response types
meta/openapi.yaml	OpenAPI 3.1 specification
meta/last-updated.json	Timestamp of the most recent data refresh

Rate Limits

Resource	Free Tier
Entity data	100/day per IP
CGJ indices & county listings	Unlimited
CGJ report detail	50/day per key
Cache revalidation (304)	Free, 5,000/day per key

Conditional Requests

Every keyed response carries an ETag. Send it back on the next request as If-None-Match, and if nothing has changed the API answers HTTP 304 Not Modified with no body and spends none of your daily allowance. The X-Quota-* headers on a 304 report the same counter as before, so you can confirm the revalidation was free.

A 304 still requires a valid API key. Conditional requests are capped at 5,000 per key per day, well above any normal use; past that the API returns HTTP 429 with a Retry-After.

The bulk export manifest at https://data.ungovr.org/v1/ai-laws/export/manifest.json is the cheapest thing to revalidate. Its built_at field is the corpus version, so an unchanged manifest means the much larger data files it lists are unchanged too and need not be fetched at all.

Machine Payments (MPP)

When free-tier limits are exceeded, the API returns HTTP 402 with a Machine Payments Protocol challenge. AI agents and programmatic clients can pay per request from a pre-loaded wallet funded via Stripe.

Resource	Price
Entity data	$0.001
CGJ report detail	$0.01

Minimum wallet top-up is $5.00. Payments are processed via WWW-Authenticate: Payment / Authorization: Payment headers. See the MCP page for the equivalent JSON-RPC flow.

Register for an API Key