Add more search options (#21)

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);
 	}
 

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`<br>
+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.

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';