API docs

Send your key in the Authorization header. It never goes in the URL. In every example RALLYBASE_KEY stands for your key.

Quickstart

# -i prints the status and headers: on a 429, Retry-After says how long to wait. Do not loop or retry blindly.
curl --fail-with-body -sS -i "https://rallybase.org/api/v2/lookup?county=48453" \
  -H "Authorization: Bearer $RALLYBASE_KEY"

# -i prints the status and headers: on a 429, Retry-After says how long to wait. Do not loop or retry blindly.
curl --fail-with-body -sS -i "https://rallybase.org/api/v2/lookup" \
  -H "Authorization: Bearer $RALLYBASE_KEY" \
  -H "x-geocode-address: 1600%20Example%20St%2C%20Austin%2C%20TX"

# Step 1: who holds office at this address, at each level. Federal and state rows carry phone, email and website; on each row,
# source_url is the page the row was read from.
# -i prints the status and headers: on a 429, Retry-After says how long to wait. Do not loop or retry blindly.
curl --fail-with-body -sS -i "https://rallybase.org/api/v2/lookup" \
  -H "Authorization: Bearer $RALLYBASE_KEY" \
  -H "x-geocode-address: 1600%20Example%20St%2C%20Austin%2C%20TX"

The lookup

GET /api/v2/lookup takes a street address, URL-encoded, in the x-geocode-address header, or coordinates in the x-rb-lat and x-rb-lng headers, and answers every level for that point. A five-digit FIPS code in county answers the county officials only. The names, ids and pages in this answer are placeholders.

curl "https://rallybase.org/api/v2/lookup" \
  -H "Authorization: Bearer $RALLYBASE_KEY" \
  -H "x-geocode-address: 1600%20Example%20St%2C%20Austin%2C%20TX"

{
  "license": "Data licensed under the Rallybase API Terms: use, display and analysis in your own product or research; no resale or redistribution as a dataset or competing service; attribution with source links when shown publicly.",
  "snapshot": {
    "id": "snap-example",
    "built_at": "2026-10-28T06:00:00.000Z"
  },
  "freshness": "weekly snapshot",
  "county": {
    "fips": "48453",
    "name": "Travis",
    "state": "TX"
  },
  "officials": [
    {
      "id": "federal-rep-X000001",
      "level": "federal",
      "office": null,
      "office_label": "U.S. Representative, TX-37",
      "name": "Alex Example",
      "jurisdiction": "U.S. House of Representatives",
      "ocd_id": "ocd-division/country:us/state:tx/cd:37",
      "district_key": null,
      "party": "Example Party",
      "phone": "202-555-0100",
      "email": null,
      "website": "https://example.house.gov",
      "source_url": "https://www.example.gov/members",
      "read_at": null,
      "read_basis": "not held — officials.last_synced is a sync or load time, not a read date (see recorded)",
      "recorded_on": "2026-10-27",
      "attribution": null
    },
    {
      "id": "state-ocd-person/00000000-0000-0000-0000-000000000000",
      "level": "state",
      "office": null,
      "office_label": "State Senator, District 14",
      "name": "Sam Example",
      "jurisdiction": "TX Senate",
      "ocd_id": "ocd-division/country:us/state:tx/sldu:14",
      "district_key": null,
      "party": "Example Party",
      "phone": "512-555-0100",
      "email": "sam.example@example.gov",
      "website": "https://www.example.gov/senate/14",
      "source_url": "https://www.example.gov/senate",
      "read_at": null,
      "read_basis": "not held — officials.last_synced is a sync or load time, not a read date (see recorded)",
      "recorded_on": "2026-10-27",
      "attribution": null
    },
    {
      "id": "county-official-48453-county_judge",
      "level": "county",
      "office": "county_judge",
      "office_label": "County Judge",
      "name": "Jane Example",
      "jurisdiction": "Travis County, TX",
      "ocd_id": "ocd-division/country:us/state:tx/county:travis",
      "district_key": null,
      "party": null,
      "phone": null,
      "email": null,
      "website": null,
      "source_url": "https://www.example.gov/county-judge",
      "read_at": "2026-10-20",
      "read_basis": "rb.county_official.fetched_at",
      "recorded_on": null,
      "attribution": null
    },
    {
      "id": "place-official-4805000-mayor-citywide-pat-example",
      "level": "place",
      "office": null,
      "office_label": "Mayor",
      "name": "Pat Example",
      "jurisdiction": "Austin City Council",
      "ocd_id": null,
      "district_key": "place_geoid:4805000",
      "party": null,
      "phone": null,
      "email": null,
      "website": null,
      "source_url": "https://www.example.gov/council",
      "read_at": "2026-10-21",
      "read_basis": "last_verified_on: a person re-read the city page",
      "recorded_on": null,
      "attribution": null
    }
  ],
  "point": {
    "read_at": "2026-10-28T14:03:11.000Z",
    "districts": [
      {
        "name": "Congressional District 37",
        "level": "federal",
        "state": "TX",
        "census_geoid": "4837"
      },
      {
        "name": "State Senate District 14",
        "level": "state",
        "state": "TX",
        "census_geoid": "48014"
      }
    ],
    "bodies": [
      {
        "body_name": "Commissioners Court",
        "body_kind": "county_commission",
        "seats": 5,
        "composition": "A county judge elected countywide and four commissioners elected by precinct.",
        "election_method": "mixed",
        "citation": "Tex. Const. art. V, § 18",
        "source_url": "https://www.example.gov/constitution",
        "verified_on": "2026-09-01",
        "applies_as": "state_default"
      }
    ],
    "place_rosters": [
      {
        "place_geoid": "4805000",
        "place_name": "Austin",
        "state": "TX",
        "status": "rostered",
        "count": 11,
        "reason": null,
        "checked_at": "2026-09-17"
      }
    ]
  },
  "coverage": {
    "county": "held",
    "levels": {
      "federal": "served",
      "state": "served",
      "place": "served",
      "school": "none held",
      "local": "none held"
    },
    "held_not_redistributed": 0,
    "note": "No row held for this lookup was withheld by the licence filter or the row text rules."
  }
}

