USASearch

Posts tagged api

How (and When) to Use the Search API

We offer our search results as a hosted results page or as an application programming interface (API). 

When to Use the Hosted Results

Most agencies use our hosted search results page. We recommend that you to use our hosted page for the typical use case of returning search results on your website. Using the hosted page has many benefits such as allowing you to:

  • Devote minimal development resources for the initial set up.
  • Benefit from new features automatically as they’re rolled out.
  • Stay current with search best practices, such as type-ahead search and formatting of search results.

When to Use the API

You may need to access our search results to present them outside of a typical search results page. We offer our results as an API for these use cases.

You can access the API and its documentation at Admin Center > YourSite > Search API. 

The API returns results from each of our indexes—web, image, document (ODIE), RSS (news), video, best bets (boosted content), and related searches—in JSON, JSON-P, or XML.

We recommend you use our API for limited use cases such as:

  • Displaying search results within a native mobile application (i.e., an Android or iPhone app).
  • Integrating USASearch results within existing applications (such as your intranet or publications catalog).
  • Creating data mashups.

Examples of how agencies are currently using the API follow.

Use Case 1. Display Results in Your Mobile App

USA.gov and the White House use the Search API to render USASearch results within their mobile apps. 


Screenshot of a USASearch results page in the USA.gov iPhone app

 
Screenshot of a USASearch results page in the White House iPhone app

Related Links

Use Case 2. Integrate USASearch Results within existing applications

RI.gov manages hundreds of distinct websites. The state provides a consistent search experience across all of its websites. Some sites are centrally controlled by RI.gov. Others are not. Using the Search API, RI.gov programmatically tells USASearch the site’s domain from which the user searched (e.g., tmc.dot.ri.gov). RI.gov then highlights results from this specific domain within RI.gov’s common look and feel.

See the sample results page below that shows a set of results displayed on Rhode Island’s Transportation Management Center for a search on traffic.

 
Step 1. Searcher on www.tmc.dot.ri.gov types traffic in the search box



Step 2. Searcher sees results on RI.gov with a common look and feel that highlights results from the original site

Did you know? The Search API is available for government websites only. Other, publicly available APIs (i.e., for use by anyone) are at http://www.usa.gov/About/developer-resources/developers.shtml.

USASearch > Admin Center > YourSite > Search API

Filed under how to api