Bing Image Search Async Iterator

Query Bing Image Search API (v7) and get an async iterator of response objects.

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 a subsequent API call. This module automates the process of filling the offset parameter value and determines when to stop making API calls— what you get in the end is a async iterator of parsed responses.

Response objects

Please note that response objects wrap search results in the value field.

``JS
{
_type: 'Images',
totalEstimatedMatches: 834,
nextOffset: 195,
value: [
{
name: ...,
thumbnailUrl: ...,
datePublished: ...,
contentUrl: ...,
...
},
...
],
...
}
`

This module doesn't unwrap search results for you because response objects may contain additional metadata (e.g., queryExpansions, pivotSuggestions, similarTerms and relatedSearches).

Installation


`
npm install --save bing-image-search-async-iterator
`

Example Usage

This example prints out unwrapped search results returned from the API calls.

`js
const search = require('bing-image-search-async-iterator');

(async () => {
const responses = search({
key:'',
query: 'kittens',
amount: 151,
})
for await (const response of responses) {
for (const result of response.value) {
console.log(result);
}
}
})();
`

Options

$3

These are the main parameters you should specify.

| Parameter | Type | Default | Description |
| ------------ | ---------- | -------------- | ------------------------------------------------------------------ |
| key | string | | (Required) Bing Image Search API Subscription Key |
| query | string | | (Required) Search query |
| amount | integer | 2000 | Desired count of results |
| market | string | | Market Code of request origin (e.g., en-US) |
| safeSearch | string | Moderate | Filter adult content (Off, Moderate, Strict) |

$3

You may specify your search query's filters with the following settings.

| Parameter | Type | Default | Description |
| ------------ | ---------- | -------------- | ------------------------------------------------------------------ |
| aspect | string | All | Filter images by aspect ratio (Square, Wide, Tall, All) |
| color | string | | Filter images by color (ColorOnly, Monochrome, Black, Blue, Brown, Gray, Green, Orange, Pink, Purple, Red, Teal, White, Yellow) |
| imageContent | string | | Filter images by content type (Face, Portrait) |
| imageType | string | | Filter images by image type (AnimatedGif, AnimatedGifHttps, Clipart, Line, Photo, Shopping, Transparent) |
| license | string | All | Filter images by image license type (Any, Public, Share, ShareCommercially, Modify, ModifyCommercially, All); Any excludes images without known license |
| freshness | string | | Filter images by discovery time (Day, Week, Month) |
| size | string | All | Filter images by image size (Small, Medium, Large, Wallpaper, All) |
| width | integer | | Filter images by specific width |
| height | integer | | Filter images by specific height |
| minWidth | integer | | Filter images by where width is greater than or equal to specified value |
| minHeight | integer | | Filter images by where height is greater than or equal to specified value |
| maxWidth | integer | | Filter images by where width is less than or equal to specified value |
| maxHeight | integer | | Filter images by where height is less than or equal to specified value |
| minFileSize | integer | | Filter images by where file size is greater than or equal to specifie value |
| maxFileSize | integer | | Filter images by where file size is less than or equal to specified value |

$3

You do not need to set these parameters under normal circumstances.

| Parameter | Type | Default | Description |
| ------------ | ---------- | -------------- | ------------------------------------------------------------------ |
| offset | integer | 0 | Offset of the initial API call |
| count | integer | 150 | Count of results per API call (lower this value may result in more API calls) |
| clientID | string | | API request header X-MSEdge-ClientID (auto-determined if not set) |
| clientIP | string | | API request header X-MSEdge-ClientIP |
| location | string | | API request header X-Search-Location |
| queryParams | object | | Additional query params (e.g., { imageType: "AnimatedGif" }) |
| headerParams | object | | Additional header params (e.g., { Pragma: "no-cache" }) |
| fetchCb | function | fetch | Callback to construct a request that returns a response promise |

Features

- Turns a search query into an async iterator of search API call response objects
- Ends iterator _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
- Fills in X-MSEdge-ClientID` automatically based on previous API responses

License

MIT