{"id":13586049,"url":"https://github.com/arrrlo/Google-Images-Search","last_synced_at":"2025-04-07T14:33:19.795Z","repository":{"id":38431999,"uuid":"50135427","full_name":"arrrlo/Google-Images-Search","owner":"arrrlo","description":"[PYTHON] Search for image using Google Custom Search API and resize \u0026 crop afterwards","archived":false,"fork":false,"pushed_at":"2024-03-05T14:27:14.000Z","size":256,"stargazers_count":170,"open_issues_count":11,"forks_count":32,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2024-04-14T12:21:50.068Z","etag":null,"topics":["api","crop","download","google","google-images","image","search"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arrrlo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-01-21T20:42:50.000Z","updated_at":"2024-06-19T00:25:27.207Z","dependencies_parsed_at":"2024-06-19T00:25:23.590Z","dependency_job_id":"ce2bd555-0bb0-46f1-98b1-208a3608c2be","html_url":"https://github.com/arrrlo/Google-Images-Search","commit_stats":{"total_commits":168,"total_committers":16,"mean_commits":10.5,"dds":0.3928571428571429,"last_synced_commit":"6dfce418e8738a273a7f2ac165ee50501ee1b08d"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arrrlo%2FGoogle-Images-Search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arrrlo%2FGoogle-Images-Search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arrrlo%2FGoogle-Images-Search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arrrlo%2FGoogle-Images-Search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arrrlo","download_url":"https://codeload.github.com/arrrlo/Google-Images-Search/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223285017,"owners_count":17119821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","crop","download","google","google-images","image","search"],"created_at":"2024-08-01T15:05:17.826Z","updated_at":"2024-11-06T04:30:39.347Z","avatar_url":"https://github.com/arrrlo.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"![Google Images Search](google.jpeg)\n\n# Google Images Search\n\n[![PyPI version](https://badge.fury.io/py/Google-Images-Search.svg)](https://badge.fury.io/py/Google-Images-Search)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/b3d5259c67ca48a7bfe844b9721b6c19)](https://www.codacy.com/app/arrrlo/Google-Images-Search?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=arrrlo/Google-Images-Search\u0026amp;utm_campaign=Badge_Grade)\n\n![GitHub issues](https://img.shields.io/github/issues/arrrlo/Google-Images-Search.svg)\n![GitHub closed issues](https://img.shields.io/github/issues-closed/arrrlo/Google-Images-Search.svg)\n![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/arrrlo/Google-Images-Search.svg)\n\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/Google-Images-Search.svg)\n![GitHub](https://img.shields.io/github/license/arrrlo/Google-Images-Search.svg?color=blue)\n![GitHub last commit](https://img.shields.io/github/last-commit/arrrlo/Google-Images-Search.svg?color=blue)\n\n## [Installation](#installation)\n\nTo be able to use this library, you need to enable Google Custom Search API, generate API key credentials and set a project:\n\n-   Visit [https://console.developers.google.com](https://console.developers.google.com) and create a project.\n\n-   Visit [https://console.developers.google.com/apis/library/customsearch.googleapis.com](https://console.developers.google.com/apis/library/customsearch.googleapis.com) and enable \"Custom Search API\" for your project.\n\n-   Visit [https://console.developers.google.com/apis/credentials](https://console.developers.google.com/apis/credentials) and generate API key credentials for your project.\n\n-   Visit [https://cse.google.com/cse/all](https://cse.google.com/cse/all) 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\".  \n\nAfter setting up your Google developers account and project you should have been provided with developers API key and project CX.\n\nInstall package from pypi.org:  \n\n```bash\n\u003e pip install Google-Images-Search\n```\n\n## [CLI usage](#cli-usage)\n\n```bash\n# without environment variables:\n\n\u003e gimages -k __your_dev_api_key__ -c __your_project_cx__ search -q puppies\n```\n\n```bash\n# with environment variables:\n\n\u003e export GCS_DEVELOPER_KEY=__your_dev_api_key__\n\u003e export GCS_CX=__your_project_cx__\n\u003e\n\u003e gimages search -q puppies\n```\n\n```bash\n# search only (no download and resize):\n\n\u003e gimages search -q puppies\n```\n\n```bash\n# search and download only (no resize):\n\n\u003e gimages search -q puppies -d /path/on/your/drive/where/images/should/be/downloaded\n```\n\n```bash\n# search, download and resize:\n\n\u003e gimages search -q puppies -d /path/ -w 500 -h 500\n```\n\n## [Programmatic usage](#programmatic-usage)\n\n```python\nfrom google_images_search import GoogleImagesSearch\n\n# you can provide API key and CX using arguments,\n# or you can set environment variables: GCS_DEVELOPER_KEY, GCS_CX\ngis = GoogleImagesSearch('your_dev_api_key', 'your_project_cx')\n\n# define search params\n# option for commonly used search param are shown below for easy reference.\n# For param marked with '##':\n#   - Multiselect is currently not feasible. Choose ONE option only\n#   - This param can also be omitted from _search_params if you do not wish to define any value\n_search_params = {\n    'q': '...',\n    'num': 10,\n    'fileType': 'jpg|gif|png',\n    'rights': 'cc_publicdomain|cc_attribute|cc_sharealike|cc_noncommercial|cc_nonderived',\n    'safe': 'active|high|medium|off|safeUndefined', ##\n    'imgType': 'clipart|face|lineart|stock|photo|animated|imgTypeUndefined', ##\n    'imgSize': 'huge|icon|large|medium|small|xlarge|xxlarge|imgSizeUndefined', ##\n    'imgDominantColor': 'black|blue|brown|gray|green|orange|pink|purple|red|teal|white|yellow|imgDominantColorUndefined', ##\n    'imgColorType': 'color|gray|mono|trans|imgColorTypeUndefined' ##\n}\n\n# this will only search for images:\ngis.search(search_params=_search_params)\n\n# this will search and download:\ngis.search(search_params=_search_params, path_to_dir='/path/')\n\n# this will search, download and resize:\ngis.search(search_params=_search_params, path_to_dir='/path/', width=500, height=500)\n\n# search first, then download and resize afterwards:\ngis.search(search_params=_search_params)\nfor image in gis.results():\n    image.url  # image direct url\n    image.referrer_url  # image referrer url (source) \n    \n    image.download('/path/')  # download image\n    image.resize(500, 500)  # resize downloaded image\n\n    image.path  # downloaded local file path\n```\n\n## [Custom file name](#custom-file-name)\n\nSometimes you would want to save images with file name of your choice.\n\n```python\nfrom google_images_search import GoogleImagesSearch\n\ngis = GoogleImagesSearch('your_dev_api_key', 'your_project_cx')\n\n_search_params = { ... }\n\ngis.search(search_params=_search_params, path_to_dir='...', \n           custom_image_name='my_image')\n```\n\n## [Paging](#paging)\n\nGoogle's API limit is 10 images per request.  \nThat means if you want 123 images, it will be divided internally into 13 requests.  \nKeep in mind that getting 123 images will take a bit more time if the image validation is enabled.\n\n```python\nfrom google_images_search import GoogleImagesSearch\n\ngis = GoogleImagesSearch('your_dev_api_key', 'your_project_cx')\n_search_params = {\n    'q': '...',\n    'num': 123,\n}\n\n# get first 123 images:\ngis.search(search_params=_search_params)\n\n# take next 123 images from Google images search:\ngis.next_page()\nfor image in gis.results():\n    ...\n```\n\n## [Image validation](#image-validation)\n\nEvery image URL is validated by default.  \nThat means that every image URL will be checked if the headers can be fetched and validated.  \nWith that you don't need to wary about which image URL is actually downloadable or not.  \nThe downside is the time needed to validate.  \nIf you prefer, you can turn it off.\n\n```python\nfrom google_images_search import GoogleImagesSearch\n\n# turn the validation off with \"validate_images\" agrument\ngis = GoogleImagesSearch('your_dev_api_key', 'your_project_cx', validate_images=False)\n```\n\n## [Inserting custom progressbar function](#progressbar)\n\nBy default, progressbar is not enabled.  \nOnly in CLI progressbar is enabled by default using [Curses library](https://docs.python.org/3/howto/curses.html).  \nIn a programmatic mode it can be enabled in two ways:  \n- using contextual mode (Curses)  \n- using your custom progressbar function  \n\n```python\nfrom google_images_search import GoogleImagesSearch\n\n# using your custom progressbar function\ndef my_progressbar(url, progress):\n    print(url + ' ' + progress + '%')\ngis = GoogleImagesSearch(\n    'your_dev_api_key', 'your_project_cx', progressbar_fn=my_progressbar\n)\n_search_params = {...}\ngis.search(search_params=_search_params)\n\n# using contextual mode (Curses)\nwith GoogleImagesSearch('your_dev_api_key', 'your_project_cx') as gis:\n    _search_params = {...}\n    gis.search(search_params=_search_params)\n...\n```\n\n## [Saving to a BytesIO object](#bytes-io)\n\n```python\nfrom google_images_search import GoogleImagesSearch\nfrom io import BytesIO\nfrom PIL import Image\n\n# in this case we're using PIL to keep the BytesIO as an image object\n# that way we don't have to wait for disk save / write times\n# the image is simply kept in memory\n# this example should display 3 pictures of puppies!\n\ngis = GoogleImagesSearch('your_dev_api_key', 'your_project_cx')\n\nmy_bytes_io = BytesIO()\n\ngis.search({'q': 'puppies', 'num': 3})\nfor image in gis.results():\n    # here we tell the BytesIO object to go back to address 0\n    my_bytes_io.seek(0)\n\n    # take raw image data\n    raw_image_data = image.get_raw_data()\n\n    # this function writes the raw image data to the object\n    image.copy_to(my_bytes_io, raw_image_data)\n\n    # or without the raw data which will be automatically taken\n    # inside the copy_to() method\n    image.copy_to(my_bytes_io)\n\n    # we go back to address 0 again so PIL can read it from start to finish\n    my_bytes_io.seek(0)\n\n    # create a temporary image object\n    temp_img = Image.open(my_bytes_io)\n    \n    # show it in the default system photo viewer\n    temp_img.show()\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farrrlo%2FGoogle-Images-Search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farrrlo%2FGoogle-Images-Search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farrrlo%2FGoogle-Images-Search/lists"}