Skip to content

Google Images

Overview

Method Endpoint Version Description
POST /api/v1/open/search v1 Google Search API endpoint for retrieving search results

Request Headers

Header Type Required Description
Content-Type string Yes Must be set to application/json
Accept string No Response format (defaults to application/json)

Authentication

API Key Authentication

  • Pass the API key as a request parameter: api_key=your_api_key
  • Example: "api_key": "your_api_key_here"

HTTP Status Codes

Code Status Description Retry
200 OK Request successful No

Response Codes

Code Description Retry
200 Request successful No
400100 Unsupported search engine No
400200 The search service is temporarily unavailable. Please try again later No
400300 ForUserQuery contains prohibited content No
400400 No results found, please adjust keywords and try again No
400500 Authorization failed, please check your API credentials No
400600 The request frequency is too high, please try again later No
400700 You have reached the daily search limit No
400710 Insufficient Balance No

Request Example

1
2
3
4
5
6
7
8
curl -X POST "https://domain/api/v1/open/search" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "coffee",
    "engine": "google_images",
    "html": "0",
    "api_key": "your_api_key_here"
}'

Request Parameters

Parameter Type Required Description Default
api_key string Yes API key for authentication
engine string Yes Search engine type, currently engine value is google_images google
q string Yes Search query, supports regular Google search syntax (like inurl:, site:, intitle:) and advanced search parameters
cr string No Parameter defines one or multiple countries to limit the search to. It uses country{two-letter upper-case country code} to specify countries and | as a delimiter. (e.g., countryFR|countryDE will only search French and German pages). Head to the Google cr countries page for a full list of supported countries.
google_domain string No Google domain, defaults to google.com google.com
date string No Time range filter: h-last hour, d-last day, w-last week, m-last month, y-last year
ijn string No Parameter defines the page number for Google Images. There are 100 images per page. This parameter is equivalent to start (offset) = ijn * 100.
start_date string No Parameter defines the start date of time period you want to limit the search to. This parameter can't be used with time parameters. start_date with blank end_date produces date range FROM start_date TO today. This parameter overrides cdr and cd_min components of tbs parameter. The parameter format is M/D/YYYY.
end_date string No Parameter defines the end date of time period you want to limit the search to. This parameter can't be used with time parameters. end_date with blank start_date produces date range BEFORE end_date. This parameter overrides cdr and cd_max components of tbs parameter. The parameter format is M/D/YYYY.
end_date string No Parameter defines the end date of time period you want to limit the search to. This parameter can't be used with time parameters. end_date with blank start_date produces date range BEFORE end_date. This parameter overrides cdr and cd_max components of tbs parameter.
chips string No Parameter enables to filter image search. It's a string provided by Google as suggested search, like: red apple. Chips are provided under the section: suggested_searches when ijn = 0. Both chips and serpapi_link values are provided for each suggested search
tbs string No (to be searched) parameter defines advanced search parameters that aren't possible in the regular query field. (e.g., advanced search for patents, dates, news, videos, images, apps, or text contents).
imgar string No Parameter defines the set aspect ratio of images. Options: s - Square, t - Tall, w - Wide, xw - Panoramic
imgsz string No Parameter defines the size of images. Options: l - Large, m - Medium, i - Icon, qsvga - Larger than 400×300, vga - Larger than 640×480, svga - Larger than 800×600, xga - Larger than 1024×768, 2mp - Larger than 2 MP, 4mp - Larger than 4 MP, 6mp - Larger than 6 MP, 8mp - Larger than 8 MP, 10mp - Larger than 10 MP, 12mp - Larger than 12 MP, 15mp - Larger than 15 MP, 20mp - Larger than 20 MP, 40mp - Larger than 40 MP, 70mp - Larger than 70 MP
image_color string No Parameter defines the color of images. Options: bw - Black and white, trans - Transparent, red - Red, orange - Orange, yellow - Yellow, green - Green, teal - Teal, blue - Blue, purple - Purple, pink - Pink, white - White, gray - Gray, black - Black, brown - Brown. This parameter overrides ic and isc components of tbs parameter
image_type string No Parameter defines the type of images. Options: face - Face, photo - Photo, clipart - Clip art, lineart - Line drawing, animated - Animated. This parameter overrides itp component of tbs parameter
licenses string No Parameter defines the scope of licenses of images. Options: f - Free to use or share, fc - Free to use or share, even commercially, fm - Free to use, share or modify, fmc - Free to use, share or modify, even commercially, cl - Creative Commons licenses, ol - Commercial and other licenses. This parameter overrides sur component of tbs parameter
safe string No Parameter defines the level of filtering for adult content. It can be set to active or off, by default Google will blur explicit content
nfpr string No Parameter defines if the filters for 'Similar Results' and 'Omitted Results' are on or off. It can be set to 1 (default) to enable these filters, or 0 to disable these filters. 1 or 0 0
filter string No Parameter defines the exclusion of results from an auto-corrected query when the original query is spelled wrong. It can be set to 1 to exclude these results, or 0 to include them (default). Note that this parameter may not prevent Google from returning results for an auto-corrected query if no other results are available. 1 or 0 1
html string No Whether to return HTML format, 1-yes, 0-no 0