Each official carries a stable id, source_url, the public page the row was read from, and read_at, the day it was read, or null with read_basis saying why. Federal and state rows carry the office’s published phone, email and website; county, city and school rows carry none in this API. A level with no rows is explained in coverage.levels: “none held”, “could not check” and “held, not redistributed” are different findings, and none says a government has no officials.

How accurate the rows were on re-check

360 of 363 rows matched their source on re-check (99.2%; 95% interval 97.6–99.7%), November 2026.

Method: a random sample of 395 served county and city officer rows, stratified by how the source page is shared and leaving out board seats, each re-read from its own source page; a row matched when that page printed the stored name (beside the office title in 334 of the 360). The 32 rows whose page could not be read are not in the rate. It measures what we stored against what the page printed that day, not whether the page itself was current. Re-measured quarterly. Where our data comes from has the sources.

The free lookup the site uses

The site’s own pages call GET /api/v1/officials/at-point, which takes no key. It stays open for the site. A program calling it, rather than a browser, is held to 10 requests a minute per network, and every answer carries an X-Rallybase-API header pointing here. For programs, use the keyed lookup above: it returns the same officials with snapshot ids, a licence and a monthly allowance.

By plan

The API page says which plans can be bought today.

Moving from the Google Civic Information API

Google retired its two Representatives methods, representativeInfoByAddress and representativeInfoByDivision, on 2025-04-30. Source: developers.google.com/civic-information/docs/v2, read 2026-11-08: the page footer reads "Last updated 2025-04-30 UTC", and the Representatives method pages (representatives/representativeInfoByAddress and representatives/representativeInfoByDivision) answer HTTP 404. We could not retrieve the text of Google’s own notice on that day, so the shutdown date is the page’s last-updated date and the date we recorded earlier, not a quotation.

Read this first: the replacement covers federal, state, county, city and school officials for an address, but it is not a drop-in for the Google responses. Office contact is served for federal and state officials only, and the last list below says what else it leaves out.

What we hold that Google never did

• A source page on each row (source_url) and the day it was read (read_at). Google's responses carried neither.
• A finding for every level (coverage.levels): "none held", "could not check" and "held, not redistributed" are different findings, and none says a government has no officials.
• The districts that contain the point and the governing bodies with their seat counts, read from charter or statute (point.districts, point.bodies).
• The snapshot the answer came from (snapshot.id, snapshot.built_at) and the licence that applies to the data (license).
• A credit the source requires you to show, when one is owed (attribution).

What we do not hold

• Phone numbers, email addresses and websites for county, city and school officials. Federal and state offices' published contact is served; for the rest, the contact details are on the source page.
• Mailing addresses, photographs and social media channels, for any official. The fields Google returned for these (address, photoUrl, channels) have no equivalent here.
• Lookup by OCD division id. Rows carry the id; the lookup takes an address, a point or a county FIPS code.
• Complete local coverage. A county we have not read is reported as "not yet read", and a city whose roster we do not hold is listed in point.place_rosters as not_yet.