API Search Service

Today, we are thrilled to announce the release of our highly anticipated Search Service as part of the GovInfo API. The Search Service enables searching of GovInfo content and metadata using the same search terms as on the website, allowing for complex queries to target specific documents. This opens up a new world of possibilities for developers using the GovInfo API.

Request

To issue a request to the service, issue a POST request to https://api.govinfo.gov/search with a request body that looks like:

    {
        "query":"federal API",
        "pageSize":"2",
        "offsetMark":"*",
        "sorts":[
            {
                "field":"score",
                "sortOrder":"DESC"
            }
        ]
    }

Using our interactive documentation, simply copy the above into the request body field and click the execute button. If you need an API key, sign up for one here. To try the API before creating a key, use DEMO_KEY by clicking on the Authorize button at the top of the documentation page, adding it, and clicking Authorize.

This request is functionally equivalent to this search.

Request Parameters

Here is an explanation of the request parameters.

• query: Add search terms here; can include field operators like collection, congress, lastModified , and others, appropriate to collections. For more information on available search operators, see our Search Operators page and individual collection help pages.
• pageSize: The number of records to return per page. Maximum is 1000
• offsetMark: The starting record requested. For the first request, use * ; subsequent requests should use the value from the offsetMark key in the response.
• sorts: Set the preferred sorting method, specifying fields and sortOrder. This can have multiple values, allowing for customized sorting. For the initial release, the recommended sorts are:
• score - equivalent to "Relevancy" in the user interface. This returns documents in the order where more relevant documents are returned first. Note: Sorting by score ascending is not supported.
• publishdate, sortOrder:"DESC" - equivalent to "Date New to Old" in the user interface. This returns documents with newer dateIssued values first.
• publishdate, sortOrder:"ASC" - equivalent to "Date Old to New" in the user interface. This returns documents with older dateIssued values first.
• title, sortOrder:"ASC" - equivalent to "Alphabetical (A-Z)" in the user interface. This returns documents with titles alphabetically.
• title, sortOrder:"DESC" - equivalent to "Alphabetical (Z-A)" in the user interface. This returns documents with titles reverse alphabetically.
• lastModified, sortOrder:"DESC" - returns documents based on the last added/modified time in GovInfo, with most recent documents returning first. Note: If not already specified, LastModified DESC is automatically set as a secondary sort to ensure that results are returned in a consistent order.
• lastModified, sortOrder:"ASC" - returns documents based on the last added/modified time in GovInfo, with most recent documents returning last.

The following parameters are optional:

• resultLevel: Determine whether the results should return results at the package-level ("package") or a mix of granules and packages ("default"). If not specified, the default will be used.
• historical: Determine whether to return documents that are not current (e.g. older editions of the CFR). If not specified as true , the default false will be used.

Tips

Here are some quick tips that may be of use with the Search Service.

• if using quotes in your query, escape them with \
• use a range search with lastModified to limit your results to only results that have been added or updated since your last request. e.g. lastModified:range(2023-08-15T12:00:05Z,)
• Complex mods queries are available by using the mods: operator and including a mods field name, e.g. mods:field:(@name:\"Geographic Scope\":\"Atlantic\")

Additional examples of Search Service requests are available on our API repository on GitHub.

Response

After a successful request, the Search Service will return a set of results formatted in json, with a set of fields intended to provide a good baseline of metadata and links for further exploration, including direct links to content and metadata.

For the sample request above, here is an example response.

        {
            "results": [
                {
                    "title": "Adjustments to the API.",
                    "packageId": "CFR-2022-title47-vol3",
                    "granuleId": "CFR-2022-title47-vol3-sec61-46",
                    "lastModified": "2023-07-27T16:18:39Z",
                    "governmentAuthor": [
                        "National Archives and Records Administration",
                        "Office of the Federal Register"
                    ],
                    "dateIssued": "2022-10-01",
                    "collectionCode": "CFR",
                    "resultLink": "https://api.govinfo.gov/packages/CFR-2022-title47-vol3/granules/CFR-2022-title47-vol3-sec61-46/summary",
                    "dateIngested": "2023-07-27",
                    "download": {
                        "premisLink": "https://api.govinfo.gov/packages/CFR-2022-title47-vol3/premis",
                        "xmlLink": "https://api.govinfo.gov/packages/CFR-2022-title47-vol3/granules/CFR-2022-title47-vol3-sec61-46/xml",
                        "zipLink": "https://api.govinfo.gov/packages/CFR-2022-title47-vol3/zip",
                        "modsLink": "https://api.govinfo.gov/packages/CFR-2022-title47-vol3/granules/CFR-2022-title47-vol3-sec61-46/mods",
                        "pdfLink": "https://api.govinfo.gov/packages/CFR-2022-title47-vol3/granules/CFR-2022-title47-vol3-sec61-46/pdf"
                    }
                },
                {
                    "title": "Exceptions to the definition of an API.",
                    "packageId": "CFR-2022-title26-vol13",
                    "granuleId": "CFR-2022-title26-vol13-sec1-1061-3",
                    "lastModified": "2023-03-07T23:32:43Z",
                    "governmentAuthor": [
                        "National Archives and Records Administration",
                        "Office of the Federal Register"
                    ],
                    "dateIssued": "2022-04-01",
                    "collectionCode": "CFR",
                    "resultLink": "https://api.govinfo.gov/packages/CFR-2022-title26-vol13/granules/CFR-2022-title26-vol13-sec1-1061-3/summary",
                    "dateIngested": "2023-03-07",
                    "download": {
                        "premisLink": "https://api.govinfo.gov/packages/CFR-2022-title26-vol13/premis",
                        "xmlLink": "https://api.govinfo.gov/packages/CFR-2022-title26-vol13/granules/CFR-2022-title26-vol13-sec1-1061-3/xml",
                        "zipLink": "https://api.govinfo.gov/packages/CFR-2022-title26-vol13/zip",
                        "modsLink": "https://api.govinfo.gov/packages/CFR-2022-title26-vol13/granules/CFR-2022-title26-vol13-sec1-1061-3/mods",
                        "pdfLink": "https://api.govinfo.gov/packages/CFR-2022-title26-vol13/granules/CFR-2022-title26-vol13-sec1-1061-3/pdf"
                    }
                }
            ],
            "offsetMark": "AoIIQtxvuD8aQ0ZSLTIwMjItdGl0bGUyNi12b2wxMy1DRlItMjAyMi10aXRsZTI2LXZvbDEzLXNlYzEtMTA2MS0z",
            "count": 15668
        }

Give us your Feedback

We are excited to hear your thoughts on the new Search Service!

To provide feedback, please create a new issue on the GovInfo API GitHub repository.

We will review user feedback and incorporate changes and enhancements to the Search Service in the future. Changes will be announced ahead of time via issues with an upcoming label and an assigned milestone . Once we have a sense that the main functionality is satisfactory to the majority of users, we will remove the Public Preview label and announce the Search Service as production-ready, meaning that further changes will be enhancements only and non-breaking.