go-v.org · hub

go-v.org · developer documentation

Read the public record as JSON.

Key-free GET endpoints over the same live corpora that back the pages. Every response names its source, every sample below was captured from the live API, and an unreachable upstream is reported instead of being hidden.

OpenAPI 3.1 datasets.json

Quickstart

All public reads are HTTP GET and return JSON. Start with the hub search, then follow a result to the service that owns the row.

curl
curl -sS "https://go-v.org/api/v1/search?q=kenya&limit=1" | python3 -m json.tool

Base URL for this hub: https://go-v.org. The seven worked examples use the service that owns each record, not a proxy.

Authentication

Public endpoints need no key. Send a normal GET request. Do not put credentials in a query string: query strings end up in logs, browser history and shared links.

An optional X-API-Key header requests the elevated search tier. Keys are stored as SHA-256 hashes; sending an unknown key is treated as anonymous, never as an error.

curl
curl -sS -H "X-API-Key: $GOV_KEY" "https://go-v.org/api/v1/search?q=kenya&limit=1"

CORS: the hub search route returns Access-Control-Allow-Origin: * for browser clients. Other services apply their own policies.

Rate limits

Limits are per client IP and use a rolling 60-second window. The HTML search and the JSON search share a 300-request window for anonymous clients; the JSON route also uses a 60-request general API window, so the stricter limit applies there. Elevated keys raise the search window to 600 requests per minute.

curl
curl -sS -D - -o /dev/null "https://go-v.org/api/v1/search?q=kenya&limit=1"
  • X-RateLimit-Limit — requests allowed in the window.
  • X-RateLimit-Remaining — requests left.
  • X-RateLimit-Window — window length in seconds.
  • Retry-After — seconds to wait after a 429.

A 429 is a real answer, not a failed sample: back off, then retry. Other hosts may enforce their own upstream or search budgets and will say so in the status code.

Pagination

Simple routes take a limit and return the newest or best rows. The event contract uses an opaque cursor: read next_cursor and send it back as cursor. Do not construct a cursor by hand.

curl
curl -sS "https://intel.go-v.org/v1/events?limit=2&cursor=MjAyNjExMTkxNTQ1MDB8MTMzNDAyMzQ4OA=="

Other caps are documented per route: patent and document exports accept limit; document search returns at most 500 rows, so narrow with q or cc rather than assuming an offset. A null next_cursor means the end of the result set.

Errors

Errors are JSON where the route is JSON, and the HTTP status is the primary signal. Empty data is returned as an empty array with count: 0, never as a fabricated row.

StatusMeaningWhat to do
200Success, including an honest empty result.Read count before assuming rows.
400Missing or malformed parameter.Fix the query; the body names the problem.
404Unknown record, country or route.Check the locator; do not retry blindly.
429Rate limit reached.Wait for Retry-After.
502/503Upstream unavailable or output missing.Retry later; the body may name the source.
JSON
{
 "error": "rate limited",
 "retry_after": 12
}

Worked examples

Seven services, one real response each. The curl is copyable; the JSON is an actual 200 response captured 2026-11-19T17:20:00Z. Where an array is shortened for display, the caption says so.

Worked example

Live events

intel.go-v.org · GET

Open endpoint

GDELT-derived events with a verification state and a source trail. The cursor is opaque; pass next_cursor back as cursor to page forward.

Request

curl
curl -sS "https://intel.go-v.org/v1/events?limit=1"

Response shape

  • events[]
  • events[].id
  • events[].reported_at
  • events[].verification.state
  • events[].source_trail[]
  • count
  • total
  • next_cursor
  • generated_at
  • meta.contract

Live JSON sample

Verbatim 200 response; the meta block explains the time and verification semantics.

