Skip to main navigation / Skip to secondary navigation / Skip to content

Bill Positions API: Documentation

This document describes the methods in MAPLight.org's Bill Positions API.

The API has five methods:

  • Organization Search: returns an array of organization IDs that match a particular string.
  • Organization Positions: returns an array of an organization’s position on bills.
  • Bill Search: returns an array of bills that match a particular string.
  • Bill Positions: returns an array of organizations’ positions on a single bill.
  • Bill List: returns an array of organizations' positions on all bills in a session.

 

Your API Key

You can test the API without a key. Register for an account to get an API key.

 

Organization Search

The map.organization_search_v1 method returns an array of organization IDs that match a particular string.

Interfaces

  • Web form for learning the API
  • JSON responses
    • http://maplight.org/services_open_api/map.organization_search_v1.json
  • XML responses
    • http://maplight.org/services_open_api/map.organization_search_v1.xml

Parameters

  • search
    • Required.
    • String to be searched, i.e., the full name or partial name of an organization that takes a position on legislation.
  • exact
    • Optional. If omitted, system defaults to 0.
    • 1|0
      • 1 performs an exact string match on the entire contents of the field that contains names of organizations. This string match is not case sensitive.
      • 0 performs an partial string match within the field that contains names of organizations.
  • apikey
    • Required.
    • The value of your personal API key, a 32-character string.

Response Elements

  • organizations
    • organization_id: MAPLight.org’s internal identifier for organizations; to be used as input in the map.organization_positions method.
    • name: Name of an organization.

Examples

http://maplight.org/services_open_api/map.organization_search_v1.json?apikey=example&search=watch

http://maplight.org/services_open_api/map.organization_search_v1.xml?apikey=example&search=national+association+of+realtors&exact=1

 

Organization Positions

The map.organization_positions_v1 method returns an array an organization’s position on bills.

Interfaces

  • Web form for learning the API
  • JSON responses
    • http://maplight.org/services_open_api/map.organization_positions_v1.json
  • XML responses
    • http://maplight.org/services_open_api/map.organization_positions_v1.xml

Parameters

  • organization_id
    • Required
    • MAPLight.org’s internal identifier for organizations; output from the map.organization_search method.
  • apikey
    • Required
    • The value of your personal API key, a 32-character string.
  • jurisdiction
    • Required.
    • us refers to the United States Congress, ca refers to California

