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 > Activate Search > API Instructions.
The API returns results from each of our indexes—web, image, document (ODIE), RSS (news), video, best bets (boosted content), related searches, and jobs—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 DigitalGov Search 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
The White House uses the Search API to render DigitalGov Search results within their mobile apps.
Screenshot of a DigitalGov Search results page in the White House iPhone app
Related Links for Use Case 1
- WhiteHouse mobile app
- White House Github account (information on and source code for the iOS and Android mobile apps)
Use Case 2. Integrate DigitalGov Search 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 us 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 http://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. Visit our APIs page for other, publicly available APIs (i.e., for use by anyone).