JSON
{
 "events": [
  {
   "id": "1334023488",
   "story_id": "s1333806296",
   "reported_at": "2026-11-19T15:45:00+00:00",
   "first_seen_at": "2026-11-19T15:46:22Z",
   "last_corroborated_at": "2026-11-19T15:46:22Z",
   "revision": 1,
   "type": "express intent",
   "subtype": "036",
   "category": "statement",
   "type_bucket": "diplomacy",
   "description": "NATIVE AMERICAN → INDIGENOUS: express intent",
   "location_name": "USCT, US",
   "actor_attacker": "NATIVE AMERICAN",
   "actor_target": "INDIGENOUS",
   "attacker_country": null,
   "target_country": null,
   "reported_killed": null,
   "reported_wounded": null,
   "casualties": null,
   "verification": {
    "state": "UNCORROBORATED",
    "sources": 1,
    "articles": 1,
    "mentions": 1
   },
   "actors": [
    "NATIVE AMERICAN",
    "INDIGENOUS"
   ],
   "country": "US",
   "admin1": "USCT",
   "location": {
    "lat": 41.7768,
    "lon": -72.7054
   },
   "headline": "NATIVE AMERICAN → INDIGENOUS: express intent",
   "source_trail": [
    {
     "url": "https://dailycampus.com/2026/11/19/the-native-american-cultural-programs-a-place-of-history-and-acceptance/",
     "host": "dailycampus.com",
     "class": "reporting-domain"
    }
   ]
  }
 ],
 "count": 1,
 "total": 377466,
 "next_cursor": "MjAyNjExMTkxNTQ1MDB8MTMzNDAyMzQ4OA==",
 "generated_at": "2026-11-19T17:22:28Z",
 "meta": {
  "contract": "go-v events v1",
  "verification_rule": {
   "UNCORROBORATED": "one distinct reporting domain",
   "REPORTED": "two distinct domains",
   "CORROBORATED": "three to five distinct domains",
   "WIDELY REPORTED": "six or more distinct domains",
   "VERIFIED": "not issued: requires an official primary document, which this feed does not store"
  },
  "time_semantics": "reported_at is the event date published by the source; first_seen is when this system ingested it. They are different clocks.",
  "actor_countries": "attacker_country and target_country are Actor1CountryCode / Actor2CountryCode from the GDELT 2.0 export, mapped ISO3->ISO2 through the local country table. Non-country actor codes and unknown codes are null, never inferred from names.",
  "casualties": "null on each event. UCDP GED 25.1 is ingested as country-month totals only (/v1/casualties.json): GDELT and UCDP code events independently, so attaching a UCDP death count to a GDELT event would be an invented match. reported_killed and reported_wounded stay null for the same reason.",
  "story_rule": {
   "key": "root + country + admin1 (exact, empty allowed)",
   "window": "an event joins a story when its reported_at is within 48 hours after that story's first event",
   "overlap": "at least one normalised actor name is shared with any event already in the story",
   "assignment": "chronological by reported_at; the joining event picks the matching story with the latest first_event, then the smallest story_id",
   "story_id": "s<first event id>; every event belongs to exactly one story (singleton when no rule matches)",
   "scope": "CAMEO two-digit roots only; natural-hazard rows (earthquake,dr,tc) and malformed roots are singleton stories because they are physical records, not actor narratives"
  },
  "bucket_rule": {
   "protest": "CAMEO root 14",
   "violence": "CAMEO roots 18,19,20",
   "coercion": "CAMEO roots 13,15,17",
   "aid": "CAMEO root 07",
   "diplomacy": "CAMEO roots 01-06,08-12,16",
   "disaster": "stored natural-hazard roots earthquake,dr,tc",
   "election": "no CAMEO root; requires GDELT GKG themes, not stored",
   "economy": "no CAMEO root; requires GDELT GKG themes, not stored",
   "health": "no CAMEO root; requires GDELT GKG themes, not stored",
   "energy": "no CAMEO root; requires GDELT GKG themes, not stored",
   "migration": "no CAMEO root; requires GDELT GKG themes, not stored",
   "other": "any other stored root"
  },
  "pair_rule": "directed cross-country pairs from actor1_cc/actor2_cc; same-country and missing-code rows are excluded, not imputed. Windows use reported_at (ts), not ingest time."
 }
}

Worked example

Encyclopedia article

encyclopegia.org · GET

Open endpoint

An immutable article snapshot with claims, named sources, citations in nine formats, a ledger receipt and any contradictions the engine holds.

Request

curl
curl -sS "https://encyclopegia.org/a/ada-lovelace.json"

Response shape

  • slug
  • title
  • lead
  • qid
  • content_hash
  • snapshot_id
  • license
  • license_class
  • source_uri
  • categories
  • url
  • claims[]
  • citations{}
  • ledger_receipt{}
  • contradictions[]
  • flags{}

Live JSON sample

