hubot-search

An extendable Hubot script for querying several search engine services: Google Custom Search, Azure Marketplace - Bing Search API v2, and Microsoft Cognitive Services - Bing Search API v5.

See src/search.coffee for full documentation.

Attention: Azure Marketplace "Bing Search" and "Bing Search Web Results Only" API (v2) offerings will end of life on December 15, 2016.

Currently by default, this script will use Azure Marketplace - Bing Search API v2, and the BING_SEARCH_API_KEY environment variable should be the v2 key (from Azure Marketplace).

Nevertheless, we strongly recommend that you use Microsoft Cognitive Services - Bing Search API v5 by setting USE_BING_V5 to true in the environment that is using this script, and ensuring the BING_SEARCH_API_KEY is the v5 key (from Cognitive Services).

USE_BING_V5 will not be necessary by 2017 when the v2 API is deprecated at end of life.

Installation via NPM

1. Install the hubot-search module as a Hubot dependency by running:

   npm install --save hubot-search

2. Enable the module by adding the hubot-search entry to your external-scripts.json file:

   [
       "hubot-search"
   ]

3. Run your bot and see below for available config / commands

Configuration

Variable | Default | Description --- | --- | --- GOOGLE_API_KEY | N/A | A unique developer API key is required to use Google's Custom Search API GOOGLE_CUSTOM_SEARCH | N/A | The Google Custom Search engine identifier (the cx portion of the custom search engine URL) BING_SEARCH_API_KEY | N/A | The API key for performing Bing Search API queries MAX_SEARCH_RESULTS | 5 | The number of search results to return

Google Custom Search

The Google Custom Search command listener will not be registered if neither GOOGLE_API_KEY nor GOOGLE_CUSTOM_SEARCH environment variables are defined.

Create Google API Key

1. Create a new API key: https://console.developers.google.com/apis/credentials
2. Select "Server key" for the type. You may be required to create a new project, just follow the instructions
3. Return to the "Overview", and locate "Custom Search API"
4. Enable "Custom Search API"

Create Google Custom Search Engine

1. Create a new Google Custom Search engine: https://cse.google.com/cse/create/new

2. To search all websites, enter any web URL in (1), and complete the creation

3. Edit your newly created search engine

4. Set "Sites to search" to "Search the entire web but emphasize included sites", and delete the sites you have previously added

5. Save, and export the variables:

   export GOOGLE_API_KEY="API KEY HERE"
   export GOOGLE_CUSTOM_SEARCH="ENGINE ID HERE"

Azure Marketplace - Bing Search API v2

The Bing Search API command listener will not be registered if BING_SEARCH_API_KEY is not defined.

1. Visit https://datamarket.azure.com/dataset/bing/searchweb

2. Subscribe for a "Bing Search API – Web Results Only" package / plan (free works fine)

3. Obtain the primary account key (located at the top of the page under "Show")

4. Export the API key:

   export BING_SEARCH_API_KEY="API KEY HERE"

Microsoft Cognitive Services - Bing Search API v5

The Bing Search API command listener will not be registered if BING_SEARCH_API_KEY is not defined.

1. Visit https://www.microsoft.com/cognitive-services/en-us/subscriptions?productId=/products/56ec2de6bca1df083495c610

2. Subscribe for a "Bing Web Search" package / plan (free works fine)

3. Obtain the API key (located in the "Keys" column; click "Show")

4. Export the API key:

   export BING_SEARCH_API_KEY="API KEY HERE"
   export USE_BING_V5="true"

Commands

Command | Listener ID | Description --- | --- | --- hubot <search|google> query | search.google | Queries Google Custom Search for query, and returns the first MAX_SEARCH_RESULTS results hubot bing query | search.bing | Queries Bing Search API for query, and returns the first MAX_SEARCH_RESULTS results

Sample Interaction

user1>> hubot search Elon Musk
hubot>> 1. Elon Musk - Wikipedia, the free encyclopedia: Elon Reeve Musk is a South African-born Canadian-American business magnate
, engineer, and investor. He is the founder, CEO and CTO of SpaceX; ... (https://en.wikipedia.org/wiki/Elon_Musk)
hubot>> ...