Posts tagged activate-search

How to Mask Your Domain

We offer DNS masking, which allows you to show searchers search.YOURAGENCY.gov (instead of search.USA.gov). Follow these steps to mask your domain. Please note that due to limitations in the size of our SSL certificate, we are only able to offer top level domain masking: i.e., search.youragency.gov but not search.subagency.youragency.gov.

  1. Create a search subdomain for your domain. If search is already in use in your environment, you could use find or findit as your subdomain.

  2. Create a CNAME in your external DNS records for search.youragency.gov. Point it to yoursitehandle.sites.infr.search.usa.gov. Your site handle is listed on the settings page in the Search Admin Center.

    For example: if your site handle is abc, the DNS record would look like this:

     search.youragency.gov   CNAME  abc.sites.infr.search.usa.gov
    

    NOTE: if your site handle contains a ., please replace it with a - in your DNS record, e.g., for site handle abc.gov.search the DNS record would look like this:

     search.youragency.gov   CNAME  abc-gov-search.sites.infr.search.usa.gov
    
  3. After your DNS record has been added, email us to request to be added to our SSL certificate. If your CNAME is not on our SSL certificate, browser security warnings will appear when your search results page attemps to load over HTTPS. It generally takes a few days for these requests to get through our queue.

    Your domain mask will work as soon as these two steps are complete.

  4. When your DNS record is in place and you have received confirmation that your domain mask has been added to our SSL certificate, change your search box’s form code action from search.usa.gov/search to search.youragency.gov/search.


Troubleshooting tip: Many agencies have both internal and external DNS. Be sure to update your external DNS records (step 1) before changing your form code (step 2).

Did you know? Any search site within your domain may use the same domain mask and CNAME record, even if the CNAME is not associated with that particular site’s handle. To implement an existing mask for a search box, just do Step 2, above.

Did you know? Once the CNAME is set up, if visitors to your site happen to truncate the URL in the browser bar to http://search.youragency.gov (without any parameters), they’re automatically redirected to your agency’s homepage at http://www.youragency.gov.

Did you know? Most of our customers use a search.youragency.gov mask (such as search.nih.gov). If the search subdomain is already used by another application, you can use find or findit, such as find.irs.gov or findit.state.gov. We no longer support other subdomain patterns.

Showing Results Within Your Agency's Website

We offer an API that allows agencies to display results from our service on their website. Instead of searchers going to our hosted search results page, agencies can use the “Search Results API” to pull results from our service and display the results within their own pages. Agencies that want to maintain an exact match of their headers, footers, and other branding are encouraged to use this API.

The API exposes all relevant results “modules” in a single JSON call, including:

Note about Web Results: To retrieve web results through this API, you must either use our indexes (populated via the i14y API or via RSS), or you must purchase an API key from Bing.

This API is available for use on official government websites only. You must be a Search.gov customer to access the instructions. Sign in is required.

Instructions can be found under Admin Center > YourSite > Activate Search > Search Results API Instructions. The Search Results API key can be found under Admin Center > YourSite > Activate Search > API Access Key.

Displaying Type-ahead Suggestions on Your Agency's Website

Note: this information is for customers who wish to display type-ahead (autocomplete) suggestions on their agency’s website. If you are only looking to turn on type-ahead suggestions on your search results page, please review the instructions on our Display Overview page.

There are two ways to get type-ahead suggestions to appear on your agency’s website.

JavaScript Snippet

We offer a JavaScript snippet that is placed on your pages before the closing </body> tag.

You must be a Search.gov customer to use this feature. Full instructions and code can be found under Admin Center > YourSite > Activate Search > Code Snippets.

The code will look similar to:

<script type="text/javascript">
//<![CDATA[
      var usasearch_config = { siteHandle:"YourSiteHandle" };

      var script = document.createElement("script");
      script.type = "text/javascript";
      script.src = "//search.usa.gov/javascripts/remote.loader.js";
      document.getElementsByTagName("head")[0].appendChild(script);

//]]>
</script>

Type-ahead API

The Type-ahead API exposes your site’s type-ahead suggestions. Calling the API directly alllows you to show type-ahead suggestions without adding the JavaScript code.

This API is available for use on official government websites only. You must be a Search.gov customer to access the instructions. Sign in is required.

Keys and instructions can be found under Admin Center > YourSite > Activate Search > Type-ahead API Instructions.


Troubleshooting: Suggestions are derived from the searches performed on your website. For additional details, please review the Type-ahead API section in the Search Admin Center.

How to Activate Your Search by Adding Our Code Snippets to Your Website

Search.gov Home > Admin Center > YourSite > Activate Search > Code Snippets

Visit our Admin Center, select your site, and click on the Activate Search option in the left-hand menu.

Add the following two snippets of code to your website to “hook” your website and our hosted search service together. You can add this code to your individual web pages or to the template(s) in your content management system.

1. Form Snippet

Include this snippet of code where the form for your search box appears. It should look something like this:

<form accept-charset="UTF-8" action="https://search.usa.gov/search" 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" />
</form>

2. Javascript Snippet

Include this snippet of code before the closing </body> tag. This tag enables type-ahead search in the search box on your web pages and powers the data on trending URLs on the Site Overview page in the Admin Center. It should look something like this:

<script type="text/javascript">
//<![CDATA[
      var usasearch_config = { siteHandle:"YourSiteHandle" };

      var script = document.createElement("script");
      script.type = "text/javascript";
      script.src = "//search.usa.gov/javascripts/remote.loader.js";
      document.getElementsByTagName("head")[0].appendChild(script);

//]]>
</script>

Advanced: Options for Limiting a Search Box to Specific Folders or Subdomains

You can limit results to specific folders or subdomains by creating a collection, setting up an RSS feed, or passing in a hidden value.

Option 1. Limit to Collections

Create a collection. Then update your form code to (a) change the action to action="https://search.usa.gov/search/docs/ and (b) add an input for this collection, <input type="hidden" name="dc" value="###">. It should look something like this:

<form accept-charset="UTF-8" action="https://search.usa.gov/search/docs/" id="search_form" method="get">
    <div style="margin:0;padding:0;display:inline">
    <input type="hidden" name="dc" value="###">
    <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" />
</form>

The value is the number for your collection ID, which is visible in the URL when you edit your collection in the Admin Center as shown in the sample below.

Value for the collection ID

Option 2. Limit to RSS Feeds

Set up an RSS feed. Then update your form code to (a) change the action to action="https://search.usa.gov/search/news/ and (b) add an input for this feed, <input type="hidden" name="channel" value="###">. It should look something like this:

<form accept-charset="UTF-8" action="https://search.usa.gov/search/news/" id="search_form" method="get">
    <div style="margin:0;padding:0;display:inline">
    <input type="hidden" name="channel" value="###">
    <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" />
</form>

The value is the number for your RSS ID, which is visible in the URL when you edit or preview your feed in the Admin Center.

Option 3. Limit to a Hidden Domain Value

Leave your domain blank on the Domains page and, instead, pass a hidden value for the domain in the search form code.

For example, on health.agency.gov, the following hidden value would be added to limit results to only the health subdomain.

<input type="hidden" name="sitelimit" id="sitelimit" value="www.health.agency.gov" >

Did you know? If you’re using Drupal, be sure to check out our Drupal module.

Did you know? We offer DNS masking, which allows you to show searchers your domain (instead of USA.gov).