New govinfo API
Published: October 22, 2018
Jump to: Introduction | Definitions | Example: Federal Register | Example: Congressional Record | Wrapping Up
Highlights
- Try the govinfo API for easier access to documents and metadata from all three branches of the Federal Government.
- Use the API to request lists of new and updated govinfo content within several collections.
- Get machine-readable JSON summaries of packages or granules and direct access to content and metadata.
- 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 pleased to announce the availability of a govinfo Application Programming Interface (API), a set of programming instructions and standards for accessing web-based software applications, web tools, or data. See detailed API documentation or learn about other developer tools including bulk data, sitemaps, and a link service on the Developer Hub.
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).
This initial release of the govinfo API includes the following endpoints:
- Collections Service - Lists documents have been added or updated.
- Packages Service - Provides access to package level summary information, content files, and metadata.
Definitions
The terms package and granule are used as a generalized way to discuss the organization of the documents within govinfo.
A package is a set of files that contains contextual information necessary to understand information within a document, including the content in various file formats (e.g. PDF, HTM, XML) as well as the descriptive (MODS) and preservation (PREMIS) metadata about the content. A package could be a Congressional Bill or a title of the United States Code.
Many packages are divided into subsections of the overall document called granules. This could be a speech in the Congressional Record, a notice in the Federal Register, or a chapter in the Code of Federal Regulations.
Both packages and granules have unique IDs.
Packages are also parts of collections, which are sets of similar documents such as the Congressional Bills collection. For a full list of collections and more information about each, see the What's Available page.
Example: Federal Register
Download a Federal Register package as a zip file using the demo key: https://api.govinfo.gov/packages/FR-2018-08-03/zip?api_key=DEMO_KEY
This zip file is for an issue of the Federal Register, dated August 3, 2018, and contains the following files:
- Content (the actual text/object itself)
- HTM
- XML
- Metadata (information about the content)
- DIP - Technical information regarding the contents of the package, following the METS schema.
- MODS - Descriptive information about the issue of the Federal Register, such as number of pages, publish date, and publisher.
- PREMIS - Preservation information about the package; describes what actions have been performed (e.g. ingest, virus checks.) This also includes fixity information for preservation purposes.
Inside each content folder, you will see one file that shares the package ID, in this example, FR-2018-08-03.pdf. This is the package level file. There are also files that correspond to the granules within the Federal Register issue, such as notices, presidential documents, and proposed and final rules. The file names correspond to the granule ID, such as 2018-16515.
See how package and granule IDs are constructed and used in govinfo URLs on each collection's help page (e.g. Federal Register Sample URLs).
Example: Congressional Record
This example shows how to retrieve a list of recently added or updated issues of the Congressional Record and retrieve content and metadata at different levels.
Use this link to see issues of the Congressional Record that have been added or updated on govinfo since October 1st, 2018:
https://api.govinfo.gov/collections/CREC/2018-10-01T00:00:00Z?pageSize=10&offsetMark=*&api_key=DEMO_KEY
Use pageSize to specify the number of packages listed, and offsetMark=* to specify the starting record.
Snippet of results:
{
"count": 19,
"message": null,
"nextPage": "https://api.govinfo.gov/collections/CREC/2018-10-01T00:00:00Z?offsetMark=AoJwx830kIMDL0NSRUMtMjAyMi0wNC0yNQ%3D%3D&pageSize=10",
"previousPage": null,
"packages": [
{
"packageId": "CREC-2018-10-04",
"lastModified": "2018-10-11T19:35:58Z",
"packageLink": "https://api.govinfo.gov/packages/CREC-2018-10-04/summary"
},
{
"packageId": "CREC-2018-10-10",
"lastModified": "2018-10-11T19:40:21Z",
"packageLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/summary"
},
{
"packageId": "CREC-2018-06-27",
"lastModified": "2018-10-16T07:25:30Z",
"packageLink": "https://api.govinfo.gov/packages/CREC-2018-06-27/summary"
},
{
"packageId": "CREC-2018-10-12",
"lastModified": "2018-10-13T14:03:40Z",
"packageLink": "https://api.govinfo.gov/packages/CREC-2018-10-12/summary"
......
},
Use this link for the JSON package summary:
https://api.govinfo.gov/packages/CREC-2018-10-10/summary?api_key=DEMO_KEY
The resulting package summary is similar to what is displayed on the Details page for this package, but in a machine-readable format.
Snippet of results for CREC-2018-10-10:
{
"title": "Congressional Record Volume 164, Issue 168, (October 10, 2018)",
"collectionCode": "CREC",
"collectionName": "Congressional Record",
"category": "Proceedings of Congress and General Congressional Publications",
"dateIssued": "2018-10-10",
"detailsLink": "https://www.govinfo.gov/app/details/CREC-2018-10-10",
"granulesLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/granules?offset=0&pageSize=100",
"packageId": "CREC-2018-10-10",
"download": {
"pdfLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/pdf",
"pdfExtensionsLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/pdf/extensions",
"pdfSenateLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/pdf/senate",
"pdfDailyDigestLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/pdf/dailydigest",
"modsLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/mods",
"premisLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/premis",
"zipLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/zip"
},
"branch": "legislative",
"pages": "94",
"governmentAuthor1": "Congress",
"suDocClassNumber": "X 1.1/A:X/A.",
"documentType": "CREC",
"congress": "115",
"session": "2",
"volume": "164",
"issue": "168",
"bookCount": "1",
"publisher": "U.S. Government Publishing Office",
"otherIdentifier": {
"migrated-doc-id": "cr10oc18",
"ils-system-id": "000568013",
"stock-number": "752-002-00000-2"
},
"lastModified": "2018-10-11T19:40:21Z"
}
Use links in the summary to retrieve content and metadata files that represent the complete issue of the Congressional Record. In this example, PDFs that represent sections of the Record are also available.
"download": {
"pdfLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/pdf",
"pdfExtensionsLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/pdf/extensions",
"pdfSenateLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/pdf/senate",
"pdfDailyDigestLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/pdf/dailydigest",
"modsLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/mods",
"premisLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/premis",
"zipLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/zip"
},
If the package has granules, get a list by using granulesLink:
https://api.govinfo.gov/packages/CREC-2018-10-10/granules?offset=0&pageSize=100&api_key=DEMO_KEY
Snippet of results:
{
"count": 53,
"offset": 0,
"pageSize": 100,
"nextPage": null,
"previousPage": null,
"granules": [
{
"title": "Daily Digest/Highlights + Senate",
"granuleId": "CREC-2018-10-10-pt1-PgD1124",
"granuleLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/granules/CREC-2018-10-10-pt1-PgD1124/summary"
},
{
"title": "Daily Digest/Senate Committee Meetings",
"granuleId": "CREC-2018-10-10-pt1-PgD1125",
"granuleLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/granules/CREC-2018-10-10-pt1-PgD1125/summary"
},
{
"title": "Daily Digest/House of Representatives",
"granuleId": "CREC-2018-10-10-pt1-PgD1126",
"granuleLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/granules/CREC-2018-10-10-pt1-PgD1126/summary"
},
{
"title": "Daily Digest/House Committee Meetings",
"granuleId": "CREC-2018-10-10-pt1-PgD1126-2",
"granuleLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/granules/CREC-2018-10-10-pt1-PgD1126-2/summary"
},
....
}
View summaries from the list of granules. For example, use this link to view the summary for a granule:
https://api.govinfo.gov/packages/CREC-2018-10-10/granules/CREC-2018-10-10-pt1-PgD1124/summary?api_key=DEMO_KEY
Snippet of results:
{
"title": "Daily Digest/Highlights + Senate",
"collectionCode": "CREC",
"collectionName": "Congressional Record",
"category": "Proceedings of Congress and General Congressional Publications",
"dateIssued": "2018-10-10",
"detailsLink": "https://www.govinfo.gov/app/details/CREC-2018-10-10/CREC-2018-10-10-pt1-PgD1124",
"granulesLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/granules?offset=0&pageSize=100",
"packageId": "CREC-2018-10-10",
"packageLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/summary",
"granuleId": "CREC-2018-10-10-pt1-PgD1124",
"download": {
"txtLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/granules/CREC-2018-10-10-pt1-PgD1124/htm",
"pdfLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/granules/CREC-2018-10-10-pt1-PgD1124/pdf",
"modsLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/granules/CREC-2018-10-10-pt1-PgD1124/mods",
"premisLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/premis",
"zipLink": "https://api.govinfo.gov/packages/CREC-2018-10-10/zip"
},
"bookNumber": "1",
"granuleClass": "DAILYDIGEST",
"subGranuleClass": "DDSCHAMBER",
"granuleDate": "2018-10-10",
"pagePrefix": "D",
"lastModified": "2018-10-11T19:40:21Z"
}
Full metadata for any granule is available in the MODS. Use this link to retrieve the MODS for this Congressional Record granule:
https://api.govinfo.gov/packages/CREC-2018-10-10/granules/CREC-2018-10-10-pt1-PgD1124/mods?api_key=DEMO_KEY
Use this link to retrieve an individual HTML file:
https://api.govinfo.gov/packages/CREC-2018-10-10/granules/CREC-2018-10-10-pt1-PgD1124/htm?api_key=DEMO_KEY
Request HTML files for each granule directly from the list of IDs in the granulesLink request, using the following pattern:
https://api.govinfo.gov/packages/{{packageId}}/granules/{{granuleId}}/htm?api_key={{api_key}}
Wrapping Up
Please send us feedback on our initial API implementation via GPO's GitHub Account
We also welcome input on our next planned API features, including a search service and improved access to our bulk data content via the API.