bing-image-search

Bing Image Search

Tool to query the Bing Image Search API (v7).

Motivation

Bing Image Search API returns up to 150 results per API call. To access more results, you need to specify the proper offset request parameter in subsequent API calls. This tool automates the process of filling the offset parameter value and determines when to stop making API calls.

Installation

npm install --global bing-image-search

Usage

usage: bing-image-search [-h] [-v] [--key KEY] [--amount AMOUNT]
                         [--market MARKET] [--safeSearch MODE]
                         [--aspect ASPECT] [--color COLOR]
                         [--imageContent TYPE] [--imageType TYPE]
                         [--license LICENSE] [--freshness VALUE] [--size SIZE]
                         [--width VALUE] [--height VALUE] [--minWidth VALUE]
                         [--minHeight VALUE] [--maxWidth VALUE]
                         [--maxHeight VALUE] [--minFileSize VALUE]
                         [--maxFileSize VALUE] [--indent SPACES]
                         [--qparam KEY VALUE] [--hparam KEY VALUE] [--raw]
                         query

Bing Image Search

Optional arguments:
  -h, --help           Show this help message and exit.
  -v, --version        Show program's version number and exit.

  Basic arguments

  query                Search query string
  --key KEY            API Key (or set BING_IMAGE_SEARCH_API_KEY instead)
  --amount AMOUNT      Total results desired (default: 2000)
  --market MARKET      Market code (e.g., "en-US")
  --safeSearch MODE    Safe search ("Off", "Moderate", "Strict")

  Filter arguments

  --aspect ASPECT      Aspect ratio ("Square", "Wide", "Tall", "All")
  --color COLOR        Color ("ColorOnly", "Monochrome", "Black", "Blue",
                       "Brown", "Gray", "Green", "Orange", "Pink", "Purple",
                       "Red", "Teal", "White", "Yellow")
  --imageContent TYPE  Content type ("Face", "Portrait")
  --imageType TYPE     Image type ("AnimatedGif", "AnimatedGifHttps",
                       "Clipart", "Line", "Photo", "Shopping", "Transparent")
  --license LICENSE    Image license type ("Any", "Public", "Share",
                       "ShareCommercially", "Modify", "ModifyCommercially",
                       "All"); "Any" excludes images without known license
  --freshness VALUE    Discovery time ("Day", "Week", "Month")
  --size SIZE          Image size ("Small", "Medium", "Large", "Wallpaper",
                       "All")
  --width VALUE        Width is equal to VALUE
  --height VALUE       Height is equal to VALUE
  --minWidth VALUE     Width is greater than or equal to VALUE
  --minHeight VALUE    Height is greater than or equal to VALUE
  --maxWidth VALUE     Width is less than or equal to VALUE
  --maxHeight VALUE    Height is less than or equal to VALUE
  --minFileSize VALUE  File is size greater than or equal to VALUE
  --maxFileSize VALUE  File is size less than or equal to VLAUE

  Special arguments

  --indent SPACES      Spaces to indent JSON outputs (default: 2)
  --qparam KEY VALUE   Add query param (multiples allowed)
  --hparam KEY VALUE   Add header param (multiples allowed)
  --raw                Do not unwrap search results from API responses

For more information, check out these links:

• Get your Bing Search API Key
• Bing Search Advanced Operator Reference
• Market code options
• SafeSearch options

Example

To search for "kittens", execute the following command:

Command

bing-image-search --key <YOUR_API_SUBSCRIPTION_KEY> --amount 2 kittens

Output

