Status
The query API is available, and until now it was undocumented. It serves the same records the explorer on this site reads, over HTTPS, with no key and no account.
It is not versioned. Response shapes may change without notice, and no stability guarantee is offered yet. Anything published from it should be quoted with the date it was retrieved.
Endpoints
The base URL is https://api.g3observatory.org. Every response is JSON, and carries a meta block giving the collection wave, the dataset, and the coverage state at the moment of the request.
| Endpoint | Returns |
|---|---|
| GET / | Service status and the endpoint list. |
| GET /health | The same payload; use either. |
| GET /institutions | The registry, filtered and paged. |
| GET /institutions/{institution_uid} | One institution, with its findings. |
| GET /aggregates | Totals, and counts by country, by government level, and by evidence state. |
Filtering and paging
These parameters apply to the institutions endpoint.
- country_iso3, government_level, branch, institution_type, evidence
- Filter on exact values.
- q
- Matches an institution’s name, its country and its type, so a result need not carry the word in its name at all. It also covers a notes field the response does not return.
- sort
- Takes name, country, relevance or findings.
- limit
- An integer from 1 to 200.
- cursor
- The next_cursor value from the previous response, sent with the same query and sort. When next_cursor comes back null there are no further pages. Not accepted when sorting by relevance or findings, which page by offset.
- offset
- The alternative to cursor: skip this many rows instead of walking from the previous page. The relevance and findings sorts can only be paged this way, because a rank is computed rather than stored. Sending both returns 400, and so does exceeding the maximum.
- wave
- Selects the collection wave. Defaults to the current one.
On every listing response, meta.total is the number of records matching the filter, and meta.total_is_exact says whether that number is a count or an estimate.
Errors and limits
Errors return a JSON body with an error code and a message. An unknown parameter, a limit outside the permitted range, or an unrecognised sort returns 400 and names the problem. An unknown institution returns 404. Requests are rate-limited by address, and going over the limit returns 429 with a Retry-After header.
Reading the numbers
The evidence_status field on each record is the four-state vocabulary described under Review states on the methodology page, and it is worth reading there before the counts are used. Two of the four are easy to misread. Not yet reviewed is most of the registry and is not a negative finding. Unclear, shown as possible AI use, is a search that did not settle the question, and it is not a documented finding. The filter evidence=documented_or_unclear lists documented and unclear records together.
The coverage block reports state as in_progress while collection is running, which it currently is. Counts move when the published views are refreshed, so a figure taken from this API is a figure at a moment, and the as_of timestamp in the same block is that moment.
The documented count counts institutions and never activities. An institution with six recorded deployments counts once.
Bulk access and terms
The registry can be searched and filtered through the site itself, and researchers who need the data in bulk can make a request.
The data are published under CC BY 4.0 and the code under MIT; the terms, and how to credit the project, are set out on the bulk-access page.