Data Layout#

Introduction#

License our data in bulk for maximum flexibility. We currently carry data for all levels of government in the United States: federal, state and local.

Our “Officials - Basic” package includes the following data tables in .CSV format:

  • Officials

  • Titles

  • Role and Level Enumeration

  • Official Committees

Our “Officials - Plus” package includes all of the tables in the basic package, plus the following data tables in .CSV format:

  • Officials Social Media Identifiers

  • Committees Social Media Identifiers

Our “Districts” package can be purchased independently of, or in addition to, our officials data. Spatial data is provided in WKT (Well-known text) format.

Sample Files#

  • Officials sample files: Click here to download.

  • Titles sample files: Click here to download.

  • Role and Level sample files: Click here to download.

  • Official Committees sample files: Click here to download.

  • Officials Social Media Identifiers sample files: Click here to download.

  • Committees Social Media Identifiers sample files: Click here to download.

  • District Boundaries sample files: Click here to download.

Samples contain information about officials and chambers as of January 2024

Layout and Definitions#

Officials Table#

Column Name

Type

Definition and Note

official_id

integer

Primary key

official_district_id

integer

Foreign key of the district (join field)

party

nvarchar (120)

Political party designation of the official

valid_from

datetimeoffset (7)

Start date of official’s current term in office

valid_from_precision

nvarchar (1)

Accuracy of valid from (day, month, year)

valid_to

datetimeoffset (7)

Official’s legislative role

valid_to_precision

nvarchar (1)

Accuracy of valid from (day, month, year)

first_name

nvarchar (40)

First name of the official

middle_initial

nvarchar (40)

Middle initial or middle name of the official

last_name

nvarchar (100)

Last name of the official

name_suffix

nvarchar (64)

Name suffix of the Official

preferred_name

nvarchar (32)

Commonly used name instead of official’s given first name

primary_address_1

nvarchar (120)

First line of official’s primary (capitol) address

primary_address_2

nvarchar (120)

Second line of official’s primary (capitol) address

primary_address_3

nvarchar (120)

Third line of official’s primary (capitol) address

primary_city

nvarchar (50)

City of official’s primary address

primary_state

nvarchar (40)

State of official’s primary address

primary_postal_code

nvarchar (60)

Postal code of official’s primary address

primary_phone_1

nvarchar (80)

Official’s primary phone number

primary_phone_2

nvarchar (150)

Official’s alternate phone at primary address

primary_fax_1

nvarchar (64)

Official’s primary fax number

primary_fax_2

nvarchar (32)

Official’s alternate fax at primary address

secondary_address_1

nvarchar (180)

First line of official’s secondary (district) address

secondary_address_2

nvarchar (180)

Second line of official’s secondary (district) address

secondary_address_3

nvarchar (180)

Third line of official’s secondary (district) address

secondary_city

nvarchar (50)

City of official’s secondary address

secondary_state

nvarchar (32)

State of official’s secondary address

secondary_postal_code

nvarchar (24)

Postal code of official’s secondary address

secondary_phone_1

nvarchar (40)

Official’s phone number at secondary address

secondary_phone_2

nvarchar (40)

Official’s alternate phone at secondary address

secondary_fax_1

nvarchar (32)

Official’s fax number at secondary address

secondary_fax_2

nvarchar (32)

Official’s alternate fax at secondary address

email_1

nvarchar (150)

Official’s primary (capitol) email address

email_2

nvarchar (150)

Official’s secondary email address

photo_origin_url

nvarchar (320)

URL of the official’s headshot

url_1

nvarchar (360)

URL of official’s primary website (usually the city, state or national website with information on the legislator)

url_2

nvarchar (600)

URL of official’s secondary website, where applicable - may be a website privately maintained by legislator, caucus or party, etc.

salutation

nvarchar (48)

Official’s salutation

web_form_url

nvarchar (400)

URL of the official’s web contact form

title

nvarchar (300)

Title the official was elected to serve, such as “Senator”

is_appointed

bit

Whether official is appointed rather than elected

