Search Notes for the Week Ending February 8, 2013

Highlighted Feature

You can now access your raw HTTP logs. These logs contain valuable data on searches, clicks and USASearch tag page loads. 

Read How to Access Your Raw Logs for more details about how to request secure FTP access to your logs.

Other Features

  • We open sourced all of the code that powers our Recalls Server API in Github.
  • Searchers are now able to search and see results from collections that are not visible in the left-hand navigation on your “main” web results. You can use this option to provide a search box on a small subset of content (such as a policy manual or meeting minutes) while not cluttering up the left-hand navigation on your main results page. (It also helps reduce the likelihood that searchers experience a “dead end” on your main results page.)


  • We upgraded to CentOS 6.3.
  • We optimized the routing of search queries so that they’re served by the geographically closest datacenter. 

Filed under releases

How to Access Your Raw Logs

You can directly access your raw HTTP logs. The logs include valuable data on searches, clicks, and USASearch tag page loads.

With the raw logs, you can conduct in-depth, ad hoc analyses to answer any questions that you can’t answer using the standard analytics reports in the Admin Center. You can also automatically integrate your search logs with your other reports and business processes. 

To access your raw logs, you’ll first need to upload your public key on the Raw Logs Access page in the Admin Center

We’ll set up your public key on our secure FTP servers and send you an email when your logs are available for download. 

Once your key is set up, you’ll be able access your log files via secure FTP. We upload your logs each day, usually within several hours after midnight GMT. After a week, we purge the older files.

We recommend customers set up a cron script to automatically download the latest files each day.

Troubleshooting tip: On Unix systems, you can generate a RSA public key with no passphrase by typing in the following command. Once you’ve created a key, it’ll be located at /home/user/.ssh/