Response Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
{
    "code": 200,
    "data": {
        "search_metadata": {
            "raw_html_file": "oss_html",
            "total_time_taken": 2.032416469,
            "id": "1985902431212408832",
            "json_endpoint": "oss_json",
            "created_at": "2025-10-29 08:53:31",
            "processed_at": "2025-10-29 08:53:33",
            "google_url": "https://www.google.com/search?q=coffee&udm=2",
            "status": "Success"
        },
        "search_information": {
            "organic_results_state": "",
            "time_taken_displayed": 0.06,
            "total_results": ""
        },
        "search_parameters": {
            "engine": "google_images",
            "html": "0",
            "google_domain": "www.google.com",
            "q": "coffee",
            "tbm": "isch"
        },
        "related_searches": [
            {
                "query": "clip art coffee",
                "link": "https://www.google.com/search?v=552fb68e3d08662a&gl=us&hl=en&udm=2&q=clip+art+coffee&stick=H4sIAAAAAAAAA FhUopCcn5aWmgoAOTTt0BIAAAAA&source=univ&sa=X&ved=2ahUKEwi28pHWxqWQ Q_wK_wQrNwCegQILRAA",
                "highlighted_words": "clip art"
            }
        ],
        "suggested_searches": [
            {
                "name": "Cafe",
                "link": "https://www.google.com/search?esv=552fb68e3d08662a&gl=us&hl=en&q=cafe+coffee&uds=AOm0WdE2fekQnsyfYEw8JPYozOKzryiE-s2AOejeW7Z-tgPLjl_4J4uczmoY_f8MYUk3PVXEFE-ZW6B3tyq_BA0eRxNCG883SZGtfrpWkSi46Fxfr9TuilLBmL6CpOnneO3SaYoufqOf9qK8TuGvSAt77c0n=2&sa=X&ved=2ahUKEwi28pHWxqWQAxEU-7jgGHQ_wK_wQxKsJKAB6BAgPEAE&ictx=0",
                "uds": "AOm0WdE2fekQnsyfYEw8JPYozOKzryiE-s2AOejeW7Z-Ljl_4J4uczmoY_f8MYUk3PVXEFE-ZW6B3tyq_BA0eRxNCG883SZGtfrpWkSi46Fxfr9TuilLBmL6CpOnneO3SaYoufqOf9qK8TuGvSAt77c0",
                "q": "cafe+coffee"
            }
        ],
        "images_results": [
            {
                "position": 1,
                "thumbnail": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAAAQABAAAD/2wCEAAkGBxM",
                "source": "Wikipedia, the free encyclopedia",
                "title": "Coffee - Wikipedia",
                "link": "https://en.wikipedia.org/wiki/Coffee",
                "original": "https://upload.wikimedia.org/wikipedia/commons/thumb/e/e4/Latte_and_dark_co/1200px-Latte_and_dark_coffee.jpg",
                "original_width": 750,
                "original_height": 1200
            }
        ],
        "pagination": {
            "next": "",
        }
    },
    "msg": "string",
    "reqId": "string"
}

Complete Response Parameters Overview

search_metadata

object Contains metadata about the search execution

Parameter Type Description Applicable Terminal
id string Unique identifier for the search request
json_endpoint string Provide an interface endpoint for searching related JSON data, through which JSON-formatted search data can be obtained
created_at string The timestamp when the search request was created, recording the time when the search was initiated
processed_at string The timestamp when the search results were processed and became available for return, recording the time point from processing to completion of the search
google_url string The Google search URL, which contains the search keyword "coffee" along with language parameters (hl=en for English), regional parameters (gl=us for the United States), and other search parameters, used to redirect to the corresponding Google search page
status string Status of the search execution (e.g., Success)
raw_html_file string Identifier for the original HTML file
total_time_taken number The total time spent on the entire search process (including request sending, result parsing, and other stages)

search_information

object Contains information about the search results

Parameter Type Description Applicable Terminal
organic_results_state string State of organic results
time_taken_displayed number TDisplay time (i.e., the time spent on displaying the search results)
total_results string Total results count (the total number of results returned by this search)

search_parameters

object Contains the parameters used for the search

Parameter Type Description Applicable Terminal
q string Keywords used for this query
engine string Search engine used for this query (e.g., google_web)
lr string No Parameter defines one or multiple languages to limit the search to. It uses lang_{two-letter language code} to specify languages and | as a delimiter. (e.g., lang_fr|lang_de will only search French and German pages). Head to the Google lr languages page for a full list of supported languages.
html string When HTML=0, returns JSON; when HTML=1, returns HTML; when HTML=2, returns both JSON and HTML
google_domain string Specifies the corresponding Google domain (e.g., google.com, etc., used to distinguish Google services in different regions/locales)
tbm string isch

object[] Provide other search terms related to the keyword to help users expand their search scope and discover relevant content.

Parameter Type Description Applicable Terminal
query string Related search query keywords, associated content terms for the search
link string Google search results page link, which can redirect to the search results page for that keyword.
highlighted_words string The core terms highlighted in the search results, emphasizing the most relevant key content related to the current search topic

suggested_searches

object[] Recommend potentially interesting search terms to help users quickly locate more precise image content.

Parameter Type Description Applicable Terminal
name string The name of the recommended search / keywords, which are the suggested terms for the user to sear
link string The Google search results page link for the recommended search
uds string The identifier used internally by Google (for tracking search sessions, personalization logic, and other scenarios, serving as an internal platform identifier)
q string The corresponding query parameter for recommended searches

images_results

object[] Recommended search terms / keywords, which are the suggested search queries for users.

Parameter Type Description Applicable Terminal
position number The ranking of this result in the images search results
thumbnail string Thumbnail link (address of a small preview image related to the content, used for quick visual identification, including data:image/png;base64)
source string Source platform / website of the image
title string Title of the content associated with the image
link string Destination webpage link after clicking the image
original string Original image file URL
original_width number Original image width (in pixels)
original_height number Original image height (in pixels)

pagination

object (Pagination) related fields used to describe pagination navigation information for search results

Parameter Type Description Applicable Terminal
next string URL for the next page of search results