Excerpt from the 200 response: the lead is verbatim, claims are shortened to two and the citation map to APA only.

JSON
{
 "slug": "ada-lovelace",
 "title": "Ada Lovelace",
 "lead": "Augusta Ada King, Countess of Lovelace ( ; 10 December 1815 – 27 November 1852), also known as Ada Lovelace, was an English mathematician and writer chiefly known for work on Charles Babbage's proposed mechanical general-purpose computer, the analytical engine. She was the first to recognise the machine had applications beyond pure calculation. Lovelace is often considered the first computer programmer. Lovelace was the only legitimate child of poet Lord Byron and reformer Anne Isabella Milbanke. Lord Byron separated from his wife a month after Ada was born, and died when she was eight. Although often ill in childhood, Lovelace pursued her studies assiduously. She married William King in 1835. King was a Baron, and was created Viscount Ockham and 1st Earl of Lovelace in 1838. The name Lovelace was chosen because Ada was descended from the extinct Baron Lovelaces. The title given to her husband thus made Ada the Countess of Lovelace. Lovelace's educational and social exploits brought her into contact with scientists such as Andrew Crosse, Charles Babbage, David Brewster, Charles Wheatstone and Michael Faraday, and the author Charles Dickens, contacts which she used to further her education. Lovelace described her approach as \"poetical science\" and herself as an \"Analyst (& Metaphysician)\".…",
 "qid": "local:ada-lovelace",
 "content_hash": "f00791dcbe9366a8d58801b154e7915766ded11e4c8469b436415134878548d6",
 "snapshot_id": "ada-lovelace-000002-f00791dcbe9366a8",
 "license": "CC BY-SA 4.0",
 "license_class": "tier3-original",
 "source_uri": "https://en.wikipedia.org/w/index.php?oldid=1376338287",
 "categories": [
  "Mathematicians",
  "Computing",
  "19th century"
 ],
 "url": "https://encyclopegia.org/a/ada-lovelace",
 "claims": [
  {
   "id": 3,
   "predicate": "date of birth",
   "object": "10 December 1815",
   "object_num": 18151210.0,
   "polarity": 1,
   "confidence": 0.9,
   "source_name": "project assertion — no external source",
   "source_uri": null,
   "source_tier": null,
   "retrieved_at": 1792300607.826807,
   "anchored": true
  },
  {
   "id": 4,
   "predicate": "date of death",
   "object": "27 November 1852",
   "object_num": 18521127.0,
   "polarity": 1,
   "confidence": 0.9,
   "source_name": "project assertion — no external source",
   "source_uri": null,
   "source_tier": null,
   "retrieved_at": 1792300607.826807,
   "anchored": true
  }
 ],
 "citations": {
  "apa": "Anticloud FZ LLE. (2026-10-18). *Ada Lovelace*. encyclopegia.org. [Identifier: da-lovelace-000002-f00791dcbe9366a8] Derived from https://en.wikipedia.org/w/index.php?oldid=1376338287. Licensed CC BY-SA 4.0."
 },
 "ledger_receipt": {
  "chain_hash": "35acbcc9a65169616ac36cb7c86b6bdc025ea726f71d1245ff7986217c9728fe",
  "content_root": "c0e582ea2555a81e3349eb1d651382bf82c61db920943898a9eac6b591e3d0ee",
  "files": [
   {
    "path": "content",
    "sha3_256": "f00791dcbe9366a8d58801b154e7915766ded11e4c8469b436415134878548d6"
   }
  ],
  "id": "ada-lovelace-000002-f00791dcbe9366a8",
  "kind": "article.seal",
  "license": "Anticloud Synthetic Licence 1.0",
  "license_class": "tier3-original",
  "prev_hash": "b97f236c601e79052dc9196892988022ac370cea4a0fd73f3979eaf0c7af485a",
  "seal": null,
  "seq": 2,
  "sig": "ceda27dc3a4aca7434d9617f9b5b2c09e02c299a4c7e69823127ee1f320f1042",
  "signing_key_id": "30b795d699fde2c0",
  "subject": "ada-lovelace",
  "tier": 3,
  "timestamp": 1792300607.826807,
  "upstream_slug": "ada-lovelace"
 },
 "contradictions": [
  {
   "id": 1,
   "claim_a": 3,
   "claim_b": 6,
   "kind": "date",
   "score": 0.99,
   "detail": "10 December 1815 vs 10 December 1810",
   "a_conf": 0.9,
   "b_conf": 0.35,
   "a_source": null,
   "b_source": "project assertion — no external source"
  }
 ],
 "flags": {
  "advisory": true,
  "contradictions": 1,
  "confidence": 0.705
 }
}