{
  "webSearchUrl": "https://www.bing.com/images/search?view=detailv2&FORM=OIIRPO&q=kittens&id=[redacted]&simid=[redacted]",
  "name": "wallpapers: Maine Coon kittens",
  "thumbnailUrl": "https://tse4.mm.bing.net/th?id=[redacted]&pid=Api",
  "datePublished": "2011-12-12T12:00:00.0000000Z",
  "contentUrl": "http://1.bp.blogspot.com/-9Z45_45PdN0/T5ZVrvnx7MI/AAAAAAAACLI/_omn-glE4iM/s1600/Maine+Coon+kittens.jpg",
  "hostPageUrl": "http://wallpapers-xs.blogspot.com/2012/04/maine-coon-kittens.html",
  "contentSize": "194706 B",
  "encodingFormat": "jpeg",
  "hostPageDisplayUrl": "wallpapers-xs.blogspot.com/2012/04/maine-coon-kittens.html",
  "width": 1600,
  "height": 1200,
  "thumbnail": {
    "width": 474,
    "height": 355
  },
  "imageInsightsToken": "[redacted]",
  "insightsMetadata": {
    "recipeSourcesCount": 0,
    "bestRepresentativeQuery": {
      "text": "Maine Coon Cats Kittens",
      "displayText": "Maine Coon Cats Kittens",
      "webSearchUrl": "https://www.bing.com/images/search?q=Maine+Coon+Cats+Kittens&id=[redacted]&FORM=IDBQDM"
    },
    "pagesIncludingCount": 62,
    "availableSizesCount": 18
  },
  "imageId": "A753D07B2EDAFCD2F61EG905A1EF6CC373727D84",
  "accentColor": "808A41"
}
{
  "webSearchUrl": "https://www.bing.com/images/search?view=detailv2&FORM=OIIRPO&q=kittens&id=[redacted]&simid=[redacted]",
  "name": "Kittens Wallpapers - Pets Cute and Docile",
  "thumbnailUrl": "https://tse4.mm.bing.net/th?id=[redacted]&pid=Api",
  "datePublished": "2018-03-14T22:15:00.0000000Z",
  "contentUrl": "http://1.bp.blogspot.com/-xzYw9bwU11s/T_VUmLlVG2I/AAAAAAAAD1o/RFswfHEUtAk/s1600/Kittens+wallpapers+2.jpg",
  "hostPageUrl": "http://dark-horse-adaptations.blogspot.com/2012/07/kittens-wallpapers.html",
  "contentSize": "248162 B",
  "encodingFormat": "jpeg",
  "hostPageDisplayUrl": "dark-horse-adaptations.blogspot.com/2012/07/kittens-wallpapers.html",
  "width": 1024,
  "height": 768,
  "thumbnail": {
    "width": 474,
    "height": 355
  },
  "imageInsightsToken": "[redacted]",
  "insightsMetadata": {
    "recipeSourcesCount": 0,
    "bestRepresentativeQuery": {
      "text": "Cute Calico Kitten",
      "displayText": "Cute Calico Kitten",
      "webSearchUrl": "https://www.bing.com/images/search?q=Cute+Calico+Kitten&id=[redacted]&FORM=IDBQDM"
    },
    "pagesIncludingCount": 85,
    "availableSizesCount": 20
  },
  "imageId": "832CB1C6B258E8A041A7545DAD0D5F92F2ABD8EF",
  "accentColor": "AFAB1C"
}

Features

• Stops output when requested amount is reached or when there are no more results
• Avoids results overlap by specifying the offset API parameter with previous response's nextOffset value
• Sets the X-MSEdge-ClientID header according to the previous API response

Raw responses

If you specify the --raw flag, you get raw responses with additional metadata (e.g., queryExpansions, pivotSuggestions, similarTerms and relatedSearches). To access the search results, you will need to extract them out of the value field from each of the raw responses.

{
  "_type": "Images",
  "totalEstimatedMatches": 834,
  "nextOffset": 195,
  "value": [
    {
      "webSearchUrl": ...,
      "name": ...,
      "thumbnailUrl": ...,
      "datePublished": ...,
      "contentUrl": ...,
      ...
    },
    ...
  ],
  "queryExpansions": ...,
  "pivotSuggestions": ...,
  "similarTerms": ...,
  "relatedSearches": ...,
  ...
}
{ ... }
{ ... }

License

MIT