VoterGuideOS
API Specificationsraces

Find races

Returns paginated races. Core race reads require an organization overlay context supplied by `overlayOrganizationId` or the `X-Organization-Id` header. When `$search` is supplied, `election` is required.

GET
/races

Query Parameters

$limit?integer

Maximum number of records to return.

Range0 <= value
$skip?integer

Number of records to skip.

Range0 <= value
$sort?

Sort object, for example $sort[createdAt]=-1.

_id?|array<>

Race id or ids.

$search?string

Full-text/fuzzy search against race office and candidate search terms. Must be paired with election.

election?|array<string>

Election key or keys.

raceKey?|array<string>

Stable race key or keys.

district?|

District id, or district[$intersectsWith] to find races whose districts intersect the supplied district id or ids.

office?string

Office key.

party?string

Party key for partisan primary races.

$populate?array<>

Includes selected joined data. Pass $populate[]=candidates to replace the default slim candidates with full candidate records.

$includeParentDistrict?boolean

Includes parent district details on populated race districts.

overlayOrganizationId?string

Organization overlay id. When supplied, the overlay service merges the organization's race overrides into global races, includes organization-created races, excludes organization-deleted races, restricts results to the organization's supported area, and returns the external organization-authenticated race shape. The same overlay context may also be supplied with the X-Organization-Id header.

Match^[a-fA-F0-9]{24}$

Header Parameters

X-Organization-Id?string

Organization id used as the overlay organization context. Equivalent to overlayOrganizationId; when both are supplied, the query parameter takes precedence.

Match^[a-fA-F0-9]{24}$

Response Body

application/json

Paginated race results.

TypeScript Definitions

Use the response body type in TypeScript.

application/json

Request validation failed.

TypeScript Definitions

Use the response body type in TypeScript.

application/json

Missing organization overlay context.

TypeScript Definitions

Use the response body type in TypeScript.

curl -X GET "https://example.com/races" \  -H "X-Organization-Id: org_123"
{
  "total": 0,
  "limit": 0,
  "skip": 0,
  "data": [
    {
      "_id": "65d4f20f8f5a4d7e9a123456",
      "election": "string",
      "office": "string",
      "raceKey": "string",
      "district": {
        "_id": "65d4f20f8f5a4d7e9a123456",
        "type": "county",
        "matchName": "ga-fulton",
        "displayName": "string",
        "createdAt": "2019-08-24T14:15:22Z",
        "updatedAt": "2019-08-24T14:15:22Z",
        "name": "string",
        "fipsCode": "string",
        "number": 0,
        "letter": "string",
        "parentId": "65d4f20f8f5a4d7e9a123456",
        "parent": "string",
        "parentsFlat": [
          "65d4f20f8f5a4d7e9a123456"
        ],
        "population": 0,
        "populationType": "definitive",
        "votingType": "voting-district",
        "intersectingCities": [
          "65d4f20f8f5a4d7e9a123456"
        ],
        "intersectingCounties": [
          "65d4f20f8f5a4d7e9a123456"
        ],
        "state": "65d4f20f8f5a4d7e9a123456",
        "translationAvailable": true,
        "longName": "State House District 77",
        "shortName": "District 77"
      },
      "parentDistrict": "65d4f20f8f5a4d7e9a123456",
      "districtType": "county",
      "cities": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "counties": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "additionalDistricts": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "excludedDistricts": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "originalDistrict": "65d4f20f8f5a4d7e9a123456",
      "party": "string",
      "positionData": {
        "special": false,
        "seatIdentifier": "string",
        "seatIdentifierType": "post"
      },
      "runoffPrecedent": "65d4f20f8f5a4d7e9a123456",
      "primaryPrecedent": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "runoffRace": "65d4f20f8f5a4d7e9a123456",
      "generalRace": "65d4f20f8f5a4d7e9a123456",
      "ballotOrder": 3000,
      "maxChoices": 1,
      "rankedChoice": {
        "enabled": false,
        "maxChoices": 1
      },
      "retention": false,
      "uncontested": false,
      "uncontestedDetailed": "under-contested",
      "longName": "string",
      "officeName": "string",
      "descriptionShort": "string",
      "detailShort": "string",
      "detailLong": "string",
      "readMoreLink": "string",
      "candidateSummary": {
        "numCandidates": 0,
        "numCandidatesNotQualified": 0,
        "names": [
          "string"
        ],
        "keys": [
          "string"
        ],
        "ids": [
          "65d4f20f8f5a4d7e9a123456"
        ],
        "photos": [
          "string"
        ],
        "parties": [
          "string"
        ]
      },
      "candidates": [
        {
          "_id": "65d4f20f8f5a4d7e9a123456",
          "photo": "string",
          "photoPathFace": "string",
          "name": "string",
          "party": "string",
          "official": "string"
        }
      ],
      "questionnaire": {},
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ]
}

Get questionnaire by ID

Returns a single questionnaire by id. Authentication is optional for this read; if provided, the token is validated and may affect fields visible to the caller.

Get race by ID

Returns a single race by id. Core race reads require an organization overlay context supplied by `overlayOrganizationId` or the `X-Organization-Id` header.