Overview

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

Getting Started

The endpoint is https://api.gsa.gov/technology/searchgov/v2/results/i14y.

You must use https. You can find your access key on the API Access Key page of the Search.gov Admin Center.

Back to top

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

Back to top

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.

We can index content using your XML sitemap (preferred) or RSS feeds. We can also deploy a crawler on a limited basis.

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.

Back to top

API Description

Parameters

Three parameters are required: (1) affiliate, (2) 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.
  • Replace SEARCH_TERM_ENTERED_IN_YOUR_SEARCH_BOX with 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.
Parameters Description
affiliate (required) Site handle
Example: affiliate=YOUR_SITE_HANDLE
access_key (required) The key used to access the API
Example: access_key=YOUR_UNIQUE_ACCESS_KEY_FROM_ADMIN_CENTER
query (required) Search term
Example: query=SEARCH_TERM_ENTERED_IN_YOUR_SEARCH_BOX
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 <U+E000> and <U+E001>, which both look like “”. You can learn more about them here and here (external resources). Your team will determine how to display the characters, whether as bold, italics, or some other preferred highlighting style.
Example: enable_highlighting=false
limit (optional) Defines the number of results to return. The default is 20, but you can specify between 1 and 50 results.
Example: limit=5
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.
Example: offset=20
sort_by (optional) Allowed variables are date and relevance. The default sort is relevance. Add sort_by=date to sort by date.

Expected Results

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.

  • query

    We return the query to you for use in the results page display.

  • web:total

    Total number of results available.

  • web:next_offset

    Offset for the subsequent results.

  • web:spelling_correction

    Spelling correction for your search term.

  • web:results

    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

    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

    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
  • health_topics

    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
  • job_openings

    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
  • recent_tweets

    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

    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

    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

    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

Back to top

Contact Us

Please never hesitate to reach out! Email the Search.gov team.

Back to top