> Searlo API Docs — Image Search
> Source: https://searlo.tech/docs#search-images
> Full docs: https://searlo.tech/docs/full.md

# Image Search

Search for images with thumbnails and source URLs.

### Endpoint

```
GET /search/images
```

**Credits:** 1 per request

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | Search query (1–500 chars) |
| `limit` | number | No | Results per page (1–10, default: 10) |
| `page` | number | No | Page number (default: 1). Google serves about 200 images per query: at `limit` 10 the last page is 21 |
| `size` | string | No | Minimum size: `icon`, `small`, `medium`, `large`, `xlarge`, `xxlarge` or `huge` |
| `imgSize` | string | No | Another name for `size` |
| `imgType` | string | No | Kind of image: `photo`, `face`, `clipart`, `lineart`, `stock` or `animated` |
| `imgColorType` | string | No | Colour treatment: `color`, `gray`, `mono` or `trans` (transparent background) |
| `imgDominantColor` | string | No | Dominant colour: `black`, `blue`, `brown`, `gray`, `green`, `orange`, `pink`, `purple`, `red`, `teal`, `white` or `yellow` |
| `gl` | string | No | Country code, max 5 chars (e.g. `us`) |
| `hl` | string | No | Interface language code, max 5 chars (e.g. `en`) |
| `cache` | boolean | No | `false` skips the cached copy and searches now. Same credits (default: `true`) |

The four filters take effect and combine: `size` (or `imgSize`), `imgType`, `imgColorType` and `imgDominantColor` each narrow the results, and the ones applied are echoed in `searchParameters`. A value outside the lists above returns `400` `VALIDATION_ERROR`. A page past the last one Google serves (`(page - 1) * limit` above 200) returns `400` `VALIDATION_ERROR` that names the last page; it is answered at once and is not charged.

### Response

```json
{
  "searchParameters": { "q": "sunset", "type": "images", "gl": "us", "num": 10, "page": 1, "imgSize": "large", "imgType": "photo" },
  "page": 1,
  "nextPage": 2,
  "previousPage": null,
  "totalResults": 50000,
  "searchTime": 0.35,
  "images": [
    {
      "position": 1,
      "title": "Beautiful Sunset",
      "imageUrl": "https://example.com/sunset.jpg",
      "width": 1920,
      "height": 1080,
      "thumbnailUrl": "https://example.com/thumb.jpg",
      "thumbnailWidth": 300,
      "thumbnailHeight": 168,
      "link": "https://example.com/gallery",
      "sourceUrl": "https://example.com/gallery",
      "source": "example.com",
      "domain": "example.com",
      "format": "image/jpeg",
      "imageId": "ANd9GcQexample"
    }
  ],
  "credits": 1
}
```

- `imageUrl` is the image itself, with its size in pixels in `width` and `height`. `thumbnailUrl` is Google's thumbnail, with its own `thumbnailWidth` and `thumbnailHeight`.
- `link` and `sourceUrl` are the page the image is on (`sourceUrl` falls back to the image URL when Google names no page). `source` and `domain` name that page's site.
- `format` is the image's MIME type, and `imageId` Google's id for it. A field Google does not give comes back `null`.

## Code Examples

### cURL

```bash
curl "https://api.searlo.tech/api/v1/search/images?q=sunset&limit=10&size=large" \
  -H "x-api-key: sk_your_api_key"

# Filters combine: orange-dominant photos
curl "https://api.searlo.tech/api/v1/search/images?q=sunset&imgType=photo&imgDominantColor=orange" \
  -H "x-api-key: sk_your_api_key"
```

### JavaScript

```javascript
async function imageSearch(query, options = {}) {
  const params = new URLSearchParams({
    q: query,
    limit: options.limit || 10,
    ...options
  });

  const res = await fetch(
    `https://api.searlo.tech/api/v1/search/images?${params}`,
    { headers: { "x-api-key": process.env.SEARLO_API_KEY } }
  );

  return res.json();
}

const result = await imageSearch("sunset", { size: "large", limit: 10 });
result.images.forEach(img => console.log(img.title, img.imageUrl, `${img.width}x${img.height}`, img.sourceUrl));
```

### Python

```python
import os
import requests

def image_search(query, limit=10, size=None):
    params = {"q": query, "limit": limit}
    if size:
        params["size"] = size

    response = requests.get(
        "https://api.searlo.tech/api/v1/search/images",
        params=params,
        headers={"x-api-key": os.environ["SEARLO_API_KEY"]}
    )
    return response.json()

results = image_search("sunset", size="large")
for img in results["images"]:
    print(img["title"], img["imageUrl"])
```


---
*From https://searlo.tech/docs — see full docs at https://searlo.tech/docs/full.md*