biography

nvarchar (max)

Official’s biography, where available

date_of_birth

nvarchar (3000)

Official’s date of birth in format yyyy-mm-dd

last_update_date

datetimeoffset (7)

Date record last updated

chamber_name

nvarchar (160)

Name of the chamber

chamber_type

nvarchar (12)

Type of chamber (“UPPER” and “LOWER” indicate legislative chambers and their relative position within the same level of government; “EXECUTIVE” indicates an executive chamber)

district_id

nvarchar (80)

Official legislature district ID of the district (usually a number)

district_city

nvarchar (48)

Local municipality the districts represents, if applicable

district_state

nvarchar (3)

Subnational geography (such as a state or province) that the district represents, coded using ISO 3166-2 suffix, if applicable

district_country

nvarchar (2)

Country the district represents

district_type

nvarchar (20)

Geographic level that district represents in relation to chamber

sk

integer

Surrogate key for the official (an ID for an individual across time and different political offices)

ocd_id

nvarchar (160)

Open Civic Data division ID

Titles Table#

Column Name

Type

Definition and Note

official_id

integer

Primary key

last_name

nvarchar (100)

Last name of the official

chamber_name

nvarchar (160)

Name of the chamber

ocd_id

nvarchar (160)

Open Civic Data division ID

title

nvarchar (120)

A list of any titles that the official holds, typically a leadership position within the chamber (e.g. Majority Leader); titles in this table are different than the title field in the Officials table

Role and Level Enumeration Table#

Column Name

Type

Definition and Note

official_id

integer

Primary key

last_name

nvarchar (100)

Last name of the official

role

nvarchar (28)

Role enumeration of the official (see role types key below)

level

nvarchar (28)

Level enumeration of the district (see role types key below)

chamber_name

nvarchar (160)

Name of the chamber in which the official serves

ocd_id

nvarchar (160)

Open Civic Data Division ID

Role Types#

Value

Description

Example

headofGovernment

Highest ranking official in an executive branch of government

President, Governor, Mayor

deputyHeadofGovernment

An official who can be deputized as Head of Government if needed

Vice President, Lieutenant Governor

governmentOfficer

An official who holds elected or appointed office in an executive branch of government, but who is not a head or deputy head of government

Secretary of State, Public Service Commissioner

executiveCouncil

An official who is a member of a council in the executive branch of government

County Executive Council member

legislatorUpperBody

An official who serves in the upper body of a chamber in the legislative branch of government

Senator

legislatorLowerBody

An official who serves in the lower body of a chamber in the legislative branch of government

Representative, Delegate

Level Types#

Column Name

Description

Example

country

Country

United States

administrativeArea1

State

New York

administrativeArea2

County

Los Angeles County

locality

City/town

Seattle

Note: Roles and levels are an additional way the Cicero database classifies and organizes officials and districts. The Role property for each elected official classifies the type of authority the office possesses.

Likewise, the Level property classifies the type of geographic hierarchical level the district possesses. This is a 1-to-many relationship; officials and districts may simultaneously possess more than one role or level.

Officials Committees Table#

Column Name

Type

Definition and Note

official_id

integer

Foreign key of official who serves on the committee

last_name

nvarchar (100)

Last name of official

official_chamber_name

nvarchar (160)

Name of chamber in which the committee exists

position

nvarchar (50)

Official’s position within the committee, e.g. Chair (most members have no special position and this field will be blank)

level

nvarchar (10)

Level of government in which the chamber and committee exist (e.g. “National” or “State”)

committee_id

integer

Primary key of the committee

name

nvarchar (220)

Name of the committee (or subcommittee)

subcommittee_of

integer

If a subcommittee is being described, then this field will be populated with the committee_id of the parent committee

url_1

nvarchar (220)

URL of committee’s primary website (usually the official state/national website with information on the committee; it may be maintained by the majority party)

url_2

nvarchar (220)

URL of committee’s secondary website, if applicable (this may be a website maintained by the minority party)

committee_chamber_type

nvarchar (5)

