Skip to main content

Search for image using Google Custom Search API and resize & crop the image afterwords

Project description

Google Images Search

PyPI version Build Status Codacy Badge

GitHub issues GitHub closed issues GitHub closed pull requests

PyPI - Python Version GitHub GitHub last commit


Before you continue you need to setup your Google developers account and project:

  • Visit and among all of the Google APIs enable "Custom Search API" for your project.

  • Visit and in the web form where you create/edit your custom search engine enable "Image search" option and for "Sites to search" option select "Search the entire web but emphasize included sites".

After setting up you Google developers account and project you should have your developers API key and project CX.

Install package from

> pip install Google-Images-Search

CLI usage

# without environment variables:

> gimages -k __your_dev_api_key__ -c __your_project_cx__ search -q puppies
# with environment variables:

> export GCS_DEVELOPER_KEY=__your_dev_api_key__
> export GCS_CX=__your_project_cx__
> gimages search -q puppies
# search only (no download and resize):

> gimages search -q puppies
# search and download only (no resize):

> gimages search -q puppies -d /path/on/your/drive/where/images/should/be/downloaded
# search, download and resize:

> gimages search -q puppies -d /path/ -w 500 -h 500

Programmatic usage

from google_images_search import GoogleImagesSearch

# if you don't enter api key and cx, the package will try to search
# them from environment variables GCS_DEVELOPER_KEY and GCS_CX
gis = GoogleImagesSearch('your_dev_api_key', 'your_project_cx')

# example: GoogleImagesSearch('ABcDeFGhiJKLmnopqweRty5asdfghGfdSaS4abC', '012345678987654321012:abcde_fghij')

#define search params:
_search_params = {
    'q': '...',
    'num': 1-50,
    'safe': 'high|medium|off',
    'fileType': 'jpg|gif|png',
    'imgType': 'clipart|face|lineart|news|photo',
    'imgSize': 'huge|icon|large|medium|small|xlarge|xxlarge',
    'imgDominantColor': 'black|blue|brown|gray|green|pink|purple|teal|white|yellow'

# this will only search for images:

# this will search and download:, path_to_dir='/path/')

# this will search, download and resize:, path_to_dir='/path/', width=500, height=500)

# search first, then download and resize afterwards
for image in gis.results():'/path/')
    image.resize(500, 500)

Inserting custom progressbar function

from google_images_search import GoogleImagesSearch

def my_progressbar(url, progress):
    print(url + ' ' + progress + '%')

gis = GoogleImagesSearch(
    'your_dev_api_key', 'your_project_cx', progressbar_fn=my_progressbar


Saving to a BytesIO object

from google_images_search import GoogleImagesSearch
from io import BytesIO
from PIL import Image

# in this case we're using PIL to keep the BytesIO as an image object
# this way we don't have to wait for disk save / write times
# the image is simply kept in memory
# this example should display 3 pictures of puppies!

gis = GoogleImagesSearch('your_dev_api_key', 'your_project_cx')

my_bytes_io = BytesIO(){'q': 'puppies', 'num': 3})
for image in gis.results():
    # here we tell the BytesIO object to go back to address 0

    # take raw image data
    raw_image_data = image.get_raw_data()

    # this function writes the raw image data to the object
    image.copy_to(my_bytes_io, raw_image_data)

    # or without the raw data which will be automatically taken
    # inside the copy_to() method

    # we go back to address 0 again so PIL can read it from start to finish

    # create a temporary image object
    temp_img =

    # show it in the default system photo viewer

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for Google-Images-Search, version 1.0.1
Filename, size File type Python version Upload date Hashes
Filename, size Google_Images_Search-1.0.1-py2.py3-none-any.whl (9.5 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size Google Images Search-1.0.1.tar.gz (9.1 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page