% cd ~
% ssh-keygen -q -b 4096 -t rsa
Enter file in which to save the key (/home/user/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:

USASearch > Admin Center > YourSite > Raw Logs Access

Filed under how to analytics

Help Searchers Find Federal Jobs

One of the most common search tasks conducted by public is looking for current job openings. To help searchers quickly find relevant jobs we have created the federal Jobs GovBox.

When you turn on the federal Jobs GovBox, searchers looking for jobs on your site will see up to three relevant USAJobs listings on your results page.

  • Federal Department Websites—If your website is affiliated with a specific federal department (e.g., Department of Commerce), the federal Jobs GovBox will return relevant, location- and keyword-matched job openings across all agencies within your department.
  • Federal Agency or Office Websites—If your website is affiliated with a specific federal agency (e.g., NOAA) or office (e.g, National Ocean Service), the federal Jobs GovBox will return relevant, location-and keyword-matched job openings at your agency.
  • State and Local Websites and Cross-Agency Portals—If your website is a state or local government site or a federal cross-agency portal (e.g.,, the federal Jobs GovBox will return relevant, location- and keyword-matched job openings across all federal agencies.

Searchers will also see a direct link to for all current job openings (specific to your department or agency, if applicable), as shown in the sample below for a search on jobs on the


Filed under GovBox Jobs how to

Search Notes for the Week Ending February 1, 2013

Highlighted Feature

The display of search results pages is constantly evolving. Some changes are subtle. Others are more noticeable.

In line with industry best practices and commercial search engines, we’ve moved the tools for filtering and sorting results to the top of results list (rather than on the left side). We’ve also added an option to clear all filters.




  • Searchers no longer see Did You Mean suggestions for your excluded domains.
  • We fixed a cross browser compatibility issue on the Query Logs page in the Admin Center so that the ‘number of clicks’ column is now visible.
  • We labeled the Safe Search radio options on our advanced search page as a fieldset to improve accessibility for screen readers.

Filed under releases

Search Notes for the Week Ending January 25, 2013

Highlighted Feature

This week we buckled down and analyzed data on jobs-related searches to ensure that the new federal Jobs GovBox lists the most relevant job openings. 

Searchers can now effectively search for jobs by keyword, agency, state, or work schedule (part-or full-time).

We also focused on not showing the Jobs GovBox when it isn’t relevant (for example, it is no longer shown when searchers look for job safety posters or employment verification forms).


  • We added our posting channel ID to all USAJobs links.
  • We set up a cron job to fetch and process job files from USAJobs.
  • We added impression and click tracking for the federal Jobs GovBox module.
  • We resolved performance discrepancy between our two datacenters.
  • We no longer use XML sitemaps to add documents to the USASearch web index.


  • You can now delete keywords from text best bets.
  • Newly added misspellings are now being applied to type-ahead suggestions.
  • Searchers can now find jobs in non-standard state locations (for example someone searching for jobs in Washington, DC, will find postings the the location of Washington DC Metro Area, District of Columbia).

Filed under releases

Search Notes for the Week Ending January 11, 2013

Highlighted Feature: The federal Jobs GovBox

We’re excited to announce that searchers looking for jobs on your site can now see all of your agency’s current job openings.

Our new federal Jobs Govbox displays up to three location- and keyword-matched job openings on your results page. For more information on how to turn on this GovBox, see How To Select The Modules That Appear On Your Results Page.

We’ve also open sourced all of the code that powers our Federal Jobs Server API in Github.


And, we’ve already pushed two bug fixes for the federal Jobs GovBox to production. Searchers no longer see yet-to-be-opened or already closed jobs. 

Filed under releases

Release Notes for the Week Ending January 4, 2013

Highlighted Feature

Are you curious about the most searched for terms on your site in the past year? They’ll arrive in your inbox in our new, annual Year-in-Review email.

We’ll send you an email every December 15 (along with cheer and goodwill) with a list of the top 1,000 terms searched for on your site over the past year and how many times each term was searched.

Other Features

  • Developers using our jobs API can find agency-specific jobs by searching for an agency’s name, abbreviation, or other variant.



  • Searchers and API users are now able to maintain a HTTP connection for multiple requests resulting in shorter response times.

Filed under releases

Search Notes for the Week Ending December 14, 2012

Highlighted Feature

Did you know that mobile search traffic increases during the holidays? 

You can now customize the header on your mobile search results page to create a more seamless experience for visitors to your mobile website. Our new feature allows you to upload your mobile logo and specify a mobile homepage URL.

USASearch > Admin Center > YourSite > Header and Footer

Other Features

  • Searchers see Bing image results followed by results from your Flickr photostream. (Example: search for images about hurricane sandy on
  • Searchers can now sort RSS-based results (such as press releases, blogs, etc.) by date or relevance.
  • Searchers now only see tweets from up to three months ago.
  • Searchers now only see articles from up to one year ago in the News GovBox.
  • You can now exclude specific subdomains or folders from your search results on the Excluded Domains page in the Admin Center.
  • You can now segment the keywords for your text Best Bets.
  • You now see your domains listed in A-Z order on the Domains page in the Admin Center.
  • You now see your requested 3rd Party Tracking scripts in the Admin Center.
  • You can now access collection results via our API.


  • We refined the rules of our fetcher to index only HTML pages with the USASearch Javascript tag and any PDF or Microsoft Office documents linked from the tagged HTML page.
  • We automatically remove the repetitive @ if you include it as part of your Twitter handle on the Social Media page in the Admin Center.
  • We automatically resize your mobile header image if it is too big.
  • We updated our Linux kernels, Jenkins, New Relic, and lots of RubyGems.


  • Searchers can now set a custom date range even if type-ahead search is disabled on your results page.
  • Searchers no longer see inactive best bets as recommended pages in the type-ahead search.
  • Images no longer overlap on image search results pages.
  • We now show both queries and clicks in the analytics reports for customers with really long site handles.
  • We fixed a bug with how we recorded clicks for searches with apostrophes.
  • We show you an error message when you try to upload an improperly encoded URL  via the URLs & Sitemaps page in the Admin Center.

Filed under releases

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 and the White House use the Search API to render USASearch results within their mobile apps. 

Screenshot of a USASearch results page in the 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 manages hundreds of distinct websites. The state provides a consistent search experience across all of its websites. Some sites are centrally controlled by Others are not. Using the Search API, programmatically tells USASearch the site’s domain from which the user searched (e.g., then highlights results from this specific domain within’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 types traffic in the search box

Step 2. Searcher sees results on 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

USASearch > Admin Center > YourSite > Search API

Filed under how to api

A Punch List to Go Live with USASearch

Your pre-launch checklist will be unique to your agency’s workflow, requirements, and deadlines. A typical punch list to go live with USASearch follows.

Connect Your Site to USASearch

Most agencies add these two snippets of code to the template(s) in their content management systems (rather than adding them to individual pages).

Check box icon 1. Does your search box point to USASearch? Update your search box form code point to USASearch so that, when users execute a search, they’ll see your USASearch-hosted results page.

<form accept-charset="UTF-8" action="" id="search_form" method="get"><div style="margin:0;padding:0;display:inline"><input name="utf8" type="hidden" value="&#x2713;" /></div>
<input id="affiliate" name="affiliate" type="hidden" value="YourSiteHandle" />
<label for="query">Enter Search Term(s):</label>
<input autocomplete="off" class="usagov-search-autocomplete" id="query" name="query" type="text" />
<input name="commit" type="submit" value="Search" />

Check box icon 2. Do you have the USASearch Javascript tag on your webpages? This Javascript helps us find your new and updated pages. It also powers the type-ahead search.

<script type="text/javascript">
      var usasearch_config = { siteHandle:"YourSiteHandle" };
      var script = document.createElement("script");
      script.type = "text/javascript";
      script.src = "";

Double Check Your Content Sources

Check box icon 3. Have you told us which domain(s) you want to search? List one or more domains that you want to search on the first page of web results.  Most agencies opt to leave out the ‘www’ to include all subdomains (e.g., list to include,,, etc). Some agencies—especially department-level portals—opt to also include their bureaus’ websites (e.g., includes,,, etc.)

Check box icon 4. Have you told us about your RSS feeds? We love RSS feeds. Tell us about all of your feeds, even if you opt not to show them  (see #7 below). They’re the quickest way for you to tell us about your new and updated content. Feeds also have well-structured titles, URLs, descriptions, and dates that we use to improve your search results page. (Tip: Preview your feeds from the RSS page in the Admin Center to confirm that we’ve indexed your content.)

Check box icon 5. Have you told us about your social media accounts? Flickr photostreams, tweets, and YouTube videos are a great way to highlight your recent content and to let searchers know about your social media channels. Tell us about all of your social media, even if you opt not to show them (see #7 below). 

Customize Your User Interface

Check box icon 6. Have you made the search results page look like your website? Customize the look and feel (colors, fonts, favicon) and header and footer of your search results page to create a seamless experience for users as they search and browse your website.

Check box icon 7. Have you told us what to show on your results page? Tell us which results modules (i.e., the stuff in the center of the page) and sidebar options (i.e., the navigation in the left-hand column) you want to appear on your search results.

Set Up Nice-to-Have Features (Optional)

Check box icon 8. Have you masked your domain?  We offer DNS masking, which allows you to show searchers your (instead of If you leverage DNS masking you will have to change your search box form action from to 

Check box icon 9. Have you added the Javascripts for your other third party web services to your results page? If you have a third party service running on your website, you likely want it to run on your results page. Agencies often include their 4Q, AddThis, Foresee, Google Analytics, Omniture, or WebTrends code, among others.

Don’t Forget SEO (Optional)

Check box icon 10. Have you optimized your site so we can find your content? We follow search engine optimization (SEO) best practices. Verify that you have a robots.txt and an XML sitemap. These two files are typically located in the root directory of your website (i.e., and, respectively). Also verify that your robots.txt file allows our user agent (usasearch) to access your public content.

Check box icon 11. Have you registered your site with the major commercial search engines? Register for both Bing Webmaster Tools and Google Webmaster Tools to maximize the coverage of your content in their search results.

Filed under how to