Search.gov is a service of the General Services Administration, providing search engine capability to federal agencies for their public websites. To learn more about Search.gov and how to set up your site for search, please review the site launch guide.
This API exposes all relevant Search.gov results “modules” in a single JSON call, including the following:
- Web results
- Best bets
- Health topics
- Job openings
- Recent tweets
- Recent news
- Recent video news
- Federal Register documents
- Related searches
The endpoint is
You must use https. You can find your access key on the API Access Key page of the Search.gov Admin Center.
OpenAPI Specification File
You can view the full details of this API in the OpenAPI Specification file available here: Open API specification file for the Results API
Note about Web Results and Endpoints
The endpoint you use to retrieve web results through this API will depend on the method we used to index your content. If we don’t yet have your content indexed, you won’t see results in the API.
Sites indexed via sitemaps or crawling will use the
/i14y endpoint. Because most users are in this category, the example API calls below are to this endpoint. Sites indexed via RSS will use the top level
/ endpoint, please modify your calls accordingly.
Three parameters are required: (1)
access_key, and (3)
query. All others are optional.
- You can find your site handle on the Search.gov Admin Center Settings page.
- Your access key is unique to your site handle so they must be paired properly to return results. If you have more than one search site set up, make sure you’ve selected the right one to get the right handle/key combination.
SEARCH_TERM_ENTERED_IN_YOUR_SEARCH_BOXwith the query entered by the searchers using your website’s search box.
- Preformatted request strings with your unique values are provided in the Search.gov Admin Center > Your Site > Activate > Search Results API Instructions.
|affiliate (required)||Site handle
|access_key (required)||The key used to access the API
|query (required)||Search term
|enable_highlighting (optional)||Enables or disables the highlighting of keywords in the results. The default is ‘true’ so use ‘false’ to disable highlighting. The opening and closing highlighting characters are
|limit (optional)||Defines the number of results to return. The default is 20, but you can specify between 1 and 50 results.
|offset (optional)||Defines the number of results you want to skip from the first result. The offset is used for implementing pagination. The default is 0 and the maximum is 999.
|sort_by (optional)||Allowed variables are date and relevance. The default sort is relevance. Add
Each item returns a unique set of fields. Each array will only have contents if there are results in that search feature matching the query.
Before you begin: If you set up the Routed Query feature in the Search.gov Admin Center, you will need to set up some additional logic. If there’s a match between the query and the Routed Query, we’ll return only the
route_to URL. Otherwise we’ll return the full results set. See Routed Queries.
We return the query to you for use in the results page display.
Total number of results available.
Offset for the subsequent results.
Spelling correction for your search term.
Web results from our Search.gov indexes.
Values Description title Title of the document url URL of the document snippet Summary of the document publication_date Publication date of the document (not available on commercial results)
Text best bets, which appear only when the query matches the text of the best bet’s title, description, or keywords.
Values Description id ID of the best bet title Title of the best bet url URL of the best bet description Description of the best bet
Graphic best bets, which appear only when the query matches the text of the best bet’s title, description, or keywords.
Values Description id ID of the graphic best bet title Title of the graphic best bet title_url URL of the graphic best bet image_url URL of the graphic image image_alt_text Alternative text of the image links An array of links in the graphic best bet. Each link contains a title and a URL
Values Description title Title of the health topic url URL of the health topic snippet Snippet of the health topic related_topics An array of topics related to the health topic. Each topic contains a title and a URL related_sites An array of sites related to the the health topic. Each site contains a title and a URL
Values Description position_id ID of the job opening position_title Position title of the job opening position_uri URI of the job opening apply_uri An array which includes the URI of the application position_location_display Text of the position location position_location An array of locations of the job opening organization_name Organization name of the job opening department_name Name of the department with opening sub_agency Name of the department’s agency with opening job_category An array of job classification and code job_grade An array of job grade position_schedule An array of job schedule position_offering_type An array of job type qualification_summary Summary of the job’s required qualifications position_remuneration An array of salary information position_start_date Start date of the job opening position_end_date End date of the job opening publication_start_date Application start date application_close_date Application close date position_formatted_description Array of formatting options for job posting user_area Array for additional user-input information for the position url URL of the job opening locations An array of locations of the job opening minimum Minimum salary of the job opening maximum Maximum salary of the job opening rate_interval_code Rate interval code of the job opening org_codes Organization codes
Values Description text Text of the tweet url URL of the tweet name Name of the tweet author screen_name Screen name of the tweet author profile_image_url URL of the tweet author profile image created_at Date of creation
Federal Register documents
Values Description id The ID of the document as known to usasearch document_number Document number of the federal register document document_type Document type of the federal register document title Title of the federal register document url URL of the federal register document agency_names An array of agency names of the federal register document page_length Page length of the federal register document start_page Start page of the federal register document end_page End page of the federal register document publication_date Publication date of the federal register document comments_close_date Comments close date of the federal register document
An array of related search terms, which are based on recent, common searches on the your site. Users will need to render each of these into a link that would make a new API call with that query term as they query
Recent news from our Search.gov indexes. Only available with commercial results.
Values Description title Title of the recent news url URL of the recent news snippet Snippet of the recent news publication_date Publication date of the recent news source Source of the recent news
Recent video news from our Search.gov indexes. Only available with commercial results.
Values Description title Title of the recent video news url URL of the recent video news snippet Snippet of the recent video news publication_date Publication date of the recent video news source Source of the recent video news thumbnail_url Thumbnail URL of the recent video news
If you have Routed Queries set up in your Admin Center, then any matching query terms will change the API response.
For instance, if you set the query
example to route to
https://www.search.gov, then the expected response will be the following:
Please never hesitate to reach out! Email the Search.gov team.