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 * Only available to US officials at the national and state level *
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#
* Samples contain information about officials and districts as of January 2024
Officials - Basic Products:
US National - Basic sample files: Click
hereto download.US State - Basic sample files: Click
hereto download.US Local - Basic sample files: Click
hereto download.
Officials - Plus Products:
US National - Plus sample files: Click
hereto download.US State - Plus sample files: Click
hereto download.US Local - Plus sample files: Click
hereto download.
Districts Products:
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”). |
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 |
Social Media#