# Find elected officials

Cicero tracks elected officials and makes their information available through the official resource. The default response ordering is by last_name, first_name.

Use location queries on this resource. You can also query for officials using the official's name.

Cost: 1 credit

Endpoint: GET /official

## Query parameters:

  - `format` (string)
    Specify the desired format of the response.
    Enum: "json", "xml"

  - `customer_id` (string, required)
    The License Key issued by Melissa.
    Example: "{REPLACE-WITH-YOUR-LICENSE-KEY}"

  - `lat` (string, required)
    Required. The latitude of the location.
    Example: "33.63756710910554"

  - `lon` (string, required)
    Required. The longitude of the location.
    Example: "-117.60695049134513"

  - `search_loc` (string)
    Required. One line address or a single search string.

  - `search_address` (string)
    Required. The street address of the location.

  - `search_neighborhood` (string)
    Required. The official neighborhood of the location (in countries with postal designations e.g., Mexico).

  - `search_city` (string)
    Required. The city of the location.

  - `search_state` (string)
    Required. The state of the location.

  - `search_postal` (string)
    Required. The postal code of the location.

  - `search_country` (string)
    Required. The country of the location (Use ISO 3166-1 alpha-2 code).

  - `last_name` (string)
    Required. The official's last name.

  - `first_name` (string)
    The official's first name.

  - `city` (string)
    The city of the location used as a filter.

  - `state` (string)
    The state of the location used as a filter.

  - `country` (string)
    The country of the location (Use ISO 3166-1 alpha-2 code) used as a filter.

  - `order` (string)
    The name of the resource field by which to order the results.

  - `sort` (string)
    Whether to sort the results in ascending or descending order.
    Enum: "asc", "desc"

  - `district_type` (string)
    The type of district.
    Example: "NATIONAL_LOWER"

  - `district_id` (string)
    The ID, number, or name of the official's district.

  - `valid_on` (string)
    The date the district is valid on. Date should be specified in a YYYY-MM-DD format.

  - `valid_on_or_after` (string)
    The date the district is valid on or after. Date should be specified in a YYYY-MM-DD format.

  - `valid_on_or_before` (string)
    The date the district is valid on or before. Date should be specified in a YYYY-MM-DD format.

  - `valid_range` (string)
    The dates during which the district is valid. Dates should be specified in a YYYY-MM-DD format and separated by a comma. Use ALL to return every district in all valid date ranges.

  - `max` (integer)
    The maximum number of objects to return.

  - `offset` (integer)
    Number of items to skip in the response, starting from the beginning of the list.

  - `key` (string)
    The License Key issued by Melissa.

