diff --git a/index.js b/index.js index 1fb963d..07a1c4e 100644 --- a/index.js +++ b/index.js @@ -40,6 +40,22 @@ class Client { result.imgSize = options.size; } + if (options.type) { + result.imgType = options.type; + } + + if (options.dominantColor) { + result.imgDominantColor = options.dominantColor; + } + + if (options.colorType) { + result.imgColorType = options.colorType; + } + + if (options.safe) { + result.safe = options.safe; + } + return qs.stringify(result); } diff --git a/readme.md b/readme.md index 29aab9a..d243b6f 100644 --- a/readme.md +++ b/readme.md @@ -50,6 +50,77 @@ client.search('Steve Angello', { ``` +## API + +Please see Google's [API documentation](https://developers.google.com/custom-search/json-api/v1/reference/cse/list#parameters) for details on the option and response properties and their possible values. Note that the option names used here may differ slightly (e.g. no `img` prefix). + +### Client(engineId, apiKey) + +#### engineId + +Type: `string` + +The [identifier](https://developers.google.com/custom-search/json-api/v1/overview#prerequisites) for a Custom Search Engine to use. + +#### apiKey + +Type: `string` + +The [credentials](https://support.google.com/googleapi/answer/6158857?hl=en) for accessing Google's API. + +### Instance + +#### .search(query, option) + +Perform an image search for `query`. + +##### query + +Type: `string` + +The search terms to use for finding images. Identical to those you would use in a web search. + +##### option + +Type: `object` + +###### page + +Type: `number`
+Default: `1` + +The range of results to return. Useful because often results cannot be returned in a single response. Note that it is a one-based unsigned integer. E.g. page `1` has the first 10 results, page `2` has the next set of 10, etc. + +###### size + +Type: `string` + +The size of images to search. E.g. `medium` or `xxlarge`. + +###### type + +Type: `string` + +The category of images to search. E.g. `face` or `photo`. + +###### dominantColor + +Type: `string` + +The [dominant color](https://designshack.net/articles/graphics/understanding-color-dominant-vs-recessive-colors/) to search for. E.g. `yellow` or `purple`. + +###### colorType + +Type: `string` + +The category of color spectrums to search. E.g. `gray` or `color`. + +###### safe + +Type: `string` + +The heuristic level to use for filtering out explicit content using [SafeSearch](https://en.wikipedia.org/wiki/SafeSearch). E.g. `off` or `high`. + ## Set up Google Custom Search Engine Google deprecated their public Google Images API, so to search for images you need to sign up for Google Custom Search Engine. diff --git a/test.js b/test.js index a4aad7c..95c2993 100644 --- a/test.js +++ b/test.js @@ -6,6 +6,36 @@ const test = require('ava'); const ImagesClient = require('./'); +test('no query', async t => { + const client = testClient('id', 'api'); + + const error = t.throws(() => { + client.search(''); + }, TypeError); + + t.is(error.message, 'Expected a query'); +}); + +test('no results', async t => { + const client = testClient('id', 'api'); + const server = testServer(); + + const query = qs.stringify({ + q: 'somethingmadeup', + searchType: 'image', + cx: 'id', + key: 'api' + }); + + server.on('/customsearch/v1?' + query, (req, res) => { + res.end(); + server.close(); + }); + + const images = await client.search('somethingmadeup'); + t.deepEqual(images, []); +}); + test('query', async t => { const client = testClient('id', 'api'); const server = testServer(); @@ -74,6 +104,102 @@ test('size option', async t => { t.deepEqual(images, fakeImages()); }); +test('type option', async t => { + const client = testClient('id', 'api'); + const server = testServer(); + + const query = qs.stringify({ + q: 'steve+angello', + searchType: 'image', + cx: 'id', + key: 'api', + imgType: 'clipart' + }); + + server.on('/customsearch/v1?' + query, (req, res) => { + res.end(fakeResponse()); + server.close(); + }); + + const images = await client.search('steve angello', { + type: 'clipart' + }); + + t.deepEqual(images, fakeImages()); +}); + +test('dominantColor option', async t => { + const client = testClient('id', 'api'); + const server = testServer(); + + const query = qs.stringify({ + q: 'steve+angello', + searchType: 'image', + cx: 'id', + key: 'api', + imgDominantColor: 'green' + }); + + server.on('/customsearch/v1?' + query, (req, res) => { + res.end(fakeResponse()); + server.close(); + }); + + const images = await client.search('steve angello', { + dominantColor: 'green' + }); + + t.deepEqual(images, fakeImages()); +}); + +test('colorType option', async t => { + const client = testClient('id', 'api'); + const server = testServer(); + + const query = qs.stringify({ + q: 'steve+angello', + searchType: 'image', + cx: 'id', + key: 'api', + imgColorType: 'gray' + }); + + server.on('/customsearch/v1?' + query, (req, res) => { + res.end(fakeResponse()); + server.close(); + }); + + const images = await client.search('steve angello', { + colorType: 'gray' + }); + + t.deepEqual(images, fakeImages()); +}); + +test('safe option', async t => { + const client = testClient('id', 'api'); + const server = testServer(); + + const query = qs.stringify({ + q: 'steve+angello', + searchType: 'image', + cx: 'id', + key: 'api', + safe: 'medium' + }); + + server.on('/customsearch/v1?' + query, (req, res) => { + res.end(fakeResponse()); + server.close(); + }); + + const images = await client.search('steve angello', { + safe: 'medium' + }); + + t.deepEqual(images, fakeImages()); +}); + function testClient(id, apiKey) { const client = new ImagesClient(id, apiKey); client.endpoint = 'http://localhost:9999';