Worked example

Patent record

patents.go-v.org · GET

Open endpoint

Full-text patent search returning a locator-ready publication number and a highlighted excerpt. Counts are what the service holds, not an inferred universe.

Request

curl
curl -sS "https://patents.go-v.org/patents.json?q=battery&limit=1"

Response shape

  • query
  • count
  • full_text_total
  • source
  • patents[].pubnum
  • patents[].title
  • patents[].filing_date
  • patents[].excerpt

Live JSON sample

Verbatim 200 response.

JSON
{
 "query": "battery",
 "count": 1,
 "full_text_total": 10753297,
 "source": "local patents_text FTS",
 "patents": [
  {
   "pubnum": "US17337051",
   "title": "Illuminated Visual Display Container Having Minimal Glare",
   "filing_date": "2013-01-25",
   "excerpt": "…1 and 1A, an example light testing setup for an illuminated container, is shown without the battery pack. The light testing setup is used…"
  }
 ]
}

Worked example

Statistics indicator

stats.go-v.org · GET

Open endpoint

One indicator with a global total, ranked country observations, named source and data year. A missing observation is not replaced by zero.

Request

curl
curl -sS "https://stats.go-v.org/api/stats/population.json"

Response shape

  • indicator
  • label
  • unit
  • nature
  • source
  • source_uri
  • generated_at
  • series_key
  • series_unit
  • row_label
  • row_nature
  • countries[].iso2
  • countries[].name
  • countries[].value
  • countries[].year
  • countries[].rank
  • global.value
  • global.year
  • global.coverage

Live JSON sample

Excerpt from the 200 response: countries are shortened to the top three; the global block is verbatim.

JSON
{
 "indicator": "population",
 "label": "World population",
 "unit": "people",
 "nature": "measured",
 "source": "World Bank World Development Indicators",
 "source_uri": "https://data.worldbank.org/indicator/SP.POP.TOTL",
 "generated_at": "2026-11-19T05:43:26Z",
 "series_key": "population",
 "series_unit": "people",
 "row_label": "Population",
 "row_nature": "measured",
 "global": {
  "id": "population",
  "label": "World population",
  "value": 8192078152.0,
  "unit": "people",
  "year": "2025",
  "nature": "measured",
  "source": "World Bank World Development Indicators",
  "source_uri": "https://data.worldbank.org/indicator/SP.POP.TOTL",
  "method": "Sum of latest WDI population for 217 countries. The per-second ticker is modelled from the measured year-on-year change.",
  "annual": null,
  "per_second": 2.3637748030925163,
  "coverage": 217,
  "status": "ok"
 },
 "countries": [
  {
   "iso2": "IN",
   "name": "India",
   "value": 1463865525.0,
   "year": 2025,
   "rank": 1,
   "source": "World Bank World Development Indicators",
   "source_uri": "https://data.worldbank.org/indicator/SP.POP.TOTL"
  },
  {
   "iso2": "CN",
   "name": "China",
   "value": 1406585000.0,
   "year": 2025,
   "rank": 2,
   "source": "World Bank World Development Indicators",
   "source_uri": "https://data.worldbank.org/indicator/SP.POP.TOTL"
  },
  {
   "iso2": "US",
   "name": "United States",
   "value": 341784857.0,
   "year": 2025,
   "rank": 3,
   "source": "World Bank World Development Indicators",
   "source_uri": "https://data.worldbank.org/indicator/SP.POP.TOTL"
  }
 ]
}

Worked example

Country coverage

estate.go-v.org · GET

Open endpoint

One country record plus its per-lane coverage. Yellow means partial, green means the claimed observation or corpus is actually held, no-data means the source publishes no observation.

Request

curl
curl -sS "https://estate.go-v.org/ke/estate.json"

Response shape

  • @context
  • @type
  • identifier
  • iso3
  • name
  • region
  • income_level
  • capital
  • population
  • gdp
  • life_expectancy
  • labels{}
  • indicators[]
  • coverage[].lane
  • coverage[].status
  • coverage[].note
  • coverage[].source_url
  • sources[]
  • generated_at
  • note
  • indicator_count