## Response 200 fields (application/json):

  - `response` (object)

  - `response.errors` (array)
    If the request encountered an error or errors, details about the error(s) will be contained in this field.

  - `response.messages` (array)
    Contains the resources matching the request query, if any.

  - `response.results` (object)
    Contains additional information about the outcome of a request that is not an error and not part of a query result.

  - `response.results.officials` (array)

  - `response.results.officials.id` (number)
    The Cicero database ID for this official. Changes after each edit; for a persistent ID, see sk.

  - `response.results.officials.sk` (number)
    The surrogate key for an official. Remains the same for an individual through different districts, chambers, and discontinuous terms.

  - `response.results.officials.valid_from` (string)
    Date the official was inaugurated in this office. Changes with redistricting or election to a new office, but not when an incumbent starts a consecutive term.

  - `response.results.officials.valid_to` (string,null)
    Date the official's term in office expires. This date would be extended if the official wins re-election.

  - `response.results.officials.last_update_date` (string)
    Date the Cicero research team last made changes to this official's information.

  - `response.results.officials.salutation` (string)
    Official's formal salutation. Some assemblies use formal titles such as “Honorable”.

  - `response.results.officials.first_name` (string)
    First name of the official. Sometimes, an official will have a preferred_name that they are more commonly known by.

  - `response.results.officials.middle_initial` (string)
    Middle name or initial of the official.

  - `response.results.officials.last_name` (string)
    Last name of the official.

  - `response.results.officials.preferred_name` (string)
    A name commonly used instead of the official's given first name. This property has a value only if it differs from the first_name.

  - `response.results.officials.name_suffix` (string)
    Name suffix of the official (e.g., “Jr.”, “III”, “Ph.D.”).

  - `response.results.officials.office` (object)

  - `response.results.officials.office.district` (object)

  - `response.results.officials.office.district.id` (number)
    The Cicero database ID for this district. This field is persistent for a given District, but this does not imply that the remainder of the response payload will never change. For example, a correction to the district boundary will change the response payload but will not change the ID. On the other hand, a boundary change due to a legal event such as an annexation or redistricting will result in a new District with a new ID (and appropriate adjustments to the valid_to field, if necessary).

  - `response.results.officials.office.district.sk` (number)
    The surrogate key for the district. Provided for API uniformity. For this resource, the SK is equivalent to the ID.

  - `response.results.officials.office.district.valid_from` (string)
    The date the district was established. Usually, this is the date of the last redistricting.

  - `response.results.officials.office.district.valid_to` (string,null)
    The date when the district's boundaries are expected to be changed. Usually, this is the date of the next redistricting.

  - `response.results.officials.office.district.last_update_date` (string)
    Date the Cicero research team last made changes to this district's boundary information.

  - `response.results.officials.office.district.district_type` (string)
    The level of government the district represents. See the district_type metadata endpoint for a list of possibilities.

  - `response.results.officials.office.district.subtype` (string)
    An additional categorization within district_type.

  - `response.results.officials.office.district.country` (string)
    The country the district is within. Uses the ISO 2 country code.

  - `response.results.officials.office.district.state` (string)
    The state, province, or region the district is within.

  - `response.results.officials.office.district.city` (string)
    The city the district represents, if the district_type is LOCAL or LOCAL_EXEC.

  - `response.results.officials.office.district.district_id` (string)
    The identifying code for the district within its delegation or district type. For example, a legislative delegation's 5th district would probably have a district_id of '5'. Non-legislative districts might have an ID assigned by the managing agency (e.g., US Census Block Groups have a GEOID).

  - `response.results.officials.office.district.label` (string)
    Descriptive text associated with a district_id, such as the label for the district (e.g., “5th Ward”), or a full label for the district (e.g. “Sealaska Alaska Native Regional Corporation”).

  - `response.results.officials.office.district.num_officials` (number)
    The number of elected officials that hold offices representing this district.

  - `response.results.officials.office.district.ocd_id` (string,null)
    The Open Civic Data Identifier for the district. Provides a standardized way of specifying and describing a geographic political division.

  - `response.results.officials.office.district.data` (object)
    Deprecated.

  - `response.results.officials.office.representing_city` (string)
    The city that this office serves.

  - `response.results.officials.office.representing_state` (string)
    The state, province, or other region that this office serves.

  - `response.results.officials.office.representing_country` (object)

  - `response.results.officials.office.representing_country.status` (string)
    The parent organization (e.g., “UN Member State”) or state on which the given Country is dependent (e.g., “Oversea Department of France”).

  - `response.results.officials.office.representing_country.name_short` (string)
    Short, common name for the country in English.

  - `response.results.officials.office.representing_country.gmi_3` (string)
    Three-letter Global Mapping International (GMI) country/territory code for the country.

  - `response.results.officials.office.representing_country.name_short_iso` (string)
    Short name (in English) for the country specified in the ISO-3166 standard.

  - `response.results.officials.office.representing_country.name_short_local` (string)
    Short, common name for the country in the local language.

  - `response.results.officials.office.representing_country.id` (number)
    The Cicero database ID for the country. Changes after each edit; for a persistent ID, see sk.

  - `response.results.officials.office.representing_country.sk` (number)
    The surrogate key for the country.

  - `response.results.officials.office.representing_country.name_short_un` (string)
    United Nations short name for the country.

  - `response.results.officials.office.representing_country.fips` (string)
    Two-letter U.S. Federal Information Processing Standard No.

  - `response.results.officials.office.representing_country.last_update_date` (string)
    Date the Cicero research team last made changes to the country's information.

  - `response.results.officials.office.representing_country.iso_3` (string)
    Three-letter ISO 3166-1 alpha-3 standard code for the country.

  - `response.results.officials.office.representing_country.iso_2` (string)
    Two-letter ISO 3166-1 alpha-2 standard code for the country.

  - `response.results.officials.office.representing_country.iso_3_numeric` (number,null)
    Three-digit ISO 3166-1 numeric standard code for the country.

  - `response.results.officials.office.representing_country.name_long_local` (string)
    Long name for the country in the local language.

  - `response.results.officials.office.representing_country.name_long` (string)
    Long name for the country in English.

  - `response.results.officials.office.representing_country.valid_from` (string)
    Deprecated.

  - `response.results.officials.office.representing_country.valid_to` (string,null)
    Deprecated.

  - `response.results.officials.office.representing_country.version` (number)
    Deprecated.

  - `response.results.officials.office.title` (string)
    The role of this office. This is the position that a candidate for office is listed for on an election ballot.

  - `response.results.officials.office.chamber` (object)

  - `response.results.officials.office.chamber.official_count` (number,null)
    The number of officials serving in the chamber.

  - `response.results.officials.office.chamber.id` (number,null)
    The Cicero database ID for the chamber. Changes after each edit; not persistent.

  - `response.results.officials.office.chamber.term_length` (string)
    The length of time for each term that officials serve in the chamber.

  - `response.results.officials.office.chamber.term_limit` (string)
    The maximum number of terms officials within the chamber can serve.

  - `response.results.officials.office.chamber.inauguration_rules` (string)
    The process for inaugurating officials within the chamber.

  - `response.results.officials.office.chamber.name_native_language` (string)
    Name of the chamber in the government's official language.

  - `response.results.officials.office.chamber.contact_phone` (string)
    A general phone number for contacting the chamber.

  - `response.results.officials.office.chamber.name_formal` (string)
    English formal name of the chamber.

  - `response.results.officials.office.chamber.election_frequency` (string)
    The length of time between elections with candidates for the chamber on the ballot. Shorter than term_length in chambers with staggered elections.

  - `response.results.officials.office.chamber.government` (object)

  - `response.results.officials.office.chamber.government.name` (string)
    The formal name of the government.

  - `response.results.officials.office.chamber.government.type` (string)
    A category describing the level of government.

  - `response.results.officials.office.chamber.government.city` (string)
    The city that the government governs.

  - `response.results.officials.office.chamber.government.state` (string)
    The state, province, or region that the government governs.

  - `response.results.officials.office.chamber.government.country` (object)

  - `response.results.officials.office.chamber.government.notes` (string)
    Deprecated.

  - `response.results.officials.office.chamber.redistricting_rules` (string)
    The process of redistricting for the chamber.

  - `response.results.officials.office.chamber.vacancy_rules` (string)
    The process of how vacancies within the chamber are filled.

  - `response.results.officials.office.chamber.contact_email` (string)
    A general email address for contacting the chamber.

  - `response.results.officials.office.chamber.last_update_date` (string)
    Date the Cicero research team last made changes to this district's information.

  - `response.results.officials.office.chamber.remarks` (string)
    Notable quirks or facts related to the chamber.

  - `response.results.officials.office.chamber.name` (string)
    Informal name of the chamber in English.

  - `response.results.officials.office.chamber.url` (string)
    URL to the official webpage of the chamber.

  - `response.results.officials.office.chamber.type` (string)
    Governmental level of the chamber.

  - `response.results.officials.office.chamber.is_appointed` (boolean)
    Whether officials in this chamber are appointed rather than elected.

  - `response.results.officials.office.chamber.election_rules` (string)
    A description of when elections take place.

  - `response.results.officials.office.chamber.legislature_update_date` (string,null)
    Deprecated.

  - `response.results.officials.office.chamber.is_chamber_complete` (boolean)
    Deprecated.

  - `response.results.officials.office.chamber.has_geographic_representation` (boolean)
    Deprecated.

  - `response.results.officials.office.id` (number)
    Deprecated. Use id on the Official object.

  - `response.results.officials.office.sk` (number)
    Deprecated. Use sk on the Official object.

  - `response.results.officials.office.valid_from` (string)
    Deprecated. Use valid_from on the Official object.

  - `response.results.officials.office.valid_to` (string,null)
    Deprecated. Use valid_to on the Official object.

  - `response.results.officials.office.last_update_date` (string)
    Deprecated. Use last_update_date on the Official object.

  - `response.results.officials.office.election_rules` (string)
    Deprecated. Use election_rules on the Chamber object.

  - `response.results.officials.addresses` (array)
    A list of address objects with the official's contact information, such as mailing address, phone, and fax.

  - `response.results.officials.addresses.address_1` (string)
    The first line of the street address.

  - `response.results.officials.addresses.address_2` (string)
    The second line of the street address.

  - `response.results.officials.addresses.address_3` (string)
    The third line of the street address.

  - `response.results.officials.addresses.city` (string)
    The city of the address.

  - `response.results.officials.addresses.state` (string)
    The state, province, or other region of the address.

  - `response.results.officials.addresses.postal_code` (string)
    The postal code for the address.

  - `response.results.officials.addresses.phone_1` (string)
    The primary phone number for contacting the address.

  - `response.results.officials.addresses.fax_1` (string)
    The primary fax number for the address.

  - `response.results.officials.addresses.phone_2` (string)
    The secondary phone number for contacting the address.

  - `response.results.officials.addresses.fax_2` (string)
    The secondary fax number for the address.

  - `response.results.officials.addresses.county` (string)
    Deprecated.

  - `response.results.officials.email_addresses` (array)
    A list of the official's email addresses.

  - `response.results.officials.web_form_url` (string)
    A web form URL for contacting the official.

  - `response.results.officials.urls` (array)
    A list of the official's government web page URLs.

  - `response.results.officials.photo_origin_url` (string)
    A URL for a headshot photo of the official.

  - `response.results.officials.photo_cropping` (object,null)
    For photos that are zoomed out or off-center, an object of the form {x, y, width, height, origWidth, origHeight} specifying the location (from top left) and dimensions of a bounding box that defines a headshot within the official photo. If no bounding box is defined (e.g., if the original photo is a well-framed headshot), this field will be null.

  - `response.results.officials.notes` (array)
    A list of descriptive information about the official, including a biography and a birthdate.

  - `response.results.officials.committees` (array)
    A list of the committees of which the official is a member.

  - `response.results.officials.committees.name` (string)
    Name of the committee.

  - `response.results.officials.committees.urls` (array)
    A list of the committee's web page URLs.

  - `response.results.officials.committees.committee_identifiers` (array)
    A list of identifier objects with information like social media accounts.

  - `response.results.officials.committees.committee_identifiers.identifier_type` (string)
    The platform referred to by the identifier.

  - `response.results.officials.committees.committee_identifiers.id` (number)
    The Cicero database ID for this identifier.

  - `response.results.officials.committees.committee_identifiers.identifier_value` (string)
    The identifying value for the official on this type of platform. Could be either a profile ID or a full URL.

  - `response.results.officials.committees.position` (string)
    The official's position within the committee, e.g. “Chair”. For members with no special position this field will be blank.

  - `response.results.officials.party` (string)
    Political party designation of the official. Might be “Nonpartisan” in cases where the government specifically uses that term.

  - `response.results.officials.identifiers` (array)
    A list of identifier objects with information like social media accounts.

  - `response.results.officials.identifiers.official` (number)
    Deprecated. Use id on the Official object.

  - `response.results.officials.identifiers.sk` (number)
    Deprecated.

  - `response.results.officials.identifiers.last_update_date` (string)
    Deprecated.

  - `response.results.officials.titles` (array)
    A list of any titles that the official holds. Typically, these are determined at an early meeting of the chamber. Titles are different than and in addition to the role (e.g., President, Senator) that the official was elected to.

  - `response.results.officials.nickname` (string)
    Deprecated. Use preferred_name instead.

  - `response.results.officials.initial_term_start_date` (string,null)
    Deprecated. Use valid_from instead.

  - `response.results.officials.current_term_start_date` (string)
    Deprecated. Use valid_from instead.

  - `response.results.officials.term_end_date` (string,null)
    Deprecated. Use valid_to instead.

  - `response.results.count` (object)

  - `response.results.count.from` (integer)

  - `response.results.count.to` (integer)

  - `response.results.count.total` (integer)

## Response 400 fields (application/json):

  - `response` (object)

  - `response.errors` (array)
    If the request encountered an error or errors, details about the error(s) will be contained in this field.
    Example: ["A detailed message about the error."]

  - `response.messages` (array)
    Contains the resources matching the request query, if any.

  - `response.results` (object)
    Contains additional information about the outcome of a request that is not an error and not part of a query result.