# Image search

`GET` `/v1/images/search`

Find images from a large independent index of images.

**Base URL:** `https://api.search.brave.com/res`

## Authorization

| Name | Location | Type | Required | Constraints | Description |
|------|----------|------|----------|-------------|-------------|
| `x-subscription-token` | header | string | Yes |  | The subscription token that was generated for the product. |

## Query Parameters

| Name | Location | Type | Required | Constraints | Description |
|------|----------|------|----------|-------------|-------------|
| `q` | query | string | Yes |  | The user's search query term. Query can not be empty. Maximum of 400 characters and 50 words in the query. |
| `search_lang` | query | string | No | `ar`, `eu`, `bn`, `bg`, `ca`, `zh-hans`, `zh-hant`, `hr`, `cs`, `da`, `nl`, `en`, `en-gb`, `et`, `fi`, `fr`, `gl`, `de`, `el`, `gu`, `he`, `hi`, `hu`, `is`, `it`, `ja`, `jp`, `kn`, `ko`, `lv`, `lt`, `ms`, `ml`, `mr`, `nb`, `pl`, `pt-br`, `pt-pt`, `pa`, `ro`, `ru`, `sr`, `sk`, `sl`, `es`, `sv`, `ta`, `te`, `th`, `tr`, `uk`, `vi`; default `en` | The search language preference. The 2 or more character language code for which the search results are provided. |
| `country` | query | string | No | `AR`, `AU`, `AT`, `BE`, `BR`, `CA`, `CL`, `DK`, `FI`, `FR`, `DE`, `GR`, `HK`, `IN`, `ID`, `IT`, `JP`, `KR`, `MY`, `MX`, `NL`, `NZ`, `NO`, `CN`, `PL`, `PT`, `PH`, `RU`, `SA`, `ZA`, `ES`, `SE`, `CH`, `TW`, `TR`, `GB`, `US`, `ALL`; default `US` | The search query country, where the results come from. The country string is limited to 2 character country codes of supported countries and `ALL` for worldwide. |
| `safesearch` | query | string | No | `off`, `strict`; default `strict` | Filters search results for adult content. The following values are supported: - **off** - No content filtering (except for illegal content). - **strict** - Drops all adult content from search results. |
| `count` | query | integer | No | `1`-`200`; default `50` | The number of search results returned in response. The maximum is 200. The actual number delivered may be less than requested. **NOTE:** Image search is not paginated and has no `offset` parameter. Raise `count` to get more results. |
| `spellcheck` | query | boolean | No | default `true` | Whether to spell check provided query. If the spell checker is enabled, the modified query is always used for search. The modified query can be found in altered key from the query response model. |

## Headers

| Name | Location | Type | Required | Constraints | Description |
|------|----------|------|----------|-------------|-------------|
| `api-version` | header | string | No |  | The API version to use. This is denoted by the format `YYYY-MM-DD`. Default is the latest that is available. Read more about [API versioning](/documentation/guides/versioning). |
| `accept` | header | string | No | `application/json`, `*/*`; default `application/json` | The default supported media type is application/json. |
| `cache-control` | header | string | No | `no-cache` | Brave Search will return cached content by default. To prevent caching set the Cache-Control header to `no-cache`. This is currently done as best effort. |
| `user-agent` | header | string | No |  | The user agent originating the request. Brave search can utilize the user agent to provide a different experience depending on the device as described by the string. The user agent should follow the commonly used browser agent strings on each platform. For more information on curating user agents, see [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-user-agent). |

## Responses

### 200
Successful Response

