Representatives

This collection includes information about political geography, as well as elected officials.

For a list of methods for this resource, see the end of this page.

Resource representations

A resource in this collection has three sections, described in detail below. The divisions section lists political geographic divisions, like a country, state, county, or legislative district. (Which divisions will be listed depends on the specific API request made.) The offices section lists political positions that are elected to represent the divisions in the first section. The officials section lists people presently serving in the offices listed.

{
  "divisions": {
    (key): {
      "name": string,
      "alsoKnownAs": [
        string
      ],
      "officeIndices": [
        unsigned integer
      ]
    }
  },
  "offices": [
    {
      "name": string,
      "divisionId": string,
      "levels": [
        string
      ],
      "roles": [
        string
      ],
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ],
      "officialIndices": [
        unsigned integer
      ]
    }
  ],
  "officials": [
    {
      "name": string,
      "address": [
        {
          "locationName": string,
          "line1": string,
          "line2": string,
          "line3": string,
          "city": string,
          "state": string,
          "zip": string
        }
      ],
      "party": string,
      "phones": [
        string
      ],
      "urls": [
        string
      ],
      "photoUrl": string,
      "emails": [
        string
      ],
      "channels": [
        {
          "type": string,
          "id": string
        }
      ]
    }
  ]
}

Political Geography

Property name	Value	Description
`divisions`	`object`	Political geographic divisions that contain the requested address.
`divisions.(key)`	`nested object`	The unique Open Civic Data identifier for this division.
`divisions.(key).alsoKnownAs[]`	`list`	Any other valid OCD IDs that refer to the same division. Because OCD IDs are meant to be human-readable and at least somewhat predictable, there are occasionally several identifiers for a single division. These identifiers are defined to be equivalent to one another, and one is always indicated as the primary identifier. The primary identifier will be returned in ocd_id above, and any other equivalent valid identifiers will be returned in this list. For example, if this division's OCD ID is ocd-division/country:us/district:dc, this will contain ocd-division/country:us/state:dc.
`divisions.(key).name`	`string`	The name of the division.
`divisions.(key).officeIndices[]`	`list`	List of indices in the `offices` array, one for each office elected from this division. Will only be present if `includeOffices` was true (or absent) in the request.

Elected Offices

Property name	Value	Description
`offices[]`	`list`	Elected offices referenced by the divisions listed above. Will only be present if includeOffices was true in the request.
`offices[].divisionId`	`string`	The OCD ID of the division with which this office is associated.
`offices[].levels[]`	`list`	The levels of government of which this office is part. There may be more than one in cases where a jurisdiction effectively acts at two different levels of government; for example, the mayor of the District of Columbia acts at "locality" level, but also effectively at both `administrativeArea2` and `administrativeArea1`. Valid values include: `international` -- International governments, such as the United Nations or European Union. `country` -- National-level governments, such as the US Federal Government. `administrativeArea1` -- Governments of the top-level administrative subdivision of a country, such as US states. `regional` -- Regional governments whose jurisdiction may cross standard administrative subdivisions; these are uncommon in the US but are common around large cities in other countries. `administrativeArea2` -- Governments of the second-level administrative subdivision of a country, such as US counties. `locality` -- City or municipal governments. `subLocality1` -- Governments of the top-level administrative subdivision of a city, such as Washington, DC's wards. `subLocality2` -- Governments of the second-level administrative subdivision of a city,such as Washington, DC's Advisory Neighborhood Councils. `special` -- Local districts that exist only for special-purpose governments, such as soil and water conservation districts.
`offices[].name`	`string`	The human-readable name of the office.
`offices[].officialIndices[]`	`list`	List of indices in the officials array of people who presently hold this office.
`offices[].roles[]`	`list`	The roles which this office fulfills. Roles are not meant to be exhaustive, or to exactly specify the entire set of responsibilities of a given office, but are meant to be rough categories that are useful for general selection from or sorting of a list of offices. Valid values include: `headOfState` -- The chief public representative of a government. The head of state of a country is usually called the President. `headOfGovernment` -- The chief executive officer of a government. In the US, this is the President; in other countries, it is often the Prime Minister. At lower levels this may be a governor or mayor. `deputyHeadOfGovernment` -- The officer responsible for assuming the head of government role in the event of the death or incapacity of the elected head of government. In the US, this is the Vice President. This office may have other duties as well. `governmentOfficer` -- An elected executive-branch officer. In US states, this may include roles such as attorney general, comptroller, secretary or state, or treasurer. `executiveCouncil` -- A member of an executive council that fulfills executive-branch roles as a group. Examples include Indiana county commissioners. `legislatorUpperBody` -- A member of the upper body of a bicameral legislature, or the only body of a unicameral legislature. `legislatorLowerBody` -- A member of the lower body of a bicameral legislature. `highestCourtJudge` -- A justice of the top court of a particular government, such as a state Supreme Court. `judge` -- A judge in any court that is not the top court of the government it serves. `schoolBoard` -- A member of a local school board. `specialPurposeOfficer` -- An officer that serves a single, defined purpose, such as a member of a soil-and-water conservation board or mosquito abatement officer.
`offices[].sources[]`	`list`	A list of sources for this office. If multiple sources are listed, the data has been aggregated from those sources.
`offices[].sources[].name`	`string`	The name of the data source.
`offices[].sources[].official`	`boolean`	Whether this data comes from an official government source.

Elected Officials

Property name	Value	Description
`officials[]`	`list`	Officials holding the offices listed above. Will only be present if includeOffices was true in the request.
`officials[].address[]`	`list`	Addresses at which to contact the official.
`officials[].address[].city`	`string`	The city or town for the address.
`officials[].address[].line1`	`string`	The street name and number of this address.
`officials[].address[].line2`	`string`	The second line the address, if needed.
`officials[].address[].line3`	`string`	The third line of the address, if needed.
`officials[].address[].locationName`	`string`	The name of the location.
`officials[].address[].state`	`string`	The US two letter state abbreviation of the address.
`officials[].address[].zip`	`string`	The US Postal Zip Code of the address.
`officials[].channels[]`	`list`	A list of known (social) media channels for this official.
`officials[].channels[].id`	`string`	The unique public identifier for the candidate's channel.
`officials[].channels[].type`	`string`	The type of channel. The following is a list of types of channels, but is not exhaustive. More channel types may be added at a later time. One of: YouTube, Facebook, Twitter
`officials[].emails[]`	`list`	The direct email addresses for the official.
`officials[].name`	`string`	The official's name.
`officials[].party`	`string`	The full name of the party the official belongs to.
`officials[].phones[]`	`list`	The official's public contact phone numbers.
`officials[].photoUrl`	`string`	A URL for a photo of the official.
`officials[].urls[]`	`list`	The official's public website URLs.

Methods

representativeInfoByAddress: Looks up political geography and representative information for a single address.
representativeInfoByDivision: Looks up representative information for a single geographic division.