Important Note: April, 2018 - For new implementations, the Search.gov team recommends you index your content with us not using the i14y API, but rather by publishing a comprehensive xml sitemap, which we can use to index your content. Read more.
i14y Github repo (External link)
What is i14y?
i14y is a content indexing API that allows you to send your content directly to our indexes. When your site is enabled for i14y, it gives you complete control over what searchers see. No commercial web results will be served: instead, searchers will see content exactly as you’ve sent it to us.
How Do I Use i14y?
If you use a different CMS, or don’t have one at all, we recommend you focus on publishing a comprehensive xml sitemap, which we would leverage to index your content.
Important Note: i14y does not visit your content to do full-text scraping of your content. For new implementations, the Search.gov team recommends you index your content with us not using the i14y API, but rather by publishing a comprehensive xml sitemap, which we can use to index your content. Read more.
Checklist to Go Live with i14y
Step 1. Connect one of your sites to i14y
i14y needs to be enabled in the back end for a site to be able to receive content through it. You can
- Add a brand new search site,
- Use the Clone Site tool to copy one of your existing site’s settings to a new site (
YourSite > Dashboard > Clone Site), or
- use an existing site.
Email us and let us know which site you want enabled for i14y. Please note: once we turn on i14y for a site, we no longer serve search results from a commercial web index. Therefore, we recommend that you set up a test site for i14y, so that your customers will continue to get results until you are fully set up and ready to move your i14y index to your production search site.
Step 2. Add a Drawer
An i14y Drawer is an index receiving content via the i14y API. We’ve called them Drawers because, like drawers in a filing cabinet, multiple indexes can be included in a single configuration to scope the entirety of a site’s search.
After we have enabled i14y for your search site, a new page will appear: Admin Center > YourSite > Manage Content > i14y Drawers.
Add i14y Drawer in the upper right corner. Create a handle for your drawer - the handle must be all lowercase alphanumeric, all one word, and can include underscores but no other special characters (e.g., agency_drawer_handle2).
The Drawer Description is optional.
If you have more than one website or domain that will be sending content, add a separate Drawer for each of these sites. We also recommend setting up separate drawers for staging or test content, so you can easily remove that content from your search site when you are ready to go live.
Step 3. Fill your Drawer
After you have created your Drawer(s), click
Show from the i14y Drawers list to find that Drawer’s secret API key. Use this secret key with your drawer handle in your API call or your CMS module to send your content to the right place.
You are now ready to add content to your drawer. You can do this in two ways:
- Use i14y directly. View our Github repo (External link) or Technical Documentation for more information.
- Use a module plugged into your CMS. At this time there is a Drupal module (External link) available. Help docs for the module are here.
- Important Note: i14y does not visit your content to do full-text scraping of your content. For new implementations, the Search.gov team recommends you index your content with us not using the i14y API, but rather by publishing a comprehensive xml sitemap, which we can use to index your content. Read more.
Step 4. Review your index
You can view the number of documents indexed for each drawer on the main i14y Drawers list, and when the most recent document was received. Click
Show to view documents within a particular drawer. We display the most recent 1,000 items that were sent to the drawer. You can also search for keywords in the documents’ text, titles, and descriptions (Note: you cannot currently search for URLs).
Note: We use the Domains section to scope search results - if the domain(s) of your i14y content are not listed in the Domains section, that content will not appear on your search results page.
We send success and / or failure codes in response to your API call, so if the number of documents in our index doesn’t match what you sent, check those response codes.
If you experience difficulty sending documents to i14y, it is possible your firewall is not letting you communicate with the i14y server. Check out our cURL test commands or view the full i14y documentation.
We can attach each i14y drawer to multiple search configurations: if you have a drawer that you’d like to use for multiple search sites, email us.
Caution: A pop-up message will appear when you hit
Remove on a drawer: please review this pop-up message carefully. If you remove a drawer that is only associated with one search configuration, the drawer and its contents will be deleted from our system. If the drawer is attached to multiple search configurations, it will only be removed from the search configuration you are currently on. The pop-up message will indicate what type of drawer you have.
If you accidentally delete a drawer, you will need to set-up a new drawer and resend the content - we are unable to retrieve deleted drawers. If you accidentally remove a shared drawer but it is still associated with other search configurations, we can re-attach it to your site. Contact us for assistance.
Step 5. Configure your search
Once you have your index populated, you will set up the rest of your search as you would for a traditional Search.gov site:
- Set your default search scope on your Domains page. Use the Filter Tags feature to further scope your search results.
- Add social media accounts: Flickr, Twitter, and YouTube
- Create Collections and Best Bets
- Select your display settings (both search features and branding).
If you have any RSS content that will not be sent to your i14y drawer, you can add those feeds as well.
Step 6. Update your search box
Update your website’s search box form code to point to
By accessing the i14y API, you agree to USA.gov’s Terms of Service for Developer Resources.
Did you know? i14y is hacker shorthand for “interoperability”, because there are 14 characters between the first and last letters. i14y can also be shorthand for Independence Day.