openapi: 3.0.2
info:
  title: Open States API v3 bills people API
  description: '

    * [More documentation](https://docs.openstates.org/en/latest/api/v3/index.html)

    * [Register for an account](https://openstates.org/accounts/signup/)



    **We are currently working to restore experimental support for committees & events.**


    During this period please note that data is not yet available for all states

    and the exact format of the new endpoints may change slightly depending on user feedback.


    If you have any issues or questions use our

    [GitHub Issues](https://github.com/openstates/issues/issues) to give feedback.'
  version: 2021.11.12
tags:
- name: people
paths:
  /people:
    get:
      tags:
      - people
      summary: People Search
      description: 'Get list of people matching selected criteria.


        Must provide either **jurisdiction**, **name**, or one or more **id** parameters.'
      operationId: people_search_people_get
      parameters:
      - description: Filter by jurisdiction name or id.
        required: false
        schema:
          title: Jurisdiction
          type: string
          description: Filter by jurisdiction name or id.
        name: jurisdiction
        in: query
      - description: Filter by name, case-insensitive match.
        required: false
        schema:
          title: Name
          type: string
          description: Filter by name, case-insensitive match.
        name: name
        in: query
      - description: Filter by id, can be specified multiple times for multiple people.
        required: false
        schema:
          title: Id
          type: array
          items:
            type: string
          description: Filter by id, can be specified multiple times for multiple people.
          default: []
        name: id
        in: query
      - description: Filter by current role.
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/OrgClassification'
          description: Filter by current role.
        name: org_classification
        in: query
      - description: Filter by district name.
        required: false
        schema:
          title: District
          type: string
          description: Filter by district name.
        name: district
        in: query
      - description: Additional information to include in response.
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/PersonInclude'
          description: Additional information to include in response.
          default: []
        name: include
        in: query
      - required: false
        schema:
          title: Page
          type: integer
          default: 1
        name: page
        in: query
      - required: false
        schema:
          title: Per Page
          type: integer
          default: 10
        name: per_page
        in: query
      - required: false
        schema:
          title: Apikey
          type: string
        name: apikey
        in: query
      - required: false
        schema:
          title: X-Api-Key
          type: string
        name: x-api-key
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonList'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /people.geo:
    get:
      tags:
      - people
      summary: People Geo
      description: 'Get list of people currently representing a given location.


        **Note:** Currently limited to state legislators and US Congress.  Governors & mayors are not included.'
      operationId: people_geo_people_geo_get
      parameters:
      - description: Latitude of point.
        required: true
        schema:
          title: Lat
          type: number
          description: Latitude of point.
        name: lat
        in: query
      - description: Longitude of point.
        required: true
        schema:
          title: Lng
          type: number
          description: Longitude of point.
        name: lng
        in: query
      - description: Additional information to include in the response.
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/PersonInclude'
          description: Additional information to include in the response.
          default: []
        name: include
        in: query
      - required: false
        schema:
          title: Apikey
          type: string
        name: apikey
        in: query
      - required: false
        schema:
          title: X-Api-Key
          type: string
        name: x-api-key
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonList'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CurrentRole:
      title: CurrentRole
      required:
      - title
      - org_classification
      type: object
      properties:
        title:
          title: Title
          type: string
          example: Senator
        org_classification:
          allOf:
          - $ref: '#/components/schemas/OrgClassification'
          example: upper
        district:
          title: District
          anyOf:
          - type: string
          - type: integer
          default: ''
          example: 3
        division_id:
          title: Division Id
          type: string
          default: ''
          example: ocd-division/country:us/state:nc/sldu:3
    Office:
      title: Office
      required:
      - name
      type: object
      properties:
        name:
          title: Name
          type: string
          example: District Office
        fax:
          title: Fax
          type: string
          example: 919-555-1234
        voice:
          title: Voice
          type: string
          example: 919-555-0064
        address:
          title: Address
          type: string
          example: 212 Maple Lane; Raleigh NC; 27526
        classification:
          title: Classification
          type: string
          example: capitol
    AltIdentifier:
      title: AltIdentifier
      required:
      - identifier
      - scheme
      type: object
      properties:
        identifier:
          title: Identifier
          type: string
          example: NCL000123
        scheme:
          title: Scheme
          type: string
          example: legacy_openstates
    Link:
      title: Link
      required:
      - url
      type: object
      properties:
        url:
          title: Url
          type: string
          example: https://example.com/
        note:
          title: Note
          type: string
          example: homepage
    Person:
      title: Person
      required:
      - id
      - name
      - party
      - jurisdiction
      - given_name
      - family_name
      - image
      - email
      - gender
      - birth_date
      - death_date
      - extras
      - created_at
      - updated_at
      - openstates_url
      type: object
      properties:
        id:
          title: Id
          type: string
          example: ocd-person/adb58f21-f2fd-4830-85b6-f490b0867d14
        name:
          title: Name
          type: string
          example: Angela Augusta
        party:
          title: Party
          type: string
          example: Democratic
        current_role:
          $ref: '#/components/schemas/CurrentRole'
        jurisdiction:
          $ref: '#/components/schemas/CompactJurisdiction'
        given_name:
          title: Given Name
          type: string
          example: Angela
        family_name:
          title: Family Name
          type: string
          example: Augusta
        image:
          title: Image
          type: string
          example: https://example.com/ncimg/3.png
        email:
          title: Email
          type: string
          example: aperson@example.com
        gender:
          title: Gender
          type: string
          example: female
        birth_date:
          title: Birth Date
          type: string
          example: '1960-05-04'
        death_date:
          title: Death Date
          type: string
          example: '2019-04-10'
        extras:
          title: Extras
          type: object
          example:
            profession: Doctor
        created_at:
          title: Created At
          type: string
          format: date-time
        updated_at:
          title: Updated At
          type: string
          format: date-time
        openstates_url:
          title: Openstates Url
          type: string
          example: https://openstates.org/person/amos-l-quick-iii-28NRPPfJA6FGVl9RrjpKjl/
        other_identifiers:
          title: Other Identifiers
          type: array
          items:
            $ref: '#/components/schemas/AltIdentifier'
        other_names:
          title: Other Names
          type: array
          items:
            $ref: '#/components/schemas/AltName'
        links:
          title: Links
          type: array
          items:
            $ref: '#/components/schemas/Link'
        sources:
          title: Sources
          type: array
          items:
            $ref: '#/components/schemas/Link'
        offices:
          title: Offices
          type: array
          items:
            $ref: '#/components/schemas/Office'
    PaginationMeta:
      title: PaginationMeta
      required:
      - per_page
      - page
      - max_page
      - total_items
      type: object
      properties:
        per_page:
          title: Per Page
          type: integer
          example: 20
        page:
          title: Page
          type: integer
          example: 1
        max_page:
          title: Max Page
          type: integer
          example: 3
        total_items:
          title: Total Items
          type: integer
          example: 52
    ValidationError:
      title: ValidationError
      required:
      - loc
      - msg
      - type
      type: object
      properties:
        loc:
          title: Location
          type: array
          items:
            anyOf:
            - type: string
            - type: integer
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
    OrgClassification:
      title: OrgClassification
      enum:
      - legislature
      - executive
      - lower
      - upper
      - government
      type: string
      description: An enumeration.
    PersonList:
      title: PersonList
      required:
      - results
      - pagination
      type: object
      properties:
        results:
          title: Results
          type: array
          items:
            $ref: '#/components/schemas/Person'
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
    JurisdictionClassification:
      title: JurisdictionClassification
      enum:
      - state
      - municipality
      - country
      type: string
      description: An enumeration.
    CompactJurisdiction:
      title: CompactJurisdiction
      required:
      - id
      - name
      - classification
      type: object
      properties:
        id:
          title: Id
          type: string
          example: ocd-jurisdiction/country:us/state:nc/government
        name:
          title: Name
          type: string
          example: North Carolina
        classification:
          allOf:
          - $ref: '#/components/schemas/JurisdictionClassification'
          example: state
    AltName:
      title: AltName
      required:
      - name
      - note
      type: object
      properties:
        name:
          title: Name
          type: string
          example: Auggie
        note:
          title: Note
          type: string
          example: nickname
    PersonInclude:
      title: PersonInclude
      enum:
      - other_names
      - other_identifiers
      - links
      - sources
      - offices
      type: string
      description: An enumeration.
    HTTPValidationError:
      title: HTTPValidationError
      type: object
      properties:
        detail:
          title: Detail
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'