1.0.6 • Published 3 months ago
bing-image-search v1.0.6
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'snextOffset
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