# Google Images

Search Google Images to retrieve image results in JSON format.

## Endpoint

```
GET /v1/image/{query}
```

## Description

The Google Images Search endpoint returns image results for a query, each with a
thumbnail set, the page the image was found on, and the original image's URL and
dimensions.

Results arrive in the **`image_results`** array. The `results` array that the other
search endpoints populate is always empty here — see [Response](#response) below.

## Authentication

All requests require authentication using the `X-Api-Key` header. See the [Authentication guide](/docs/guides/authentication) for more details.

## Path Parameters

### `query` (required)

**Type:** `string`

The search terms, packed into the path. Both the `q=`-prefixed form and a bare term
are accepted and return the same results:

**Examples:**
- `q=vintage+bicycle`
- `vintage+bicycle`

Unlike [Google Search](/docs/resources/google-search), this endpoint takes only the
search terms. Every call returns up to 20 images, and there is no pagination
parameter.

**Prefer the `q=` form if you pass anything else.** Additional Google parameters are
dropped only when the path is a query string this endpoint can parse, which means it
needs the `q=` key: `q=origami+crane&num=5` searches for *origami crane* and ignores
`num`. Appended to a bare term, the same parameter becomes part of the search —
`origami+crane&num=5` looks for the literal text `origami crane&num=5` and returns
unrelated images rather than an error.

## Request Headers

### `X-Proxy-Location` (optional)

**Type:** `string`

Specify the proxy location for the search. This determines the geographic location from which the search is performed.

**Allowed values:**
- `EU` - European Union
- `CA` - Canada
- `US` - United States
- `IE` - Ireland
- `GB` - United Kingdom
- `FR` - France
- `DE` - Germany
- `SE` - Sweden
- `IN` - India
- `JP` - Japan
- `KR` - South Korea
- `SG` - Singapore
- `AU` - Australia
- `BR` - Brazil

### `X-User-Agent` (optional)

**Type:** `string`

Specify the device type for the search. Defaults to `desktop` if not provided.

**Allowed values:**
- `desktop` - Desktop browser (default)
- `mobile` - Mobile device

## Request Example

### Using cURL

```bash
curl --request GET \
  --url 'https://api.serply.io/v1/image/q=vintage+bicycle' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'X-Proxy-Location: US' \
  --header 'X-User-Agent: desktop'
```

### Using JavaScript/Node.js

```javascript
const response = await fetch('https://api.serply.io/v1/image/q=vintage+bicycle', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Proxy-Location': 'US',
    'X-User-Agent': 'desktop'
  }
});
const data = await response.json();
console.log(data.image_results);
```

### Using Python

```python
import requests

headers = {
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Proxy-Location': 'US',
    'X-User-Agent': 'desktop'
}

response = requests.get(
    'https://api.serply.io/v1/image/q=vintage+bicycle',
    headers=headers
)
data = response.json()
print(data['image_results'])
```

## Response

The API returns a JSON object whose `image_results` array carries the images. The
other SERP-feature arrays are present for consistency with the rest of the API and
are empty on this endpoint.

### Response Structure

```json
{
  "image_results": [
    {
      "image": {
        "src": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSpyW8...&s",
        "alt": "Ladies Classic 7-Speed Vintage Bike Red - Reid Bikes"
      },
      "link": {
        "href": "https://shop.reidbikes.com/products/ladies-classic-7-speed-vintage-bike-red",
        "title": "Ladies Classic 7-Speed Vintage Bike Red - Reid Bikes",
        "domain": "shop.reidbikes.com"
      },
      "original_image": {
        "src": "http://shop.reidbikes.com/cdn/shop/files/ladies-classic-vintage-bike-red.png",
        "width": "1170",
        "height": "764",
        "file_format": "image/png"
      },
      "thumbnails": {
        "small": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSpyW8...&s",
        "medium": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRn7d-...&s",
        "large": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQZilx...&s"
      }
    }
  ],
  "results": [],
  "ads": [],
  "ads_count": 0,
  "answers": [],
  "shopping_ads": [],
  "places": [],
  "related_searches": [],
  "carousel": [],
  "company": {},
  "total": 20,
  "ts": 1.27,
  "device_region": "",
  "device_type": null,
  "query": "q=vintage+bicycle"
}
```

### Response Fields

- **`image_results`** (array): An array of image result objects
  - **`image`** (object): The result as shown on the results page
    - **`src`** (string): Thumbnail URL, served from Google's `encrypted-tbn0.gstatic.com` cache rather than the source site
    - **`alt`** (string): Alt text, generally the source page's title
  - **`link`** (object): Where the image was found
    - **`href`** (string): URL of the page hosting the image
    - **`title`** (string): Title of that page
    - **`domain`** (string): Hostname of that page
  - **`original_image`** (object): The full-size image on the source site
    - **`src`** (string): Direct URL to the original image. Served by the source site, so it may be `http://`, may be hotlink-protected, and may 404 independently of the search result
    - **`width`**, **`height`** (string): Pixel dimensions of the original, as strings
    - **`file_format`** (string): MIME type, e.g. `image/jpeg`, `image/png`, `image/webp`, `image/svg+xml`. Google does not always report the subtype, in which case this is the bare string `image/` — treat it as unknown rather than parsing it, and fall back to the extension on `src` if you need the real format
  - **`thumbnails`** (object): Three cached preview sizes — **`small`**, **`medium`**, **`large`** (strings). All are Google-hosted and safe to hotlink
- **`results`** (array): Always empty on this endpoint. Image results are in `image_results`
- **`total`** (number): Number of images returned, up to 20
- **`ts`** (number): Time in seconds the request took to complete
- **`device_region`** (string): Proxy region used, if specified via `X-Proxy-Location`
- **`device_type`** (string | null): Device type used for the search
- **`query`** (string): The path segment as sent, echoed verbatim — so a request for `q=vintage+bicycle` reports `"q=vintage+bicycle"`, not `"vintage bicycle"`
- **`ads`**, **`answers`**, **`shopping_ads`**, **`places`**, **`related_searches`**, **`carousel`** (arrays), **`company`** (object), **`ads_count`** (number): Present for consistency with the other search endpoints; empty here

## Status Codes

- **200 OK** - Successful response
- **404 Not Found** - The requested resource was not found
- **422 Unprocessable Entity** - The request was well-formed but contains semantic errors
- **429 Too Many Requests** - Rate limit exceeded

## Error Responses

See the [Errors guide](/docs/guides/errors) for information on error response formats.