Search images using Google Custom Search Engine API
Last updated 3 years ago by vdemedes .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install google-images 
SYNC missed versions from official npm registry.

google-images Build Status

Search images using Google Custom Search Engine API.


$ npm install --save google-images


Note: You'll need to set up your own Google Custom Search Engine to execute queries.

const GoogleImages = require('google-images');

const client = new GoogleImages('CSE ID', 'API KEY');'Steve Angello')
	.then(images => {
			"url": "",
			"type": "image/jpeg",
			"width": 1024,
			"height": 768,
			"size": 102451,
			"thumbnail": {
				"url": "",
				"width": 512,
				"height": 512

// paginate results'Steve Angello', {page: 2});

// search for certain size'Steve Angello', {size: 'large'});


Please see Google's API documentation 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)


Type: string

The identifier for a Custom Search Engine to use.


Type: string

The credentials for accessing Google's API.


.search(query, option)

Perform an image search for query.


Type: string

The search terms to use for finding images. Identical to those you would use in a web search.


Type: object


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.


Type: string

The size of images to search. E.g. medium or xxlarge.


Type: string

The category of images to search. E.g. face or photo.


Type: string

The dominant color to search for. E.g. yellow or purple.


Type: string

The category of color spectrums to search. E.g. gray or color.


Type: string

The heuristic level to use for filtering out explicit content using 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. Here are the steps you need to do:

1. Create a Google Custom Search Engine

You can do this here:

Do not specify any sites to search but instead use the "Restrict Pages using Types" under the "Advanced options". For the most inclusive set, use the Schema: Thing. Make a note of the CSE ID.

2. Enable Image Search

In your search engine settings, enable "Image search":

3. Set up a Google Custom Search Engine API

Register a new app and enable Google Custom Search Engine API here: Google Developers Console. Make a note of the API key.


MIT © Vadim Demedes

Current Tags

  • 2.1.0                                ...           latest (3 years ago)

13 Versions

  • 2.1.0                                ...           3 years ago
  • 2.0.1                                ...           3 years ago
  • 2.0.0                                ...           4 years ago
  • 1.0.0                                ...           5 years ago
  • 0.1.4                                ...           5 years ago
  • 0.1.3                                ...           5 years ago
  • 0.1.2                                ...           5 years ago
  • 0.1.0                                ...           8 years ago
  • 0.0.5                                ...           8 years ago
  • 0.0.4                                ...           9 years ago
  • 0.0.3                                ...           9 years ago
  • 0.0.2                                ...           9 years ago
  • 0.0.1                                ...           9 years ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 4
Dependencies (1)
Dev Dependencies (3)

Copyright 2014 - 2016 © |