hubot-search

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

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

  npm install --save hubot-search
  

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

  [
      "hubot-search"
  ]
  

• 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

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

Create Google Custom Search Engine

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

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

• Edit your newly created search engine

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

• 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.

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

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

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

• 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.

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

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

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

• 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
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>> ...