API - Related Document Service
Published: April 30, 2021
Jump to: Introduction | Example: Available Relationships for a BILLS package | Example: U.S. Code Relationship | Wrapping Up
Highlights
- The govinfo API now provides easier access to related documents for BILLS and BILLSTATUS packages.
- For package in the BILLS or BILLSTATUS collections, users can see related bill versions, bill history, Presidential signing statements, the associated public or private law, Congressional reports, U.S. Code sections, and documents in the Statutes at Large
- Use an existing api.data.gov key, or request one for free.
- Send feedback and see planned enhancements.
Introduction
As part of GPO's continuing mission of Keeping America Informed, we aim to make it easier for developers and the public at large to access and work with the information available on govinfo. In support of this goal, GPO is continuing to enhance the govinfo Application Programming Interface (API), a set of programming instructions and standards for accessing web-based software applications, web tools, or data. As part of our March 2021 release, we have enhanced the API to show related documents across multiple collections, starting with Congressional Bills and Bill Status packages. This takes one of the key features of the govinfo website and makes it more easily accessible to users to access in a programmatic fashion. We hope that this will provide users with some new ways of consuming and reusing our content!
See the original API feature tour article for more information on the capabilities of the API, including basic walk throughs of the collections and packages endpoints.
API keys
An api.data.gov key is required to use the govinfo API. Use an existing key or request one for free. You will receive a 40 character string that provides unique identification and access to APIs from agencies participating in api.data.gov's service.
To use a key, pass the key as a URL query parameter when making web service requests. For example: https://api.govinfo.gov/packages/FR-2018-08-03/summary?api_key={YOUR_KEY_HERE}
The following examples use a demo key (?api_key=DEMO_KEY).
Example: Available Relationships for a BILLS package
To use the new /related endpoint, supply a packageId for a BILLS or BILLSTATUS package. The following example is for the 21st Century Cures Act (BILLS-114hr34enr).
The response includes a list of available relationships for the given BILLS package, which then can be explored further.
https://api.govinfo.gov/related/BILLS-114hr34enr?api_key=DEMO_KEY
Snippet of results:
{
"relatedId": "BILLS-114hr34enr",
"relationships": [
{
"relationship": "Bill versions",
"collection": "BILLS",
"relationshipLink": "https://api.govinfo.gov/related/BILLS-114hr34enr/BILLS"
},
{
"relationship": "Bill History",
"collection": "HOB",
"relationshipLink": "https://api.govinfo.gov/related/BILLS-114hr34enr/HOB"
},
{
"relationship": "Congressional Reports",
"collection": "CRPT",
"relationshipLink": "https://api.govinfo.gov/related/BILLS-114hr34enr/CRPT"
},
{
"relationship": "Presidential Signing Statements and Remarks",
"collection": "CPD",
"relationshipLink": "https://api.govinfo.gov/related/BILLS-114hr34enr/CPD"
},
{
"relationship": "Public and Private Laws",
"collection": "PLAW",
"relationshipLink": "https://api.govinfo.gov/related/BILLS-114hr34enr/PLAW"
},
{
"relationship": "U.S. Code",
"collection": "USCODE",
"relationshipLink": "https://api.govinfo.gov/related/BILLS-114hr34enr/USCODE"
}
]
}
For each relationships supplied in the response, following the relationship link will provide a set of results of package or granule IDs that can be explored further. Here is the related Presidential signing statement from the Compilation of Presidential Documents collection:
https://api.govinfo.gov/related/BILLS-114hr34enr/CPD?api_key=DEMO_KEY
{
"relatedId": "BILLS-114hr34enr",
"results": [
{
"dateIssued": "2016-12-13",
"title": "Remarks on Signing the 21st Century Cures Act",
"packageLink": "https://api.govinfo.gov/packages/DCPD-201600845/summary",
"packageId": "DCPD-201600845",
"lastModified": "2021-02-22T20:06:52Z"
}
]
}
Example: U.S. Code
This example shows how to explore the U.S. Code relationships for our example BILLS package. USCODE relationships in the API have a two-step process. The first response shows the related U.S. Code titles for the specified package:
https://api.govinfo.gov/related/BILLS-114hr34enr/USCODE?api_key=DEMO_KEY
Results:
{
"relatedId": "BILLS-114hr34enr",
"results": [
{
"effectiveDate": "2020-01-24",
"title": "COMMERCE AND TRADE",
"citation": "15 U.S.C.",
"granulesLink": "https://api.govinfo.gov/related/BILLS-114hr34enr/USCODE/USCODE-2019-title15",
"packageId": "USCODE-2019-title15",
"lastModified": "2021-04-09T14:52:32Z"
},
{
"effectiveDate": "2020-01-24",
"title": "CRIME CONTROL AND LAW ENFORCEMENT",
"citation": "34 U.S.C.",
"granulesLink": "https://api.govinfo.gov/related/BILLS-114hr34enr/USCODE/USCODE-2019-title34",
"packageId": "USCODE-2019-title34",
"lastModified": "2021-04-13T14:04:39Z"
},
{
"effectiveDate": "2020-01-24",
"title": "FOOD AND DRUGS",
"citation": "21 U.S.C.",
"granulesLink": "https://api.govinfo.gov/related/BILLS-114hr34enr/USCODE/USCODE-2019-title21",
"packageId": "USCODE-2019-title21",
"lastModified": "2021-04-13T02:39:55Z"
},
{
"effectiveDate": "2020-01-24",
"title": "INTERNAL REVENUE CODE",
"citation": "26 U.S.C.",
"granulesLink": "https://api.govinfo.gov/related/BILLS-114hr34enr/USCODE/USCODE-2019-title26",
"packageId": "USCODE-2019-title26",
"lastModified": "2021-04-13T07:27:07Z"
},
{
"effectiveDate": "2020-01-24",
"title": "LABOR",
"citation": "29 U.S.C.",
"granulesLink": "https://api.govinfo.gov/related/BILLS-114hr34enr/USCODE/USCODE-2019-title29",
"packageId": "USCODE-2019-title29",
"lastModified": "2021-04-13T10:05:01Z"
},
{
"effectiveDate": "2020-01-24",
"title": "THE PUBLIC HEALTH AND WELFARE",
"citation": "42 U.S.C.",
"granulesLink": "https://api.govinfo.gov/related/BILLS-114hr34enr/USCODE/USCODE-2019-title42",
"packageId": "USCODE-2019-title42",
"lastModified": "2021-04-15T17:16:28Z"
},
{
"effectiveDate": "2020-01-24",
"title": "VETERANS' BENEFITS",
"citation": "38 U.S.C.",
"granulesLink": "https://api.govinfo.gov/related/BILLS-114hr34enr/USCODE/USCODE-2019-title38",
"packageId": "USCODE-2019-title38",
"lastModified": "2021-04-13T16:42:40Z"
}
]
}
Following any of the granulesLinks in the response will return the sections of the U.S. Code that are affected by the Bill. The snippet below shows the set of granules from Title 42, covering Public Health and Welfare:
https://api.govinfo.gov/related/BILLS-114hr34enr/USCODE/USCODE-2019-title42?api_key=DEMO_KEY
{
"relatedId": "BILLS-114hr34enr",
"results": [
{
"packageId": "USCODE-2019-title42",
"granuleId": "USCODE-2019-title42-chap7-subchapXVIII-partB-sec1395w-3",
"citation": "42 U.S.C. 1395w-3",
"title": "Competitive acquisition of certain items and services",
"granuleLink": "https://api.govinfo.gov/packages/USCODE-2019-title42/granules/USCODE-2019-title42-chap7-subchapXVIII-partB-sec1395w-3/summary"
},
{
"packageId": "USCODE-2019-title42",
"granuleId": "USCODE-2019-title42-chap7-subchapXVIII-partB-sec1395w-4",
"citation": "42 U.S.C. 1395w-4",
"title": "Payment for physicians' services",
"granuleLink": "https://api.govinfo.gov/packages/USCODE-2019-title42/granules/USCODE-2019-title42-chap7-subchapXVIII-partB-sec1395w-4/summary"
},
{
"packageId": "USCODE-2019-title42",
"granuleId": "USCODE-2019-title42-chap6A-subchapIII-partB-sec284",
"citation": "42 U.S.C. 284",
"title": "Directors of national research institutes",
"granuleLink": "https://api.govinfo.gov/packages/USCODE-2019-title42/granules/USCODE-2019-title42-chap6A-subchapIII-partB-sec284/summary"
},
{
"packageId": "USCODE-2019-title42",
"granuleId": "USCODE-2019-title42-chap6A-subchapII-partR-sec280i-4",
"citation": "42 U.S.C. 280i-4",
"title": "Authorization of appropriations",
"granuleLink": "https://api.govinfo.gov/packages/USCODE-2019-title42/granules/USCODE-2019-title42-chap6A-subchapII-partR-sec280i-4/summary"
},
{
"packageId": "USCODE-2019-title42",
"granuleId": "USCODE-2019-title42-chap6A-subchapXVII-partB-subparti-sec300x",
"citation": "42 U.S.C. 300x",
"title": "Formula grants to States",
"granuleLink": "https://api.govinfo.gov/packages/USCODE-2019-title42/granules/USCODE-2019-title42-chap6A-subchapXVII-partB-subparti-sec300x/summary"
},
{
"packageId": "USCODE-2019-title42",
"granuleId": "USCODE-2019-title42-chap6A-subchapII-partQ-sec280h-6",
"citation": "42 U.S.C. 280h-6",
"title": "Infant and early childhood mental health promotion, intervention, and treatment",
"granuleLink": "https://api.govinfo.gov/packages/USCODE-2019-title42/granules/USCODE-2019-title42-chap6A-subchapII-partQ-sec280h-6/summary"
},
...
...
{
"packageId": "USCODE-2019-title42",
"granuleId": "USCODE-2019-title42-chap6A-subchapIII-partA-sec282a",
"citation": "",
"title": "Authorization of appropriations",
"granuleLink": "https://api.govinfo.gov/packages/USCODE-2019-title42/granules/USCODE-2019-title42-chap6A-subchapIII-partA-sec282a/summary"
}
]
}
Wrapping Up
We hope that this is an exciting and useful feature that will help users better understand how their Government works through seeing the relationships in the complex web of official Federal publications. Give it a try by going to the API docs page and signing up for a free key!
The govinfo team is continuing to add new functionality to the API with every release. In the future, we will continue to expand the number of relationships between different documents to match what is currently available via the Related Documents on content details pages. Next up is exposing relationships between different Federal Register documents by Regulatory Identification Number (RIN), and relationships between Federal Register documents and sections of the Code of Federal Regulations.
Please send us feedback on our API implementation via our API GitHub repository.
We also welcome input on our upcoming API features, including a search service and improved access to our bulk data content via the API.
Finally, to learn more about our other developer tools including bulk data, sitemaps, and link service, check out our Developer Hub.