Skip to main content

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

Project description

Google Images Search

Google Images Search

PyPI version Codacy Badge

GitHub issues GitHub closed issues GitHub closed pull requests

PyPI - Python Version GitHub GitHub last commit


To be able to use this library, you need to enable Google Custom Search API, generate API key credentials and set a project:

After setting up your Google developers account and project you should have been provided with 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

# you can provide API key and CX using arguments,
# or you can set environment variables: GCS_DEVELOPER_KEY, GCS_CX
gis = GoogleImagesSearch('your_dev_api_key', 'your_project_cx')

# define search params
# option for commonly used search param are shown below for easy reference.
# For param marked with '##':
#   - Multiselect is currently not feasible. Choose ONE option only
#   - This param can also be omitted from _search_params if you do not wish to define any value
_search_params = {
    'q': '...',
    'num': 10,
    'fileType': 'jpg|gif|png',
    'rights': 'cc_publicdomain|cc_attribute|cc_sharealike|cc_noncommercial|cc_nonderived',
    'safe': 'active|high|medium|off|safeUndefined', ##
    'imgType': 'clipart|face|lineart|stock|photo|animated|imgTypeUndefined', ##
    'imgSize': 'huge|icon|large|medium|small|xlarge|xxlarge|imgSizeUndefined', ##
    'imgDominantColor': 'black|blue|brown|gray|green|orange|pink|purple|red|teal|white|yellow|imgDominantColorUndefined', ##
    'imgColorType': 'color|gray|mono|trans|imgColorTypeUndefined' ##

# 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():
    image.url  # image direct url
    image.referrer_url  # image referrer url (source) '/path/')  # download image
    image.resize(500, 500)  # resize downloaded image

    image.path  # downloaded local file path

Custom file name

Sometimes you would want to save images with file name of your choice.

from google_images_search import GoogleImagesSearch

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

_search_params = { ... }, path_to_dir='...', 


Google's API limit is 10 images per request.
That means if you want 123 images, it will be divided internally into 13 requests.
Keep in mind that getting 123 images will take a bit more time if the image validation is enabled.

from google_images_search import GoogleImagesSearch

gis = GoogleImagesSearch('your_dev_api_key', 'your_project_cx')
_search_params = {
    'q': '...',
    'num': 123,

# get first 123 images:

# take next 123 images from Google images search:
for image in gis.results():

Image validation

Every image URL is validated by default.
That means that every image URL will be checked if the headers can be fetched and validated.
With that you don't need to wary about which image URL is actually downloadable or not.
The downside is the time needed to validate.
If you prefer, you can turn it off.

from google_images_search import GoogleImagesSearch

# turn the validation off with "validate_images" agrument
gis = GoogleImagesSearch('your_dev_api_key', 'your_project_cx', validate_images=False)

Inserting custom progressbar function

By default, progressbar is not enabled.
Only in CLI progressbar is enabled by default using Curses library.
In a programmatic mode it can be enabled in two ways:

  • using contextual mode (Curses)
  • using your custom progressbar function
from google_images_search import GoogleImagesSearch

# using your custom progressbar function
def my_progressbar(url, progress):
    print(url + ' ' + progress + '%')
gis = GoogleImagesSearch(
    'your_dev_api_key', 'your_project_cx', progressbar_fn=my_progressbar
_search_params = {...}

# using contextual mode (Curses)
with GoogleImagesSearch('your_dev_api_key', 'your_project_cx') as gis:
    _search_params = {...}

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
# that 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.

Source Distribution

Google Images Search-1.4.6.tar.gz (10.9 kB view hashes)

Uploaded source

Built Distribution

Google_Images_Search-1.4.6-py2.py3-none-any.whl (12.6 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page