| Field | Type | Description |
|-------|------|-------------|
| `type` | string? |  |
| `query` | object | Image search query string. |
| `query.original` | string | The original query that was requested. |
| `query.altered` | string? | The altered query by the spellchecker. This is the query that is used to search. |
| `query.spellcheck_off` | bool? | Whether the spellchecker is enabled or disabled. |
| `query.show_strict_warning` | bool? | The value is `true` if the lack of results is due to a `strict` safesearch setting. Adult content relevant to the query was found, but was blocked by safesearch. |
| `results` | object[] | The list of image results for the given query. |
| `results[].type` | string? | The type of image search API result. The value is always `image_result`. |
| `results[].title` | string? | The title of the image. |
| `results[].url` | string? | The original page URL where the image was found. |
| `results[].source` | string? | The source domain where the image was found. |
| `results[].page_fetched` | string? | The ISO date time when the page was last fetched. The format is `YYYY-MM-DDTHH:MM:SSZ`. |
| `results[].thumbnail` | object? | The thumbnail for the image. |
| `results[].thumbnail.src` | string? | The served URL of the image. |
| `results[].thumbnail.width` | int? | The width of the image. |
| `results[].thumbnail.height` | int? | The height of the image. |
| `results[].properties` | object? | Metadata for the image. |
| `results[].properties.url` | string? | The image URL. |
| `results[].properties.placeholder` | string? | The lower resolution placeholder image URL. |
| `results[].properties.width` | int? | The width of the image. |
| `results[].properties.height` | int? | The height of the image. |
| `results[].meta_url` | object? | Aggregated information on the URL associated with the image search result. |
| `results[].meta_url.scheme` | string? | The protocol scheme extracted from the URL. |
| `results[].meta_url.netloc` | string? | The network location part extracted from the URL. |
| `results[].meta_url.hostname` | string? | The lowercased domain name extracted from the URL. |
| `results[].meta_url.favicon` | string? | The favicon used for the URL. |
| `results[].meta_url.path` | string? | The hierarchical path of the URL useful as a display string. |
| `results[].confidence` | string? | The confidence level for the image result. |
| `extra` | object | Additional information about the image search results. |
| `extra.might_be_offensive` | bool? | Indicates whether the image search results might contain offensive content. |

### 404
Not Found

| Field | Type | Description |
|-------|------|-------------|
| `type` | string? |  |
| `error` | object |  |
| `error.id` | string | A unique identifier for this particular occurrence of the problem. |
| `error.status` | int | The HTTP status code applicable to this problem, expressed as a string value. |
| `error.detail` | string? | Explanation specific to this occurrence of the problem. Like title, this field's value can be localized. |
| `error.meta` | object? | A meta object containing non-standard meta-information about the error. |
| `error.code` | string | An application-specific error code, expressed as a string value. |
| `time` | int? |  |

### 422
Unprocessable Entity

| Field | Type | Description |
|-------|------|-------------|
| `type` | string? |  |
| `error` | object |  |
| `error.id` | string | A unique identifier for this particular occurrence of the problem. |
| `error.status` | int | The HTTP status code applicable to this problem, expressed as a string value. |
| `error.detail` | string? | Explanation specific to this occurrence of the problem. Like title, this field's value can be localized. |
| `error.meta` | object? | A meta object containing non-standard meta-information about the error. |
| `error.code` | string | An application-specific error code, expressed as a string value. |
| `time` | int? |  |

### 429
Too Many Requests

| Field | Type | Description |
|-------|------|-------------|
| `type` | string? |  |
| `error` | object |  |
| `error.id` | string | A unique identifier for this particular occurrence of the problem. |
| `error.status` | int | The HTTP status code applicable to this problem, expressed as a string value. |
| `error.detail` | string? | Explanation specific to this occurrence of the problem. Like title, this field's value can be localized. |
| `error.meta` | object? | A meta object containing non-standard meta-information about the error. |
| `error.code` | string | An application-specific error code, expressed as a string value. |
| `time` | int? |  |

## Code Samples

### cURL

```bash
curl "https://api.search.brave.com/res/v1/images/search?q=mountain+landscape" \
  -H "Accept: application/json" \ 
  -H "Accept-Encoding: gzip" \ 
  -H "X-Subscription-Token: <YOUR_API_KEY>"
```

### Python

```python
import requests

url = "https://api.search.brave.com/res/v1/images/search"

params = {
    "q": "mountain landscape"
}

headers = {
    "Accept": "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": "<YOUR_API_KEY>"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())
```