Live JSON sample

Excerpt from the 200 response: labels are shortened to six languages, indicators to two rows and coverage to four lanes.

JSON
{
 "@context": "https://schema.org",
 "@type": "Country",
 "identifier": "KE",
 "iso3": "KEN",
 "name": "Kenya",
 "region": "Sub-Saharan Africa ",
 "income_level": "Lower middle income",
 "capital": "Nairobi",
 "population": {
  "value": 57532493,
  "year": "2025"
 },
 "gdp": {
  "value_usd": 135941278878.815,
  "year": "2025"
 },
 "life_expectancy": {
  "value": 63.834,
  "year": "2024"
 },
 "sources": [
  {
   "name": "World Bank Open Data",
   "url": "https://api.worldbank.org/v2/",
   "license": "World Bank Open Data terms"
  }
 ],
 "generated_at": 1795042800.0,
 "note": "Coverage status scores are measured from ingested rows. yellow = partial source and, for series lanes, means “series only, no document corpus”; green = the claimed observation or corpus is actually held; no-data = the authoritative source publishes no observation, red-empty = a lane this service has not built (none today).",
 "indicator_count": 83775,
 "labels": {
  "ab": "Кениа",
  "ace": "Kenya",
  "acm": "كينيا",
  "ady": "Кение",
  "aeb-arab": "كينيا",
  "af": "Kenia"
 },
 "indicators": [
  {
   "key": "account_ownership",
   "value": 90.1199173733613,
   "year": "2024",
   "source": "World Bank FX.OWN.TOTL.ZS",
   "source_uri": "https://data.worldbank.org/",
   "license": "CC BY 4.0",
   "hash": "0c8c571bad286d69c6b576ec6385ec4dfc0836aed3058dd7aefc8635d41e0526"
  },
  {
   "key": "account_ownership_pct",
   "value": 90.1199173733613,
   "year": "2024",
   "source": "World Bank",
   "source_uri": "https://data.worldbank.org/",
   "license": "CC BY 4.0",
   "hash": "8dc04907f1610a8ab651d38367a52705d4ba6adc561e0dc1e4df561ba19e066f"
  }
 ],
 "coverage": [
  {
   "lane": "patents",
   "status": "yellow",
   "note": "patent application counts (residents + non-residents) from the World Bank/WIPO series; patent documents are not ingested Series only, no document corpus.",
   "source_url": "https://data.worldbank.org/indicator/IP.PAT.RESD",
   "updated_at": 1795076843.49463,
   "status_text": "series only, no document corpus"
  },
  {
   "lane": "legal",
   "status": "yellow",
   "note": "278 primary documents ingested (US CFR 2024 + Federal Register); court decisions and non-federal law are missing. Other countries carry a Factbook legal-system description only.",
   "source_url": "https://legal.go-v.org/",
   "updated_at": 1795107750.0376458,
   "status_text": "partial document corpus"
  },
  {
   "lane": "alerts",
   "status": "green",
   "note": "1 alert row(s) in the current GDACS/USGS window | 2026-10-29 audit: VERIFIED COMPLETE — full current GDACS (125) + USGS (284) window (409 alert rows) with per-record metadata. Kept green.",
   "source_url": "https://eas.go-v.org/",
   "updated_at": 1793237821.274261,
   "status_text": "records held; no document corpus"
  },
  {
   "lane": "defense",
   "status": "yellow",
   "note": "military expenditure (% of GDP), SIPRI series via World Bank; not procurement, capabilities or intent Series only, no document corpus.",
   "source_url": "https://data.worldbank.org/indicator/MS.MIL.XPND.GD.ZS",
   "updated_at": 1795077157.5077767,
   "status_text": "series only, no document corpus"
  }
 ]
}

Try it

Three safe GET endpoints, called from this page against the same origin. No key, no write, no cross-origin request. The response is bounded for display.

GET only · no key · same origin

Response
Send a request to see the live response.

OpenAPI

The machine-readable contract covers the three try-it routes, their parameters, response fields and error statuses.

Open /openapi.json Browse the dataset catalogue

The OpenAPI document describes this hub. Service-specific routes are linked from each worked example and from /datasets.