Indicates whether the committee is associated with a chamber of chamber_type=LOWER (“House), or chamber_type=UPPER (“Senate”) or both (“Joint”).

Social Media#

Officials Social Media Identifiers Table#

Column Name

Type

Definition and Note

identifier_id

integer

Primary key

official_id

integer

Foreign key of the official

last_name

nvarchar (100)

Last name of the official

identifier_type

nvarchar (25)

Name of the Identifier source (see Identifier Types key below )

identifier_value

nvarchar (300)

Value of the Identifier

valid_from

datetimeoffset (7)

Start date of official’s current term in office

last_update_date

datetimeoffset (7)

Date official’s record was last updated

chamber_name

nvarchar (160)

Name of the chamber in which the official serves

Identifiers Types#

Name

Type

Definition

Congressional Biographical Directory *

BIOGUIDE

ID

Center for Responsive Politics *

CRP

ID

Facebook

FACEBOOK

Full URL; official’s personal Facebook profile

Facebook (Official)

FACEBOOK-OFFICIAL

Full URL; official’s in-office Facebook page

Facebook (Campaign)

FACEBOOK-CAMPAIGN

Full URL; official’s campaign Facebook page

Federal Election Commission *

FEC

ID

Flickr

FLICKR

ID

GovTrack *

GOVTRACK

ID

RSS Feed

RSS

Full URL

Twitter

TWITTER

ID (without @)

Project Vote Smart

VOTESMART

ID (only applies to US officials at national and state levels)

YouTube

YOUTUBE

ID

LinkedIn

LINKEDIN

Full URL

Instagram

INSTAGRAM

ID

Instagram (Campaign)

INSTAGRAM-CAMPAIGN

ID; official’s campaign Instagram page

* Indicates that identifier only applies to US officials at the national level

Committees Social Media Identifiers Table#

Column Name

Type

Definition and Note

identifier_id

integer

Primary key

committee_id

integer

Foreign key of the committee with which the identifier is linked

identifier_type

nvarchar (32)

Name of the Identifier source (see Identifier Types key below)

identifier_value

nvarchar (120)

Value of the Identifier

committee_name

nvarchar (220)

Name of the committee

Identifiers Types#

Name

Type

Definition

Facebook

FACEBOOK

Full URL

Flickr

FLICKR

ID

RSS Feed

RSS

Full URL

Twitter

TWITTER

ID (without @)

YouTube

YOUTUBE

ID

LinkedIn

LINKEDIN

Full URL

Instagram

INSTAGRAM

ID

District Boundaries#

Column Name

Type

Definition and Note

cicero_id

integer

Primary key (official_district_id in officials table)

district_id

integer

Official legislature ID of the district

district_type

nvarchar (10)

Indicates the level of government (“NATIONAL”, “STATE”, “LOCAL”) and district subtype for the district (see below for district_type key)

subtype

nvarchar (5)

Indicates a legislative chamber and its relative position (“UPPER”, “LOWER”) within the same level of government for the district (see below for subtype key)

city

nvarchar (64)

City of district

state

nvarchar (10)

State or province of district

country

nvarchar (2)

Country of district

label

nvarchar (100)

Descriptive text associated with a district_id

valid_from

datetimeoffset (7)

First possible date on which a district can be represented by an official (this date could be well after the date that a newly redrawn district is passed into law, and even after the date of the first election in a new district; often, the valid_from date corresponds with the inauguration date of officials)

valid_to

datetimeoffset (7)

Last possible date on which a district can be represented by an official

ocd_id

nvarchar (160)

Open Civic Data Division ID

wkt

nvarchar (max)

Spatial data in WKT (well know text) format.

District Types#

District Type

Description

1

National executive - country

2

National lower

3

State executive - state, province, territory

4

National upper

5

Local

6

Local executive - city or county

7

State upper

8

State lower

District Subtypes#

Subtype

Description

LOWER

Lower chamber districts (legislative)

UPPER

Upper chamber districts (legislative)

EXEC

Executive district or equivalent