Response Elements

  • positions
    • url: Page for the bill on MAPLight.org web site.
    • disposition: Stance that the organization took on the bill. There are two meaningful values.
      • support: This organization did want this bill to become law.
      • oppose: This organization did not want this bill to become law.
    • jurisdiction: Which legislative body.
      • US: U.S. Congress
      • CA: California
    • session: The legislative session for this bill. Values include:
      • 109: The 109th session of the United States Congress (2005-2006).
      • 110: The 110th session of the United States Congress (2007-2008).
      • 111: The 111th session of the United States Congress (2009-2010).
      • 112: The 112th session of the United States Congress (2011-2012).
      • 2009: The 2009-2010 session of the California Assembly.
      • 2011: The 2011-2012 session of the California Assembly.
    • prefix: Codes for the type of bill, which precedes the bill number, such as:
      • Values for U.S. Congress are the same values as GovTrack.us:
        • h: House Bill (i.e. H.R.)
        • hr: House Resolution (i.e. H.Res.)
        • hj: House Joint Resolution (i.e. H.J.Res.)
        • hc: House Concurrent Resolution (i.e. H.Con.Res.)
        • s: Senate Bill (i.e. S.)
        • sr: Senate Resolution (i.e. S.Res.)
        • sj: Senate Joint Resolution (i.e. S.J.Res.)
        • sc: Senate Concurrent Resolution (i.e. S.Con.Res.)
    • number: The number of the bill, without the prefix, such as:
      • 933
      • 1851
    • measure: Concatenation of prefix, number and session in human-readable form, such as:
      • H.R. 1851 (110th)
    • topic: Usually the brief name of the bill, such as:
      • Junk Fax Prevention Act of 2005
      • FHA Modernization Act of 2007
    • citation: Citation of the publication that MAPLight.org used to determine this organization’s disposition of a bill. Expressed as HTML, such as:
    • catcode: Category code of the organization. MAPLight.org researchers assign a code to the majority of organizations that take a position using the Center for Responsive Politics' taxonomy. Using this field, it is possible to link bill positions to contributions data from OpenSecrets.org. Example values:
      • F2700: Hedge Funds
      • E1110: Major (multinational) oil & gas producers
    • last_update: Timestamp of when MAPLight.org last edited the citation of the organization's position. All times are UTC.
      • 2009-04-13T19:38:45Z
      • 2009-05-08T18:34:40Z

    Examples

    http://maplight.org/services_open_api/map.organization_positions_v1.json?apikey=example&jurisdiction=us&organization_id=22135

    http://maplight.org/services_open_api/map.organization_positions_v1.xml?apikey=example&jurisdiction=us&organization_id=23222

     

    Bill Search

    The map.bill_search_v1 method returns an array of bills that match a particular string.

    Interfaces

    • Web form for learning the API
    • JSON responses
      • http://maplight.org/services_open_api/map.bill_search_v1.json
    • XML responses
      • http://maplight.org/services_open_api/map.bill_search_v1.xml

    Parameters

    • search
      • Required.
      • String to be searched, i.e., the full name or partial name of a bill.
    • jurisdiction
      • Required.
      • us refers to the United States Congress, ca refers to California
    • apikey
      • Required
      • The value of your personal API key, a 32-character string.

    Response Elements

    • bills
      • url: Page for the bill on MAPLight.org web site.
      • jurisdiction: Which legislative body.
        • US: U.S. Congress
        • CA: California
      • session: The legislative session for this bill. Values include:
        • 109: The 109th session of the United States Congress (2005-2006).
        • 110: The 110th session of the United States Congress (2007-2008).
        • 111: The 111th session of the United States Congress (2009-2010).
        • 112: The 112th session of the United States Congress (2011-2012).
        • 2009: The 2009-2010 session of the California Assembly.
        • 2011: The 2011-2012 session of the California Assembly.
      • prefix: Codes for the type of bill, which precedes the bill number.
        • Values for U.S. Congress are the same values as GovTrack.us:
          • h: House Bill (i.e. H.R.)
          • hr: House Resolution (i.e. H.Res.)
          • hj: House Joint Resolution (i.e. H.J.Res.)
          • hc: House Concurrent Resolution (i.e. H.Con.Res.)
          • s: Senate Bill (i.e. S.)
          • sr: Senate Resolution (i.e. S.Res.)
          • sj: Senate Joint Resolution (i.e. S.J.Res.)
          • sc: Senate Concurrent Resolution (i.e. S.Con.Res.)
      • number: The number of the bill, without the prefix, such as:
        • 933
        • 1851
      • measure: Concatenation of prefix, number and session in human-readable form, such as:
        • H.R. 1851 (110th)
      • topic: Usually the brief name of the bill, such as:
        • Junk Fax Prevention Act of 2005
        • FHA Modernization Act of 2007

    Examples
    http://maplight.org/services_open_api/map.bill_search_v1.json?apikey=example&jurisdiction=us&search=water

    http://maplight.org/services_open_api/map.bill_search_v1.xml?apikey=example&jurisdiction=us&search=energy+efficiency

     

    Bill Positions

    The map.bill_positions_v1 method returns an array of organizations’ positions on a single bill.

    Interfaces

    • Web form for learning the API
    • JSON responses
      • http://maplight.org/services_open_api/map.bill_positions_v1.json
    • XML responses
      • http://maplight.org/services_open_api/map.bill_positions_v1.xml

    Parameters

    • jurisdiction
      • Required.
      • us refers to the United States Congress, ca refers to California.
    • session: The legislative session for this bill. Values include:
      • 109: The 109th session of the United States Congress (2005-2006).
      • 110: The 110th session of the United States Congress (2007-2008).
      • 111: The 111th session of the United States Congress (2009-2010).
      • 112: The 112th session of the United States Congress (2011-2012).
      • 2009: The 2009-2010 session of the California Assembly.
      • 2011: The 2011-2012 session of the California Assembly.
    • prefix: Codes for the type of bill, which precedes the bill number.
      • Values for U.S. Congress are the same values as GovTrack.us:
        • h: House Bill (i.e. H.R.)
        • hr: House Resolution (i.e. H.Res.)
        • hj: House Joint Resolution (i.e. H.J.Res.)
        • hc: House Concurrent Resolution (i.e. H.Con.Res.)
        • s: Senate Bill (i.e. S.)
        • sr: Senate Resolution (i.e. S.Res.)
        • sj: Senate Joint Resolution (i.e. S.J.Res.)
        • sc: Senate Concurrent Resolution (i.e. S.Con.Res.)
    • number: The number of the bill, without the prefix, such as:
      • 933
      • 1851
    • apikey
      • Required
      • The value of your personal API key, a 32-character string.

    Response Elements

    • bill
      • url: Page for the bill on MAPLight.org web site.
      • last_update: Timestamp of when MAPLight.org last updated information about positions taken on this bill.
        • 2009-04-13T19:38:45Z
        • 2009-05-08T18:34:40Z
      • organizations
        • organization_id: MAPLight.org’s internal identifier for organizations; to be used as input in the map.organization_positions method.
        • name: Name of an organization.
        • disposition: Stance that the organization took on the bill. There are two meaningful values.
          • support: This organization did want this bill to become law.
          • oppose: This organization did not want this bill to become law.
        • citation: Citation of the publication that MAPLight.org used to determine this organization’s disposition of a bill. Expressed as HTML, such as:
        • catcode: Category code of the organization. MAPLight.org researchers assign a code to the majority of organizations that take a position using the Center for Responsive Politics' taxonomy. Using this field, it is possible to link bill positions to contributions data from OpenSecrets.org. Example values:
          • F2700: Hedge Funds
          • E1110: Major (multinational) oil & gas producers

    Examples

    http://maplight.org/services_open_api/map.bill_positions_v1.json?apikey=example&jurisdiction=us&session=111&prefix=h&number=1

     

    Bill List

    The map.bill_list method returns an array of organizations’ positions on all bills in a session. This response is cached and updated nightly.

    Interfaces

    • Web form for learning the API. This interface only returns the first ten bills.
    • JSON responses
      • http://maplight.org/services_open_api/map.bill_list_v1.json
    • XML responses
      • http://maplight.org/services_open_api/map.bill_list_v1.xml

    Parameters

    • jurisdiction
      • Required.
      • us refers to the United States Congress, ca refers to California.
    • session: The legislative session for this bill. Values include:
      • 109: The 109th session of the United States Congress (2005-2006).
      • 110: The 110th session of the United States Congress (2007-2008).
      • 111: The 111th session of the United States Congress (2009-2010).
      • 112: The 112th session of the United States Congress (2011-2012).
      • 2009: The 2009-2010 session of the California Assembly.
      • 2011: The 2011-2012 session of the California Assembly.
    • include_organizations
      • Optional.
      • Indicates whether the response includes an array of each organization's position on the bill.
      • 0|1
        • 0: The response indicates whether any organizations have taken a position on the bill.
        • 1: The responses includes an array of each organization's position on the bill, including the same elements as the response for the Bill Positions method.
    • has_organizations
      • Optional.
      • Indicates whether the response includes bill for which no organization has taken a position.
      • 0|1
        • 0: Includes all bills.
        • 1: Excludes bills for which no organization has taken a position. This is the default.
    • apikey
      • Required
      • The value of your personal API key, a 32-character string.

    Response Elements

    • bills
      • url: Page for the bill on MAPLight.org web site.
      • jurisdiction: Which legislative body.
        • US: U.S. Congress
      • session: The legislative session for this bill. Values include:
        • 109: The 109th session of the United States Congress (2005-2006).
        • 110: The 110th session of the United States Congress (2007-2008).
        • 111: The 111th session of the United States Congress (2009-2010).
      • prefix: Codes for the type of bill, which precedes the bill number.
        • Values for U.S. Congress are the same values as GovTrack.us:
          • h: House Bill (i.e. H.R.)
          • hr: House Resolution (i.e. H.Res.)
          • hj: House Joint Resolution (i.e. H.J.Res.)
          • hc: House Concurrent Resolution (i.e. H.Con.Res.)
          • s: Senate Bill (i.e. S.)
          • sr: Senate Resolution (i.e. S.Res.)
          • sj: Senate Joint Resolution (i.e. S.J.Res.)
          • sc: Senate Concurrent Resolution (i.e. S.Con.Res.)
      • number: The number of the bill, without the prefix, such as:
        • 933
        • 1851
      • measure: Concatenation of prefix, number and session in human-readable form, such as:
        • H.R. 1851 (110th)
      • topic: Usually the brief name of the bill, such as:
        • Junk Fax Prevention Act of 2005
        • FHA Modernization Act of 2007
      • last_update: Timestamp of when MAPLight.org last updated information about positions taken on this bill.
        • 2009-04-13T19:38:45Z
        • 2009-05-08T18:34:40Z
      • If the request is include_organizations=0, the response includes a has_organizations element.
        • Indicates whether the response includes bill for which no organization has taken a position.
        • 0|1
          • 0: Indicates that no organization has taken a position on this bill.
          • 1: Indicates that at least one organization has taken a position on this bill.
      • If the request is include_organizations=1, the response includes organizations array, including the same fields as the organizations array in the Bill Positions response.

    Examples

    http://maplight.org/services_open_api/map.bill_list_v1.json?apikey=example&jurisdiction=us&session=111&include_organizations=0&has_organizations=0

    http://maplight.org/services_open_api/map.bill_list_v1.xml?apikey=example&jurisdiction=us&session=110&include_organizations=1&has_organizations=1