# Ecosia Search API — web, news, images, videos and autocomplete (SERP scraper)

> Ecosia web results for a query: ranked organic results (position, title, URL, displayed URL, domain, snippet, date, sitelinks), related searches, knowledge panel, local businesses, inline videos, spelling correction, plus the index Ecosia answered from. Choose the region, SafeSearch level and the page.
> ReefAPI engine `ecosia` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/ecosia/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/ecosia/v1/search — 2 credits
Ecosia web results for a query: ranked organic results (position, title, URL, displayed URL, domain, snippet, date, sitelinks), related searches, knowledge panel, local businesses, inline videos, spelling correction, plus the index Ecosia answered from. Choose the region, SafeSearch level and the page.

**Parameters:**
- `q` (string, required) — Search query, in any language.
- `market` (enum, optional, default "en-us") — Ecosia search region (language-country, lowercase), the same list as Ecosia's own region menu. Sets which country's results and which language the index favours. en-ww = all regions. [one of: en-us, es-us, en-gb, en-ca, fr-ca, en-au, en-nz, en-ie, en-in, en-za, en-sg, en-my, en-ph, en-id, en-th, th-th, en-vn, vi-vn, en-sa, ar-sa, de-de, de-at, de-ch, fr-ch, fr-fr, fr-be, nl-be, nl-nl, es-es, pt-pt, it-it, pl-pl, cz-cz, sk-sk, hr-hr, ro-ro, bg-bg, gr-gr, da-dk, sv-se, nb-no, fi-fi, ee-ee, lv-lv, lt-lt, uk-ua, ru-ru, tr-tr, ja-jp, ko-kr, zh-cn, zh-hk, zh-tw, pt-br, es-mx, es-ar, es-cl, es-co, es-pe, es-ve, en-ww]
- `language` (string, optional) — Interface language as a 2-letter code (en, de, fr, ja...). Defaults to the market's language. It changes the labels Ecosia writes into the page (for example the sitelink text), not which results are returned.
- `safe_search` (enum, optional, default "moderate") — Ecosia SafeSearch level. [one of: strict, moderate, off]
- `page` (integer, optional, default 1) — 1-based results page.

**Returns:** query, market, page, results_provider, results[] (position/title/url/displayed_url/domain/url_is_redirect/snippet/date/source_name/thumbnail_url/sitelinks/ecosia_label/provider), ads[], related_searches[], knowledge_panel{}, local_results[], video_results[], spelling_suggestion, query_correction{}, has_next_page

**Example request body:**
```json
{
  "q": "best hiking boots"
}
```

### POST https://api.reefapi.com/ecosia/v1/news — 2 credits
Ecosia News results: title, URL, publisher, publish time (UTC), snippet and thumbnail, with the source's own total count. Region, SafeSearch, recency window and page.

**Parameters:**
- `q` (string, required) — Search query, in any language.
- `market` (enum, optional, default "en-us") — Ecosia search region (language-country, lowercase), the same list as Ecosia's own region menu. Sets which country's results and which language the index favours. en-ww = all regions. [one of: en-us, es-us, en-gb, en-ca, fr-ca, en-au, en-nz, en-ie, en-in, en-za, en-sg, en-my, en-ph, en-id, en-th, th-th, en-vn, vi-vn, en-sa, ar-sa, de-de, de-at, de-ch, fr-ch, fr-fr, fr-be, nl-be, nl-nl, es-es, pt-pt, it-it, pl-pl, cz-cz, sk-sk, hr-hr, ro-ro, bg-bg, gr-gr, da-dk, sv-se, nb-no, fi-fi, ee-ee, lv-lv, lt-lt, uk-ua, ru-ru, tr-tr, ja-jp, ko-kr, zh-cn, zh-hk, zh-tw, pt-br, es-mx, es-ar, es-cl, es-co, es-pe, es-ve, en-ww]
- `language` (string, optional) — Interface language as a 2-letter code (en, de, fr, ja...). Defaults to the market's language. It changes the labels Ecosia writes into the page (for example the sitelink text), not which results are returned.
- `safe_search` (enum, optional, default "moderate") — Ecosia SafeSearch level. [one of: strict, moderate, off]
- `freshness` (enum, optional) — Only results from this recency window (Ecosia's own time filter). [one of: day, week, month]
- `page` (integer, optional, default 1) — 1-based results page.

**Returns:** query, market, page, total_results, total_pages, news[] (position/title/url/domain/source/date/snippet/thumbnail_url)

**Example request body:**
```json
{
  "q": "climate change"
}
```

### POST https://api.reefapi.com/ecosia/v1/images — 3 credits
Ecosia image results: full-size image URL, thumbnail, source page, dimensions, format and accent colour, plus Ecosia's related-search chips. Filter by size, colour, type, aspect ratio, licence and recency.

**Parameters:**
- `q` (string, required) — Search query, in any language.
- `market` (enum, optional, default "en-us") — Ecosia search region (language-country, lowercase), the same list as Ecosia's own region menu. Sets which country's results and which language the index favours. en-ww = all regions. [one of: en-us, es-us, en-gb, en-ca, fr-ca, en-au, en-nz, en-ie, en-in, en-za, en-sg, en-my, en-ph, en-id, en-th, th-th, en-vn, vi-vn, en-sa, ar-sa, de-de, de-at, de-ch, fr-ch, fr-fr, fr-be, nl-be, nl-nl, es-es, pt-pt, it-it, pl-pl, cz-cz, sk-sk, hr-hr, ro-ro, bg-bg, gr-gr, da-dk, sv-se, nb-no, fi-fi, ee-ee, lv-lv, lt-lt, uk-ua, ru-ru, tr-tr, ja-jp, ko-kr, zh-cn, zh-hk, zh-tw, pt-br, es-mx, es-ar, es-cl, es-co, es-pe, es-ve, en-ww]
- `language` (string, optional) — Interface language as a 2-letter code (en, de, fr, ja...). Defaults to the market's language. It changes the labels Ecosia writes into the page (for example the sitelink text), not which results are returned.
- `safe_search` (enum, optional, default "moderate") — Ecosia SafeSearch level. [one of: strict, moderate, off]
- `freshness` (enum, optional) — Only results from this recency window (Ecosia's own time filter). [one of: day, week, month]
- `size` (enum, optional) — Ecosia's own 'size' filter. [one of: small, medium, large, wallpaper]
- `color` (enum, optional) — Ecosia's own 'color' filter. [one of: colorOnly, monochrome, red, orange, yellow, green, teal, blue, purple, pink, brown, black, gray, white]
- `image_type` (enum, optional) — Ecosia's own 'imageType' filter. [one of: photo, clipart, line, animatedgif, transparent]
- `aspect` (enum, optional) — Ecosia's own 'aspect' filter. [one of: square, wide, tall]
- `license` (enum, optional) — Ecosia's own 'license' filter. [one of: share, shareCommercially, modify, modifyCommercially, public]
- `page` (integer, optional, default 1) — 1-based results page. About 60 images per page. Pages overlap (Ecosia serves windows, not slices): dedupe on id.

**Returns:** query, market, page, total_results, images[] (position/id/title/image_url/thumbnail_url/source_url/domain/width/height/thumbnail_width/thumbnail_height/format/accent_color), related_searches[] (query/label/thumbnail_url)

**Example request body:**
```json
{
  "q": "red fox"
}
```

### POST https://api.reefapi.com/ecosia/v1/videos — 2 credits
Ecosia video results: watch URL, platform, title, description, duration (ISO 8601 and seconds), publish date and thumbnail. Filter by length, resolution and recency.

**Parameters:**
- `q` (string, required) — Search query, in any language.
- `market` (enum, optional, default "en-us") — Ecosia search region (language-country, lowercase), the same list as Ecosia's own region menu. Sets which country's results and which language the index favours. en-ww = all regions. [one of: en-us, es-us, en-gb, en-ca, fr-ca, en-au, en-nz, en-ie, en-in, en-za, en-sg, en-my, en-ph, en-id, en-th, th-th, en-vn, vi-vn, en-sa, ar-sa, de-de, de-at, de-ch, fr-ch, fr-fr, fr-be, nl-be, nl-nl, es-es, pt-pt, it-it, pl-pl, cz-cz, sk-sk, hr-hr, ro-ro, bg-bg, gr-gr, da-dk, sv-se, nb-no, fi-fi, ee-ee, lv-lv, lt-lt, uk-ua, ru-ru, tr-tr, ja-jp, ko-kr, zh-cn, zh-hk, zh-tw, pt-br, es-mx, es-ar, es-cl, es-co, es-pe, es-ve, en-ww]
- `language` (string, optional) — Interface language as a 2-letter code (en, de, fr, ja...). Defaults to the market's language. It changes the labels Ecosia writes into the page (for example the sitelink text), not which results are returned.
- `safe_search` (enum, optional, default "moderate") — Ecosia SafeSearch level. [one of: strict, moderate, off]
- `freshness` (enum, optional) — Only results from this recency window (Ecosia's own time filter). [one of: day, week, month]
- `length` (enum, optional) — Ecosia's own 'videoLength' filter. [one of: short, medium, long]
- `resolution` (enum, optional) — Ecosia's own 'resolution' filter. [one of: 480p, 720p, 1080p]
- `page` (integer, optional, default 1) — 1-based results page.

**Returns:** query, market, page, total_results, total_pages, videos[] (position/title/url/domain/platform/date/duration/duration_seconds/description/thumbnail_url)

**Example request body:**
```json
{
  "q": "how to tie a tie"
}
```

### POST https://api.reefapi.com/ecosia/v1/autocomplete — 1 credit
Ecosia search suggestions for a partial query, in the chosen region (the typeahead Ecosia's own search box shows, up to 10). Fast and cheap.

**Parameters:**
- `q` (string, required) — The partial query typed so far.
- `market` (enum, optional, default "en-us") — Ecosia search region (language-country, lowercase), the same list as Ecosia's own region menu. Sets which country's results and which language the index favours. en-ww = all regions. [one of: en-us, es-us, en-gb, en-ca, fr-ca, en-au, en-nz, en-ie, en-in, en-za, en-sg, en-my, en-ph, en-id, en-th, th-th, en-vn, vi-vn, en-sa, ar-sa, de-de, de-at, de-ch, fr-ch, fr-fr, fr-be, nl-be, nl-nl, es-es, pt-pt, it-it, pl-pl, cz-cz, sk-sk, hr-hr, ro-ro, bg-bg, gr-gr, da-dk, sv-se, nb-no, fi-fi, ee-ee, lv-lv, lt-lt, uk-ua, ru-ru, tr-tr, ja-jp, ko-kr, zh-cn, zh-hk, zh-tw, pt-br, es-mx, es-ar, es-cl, es-co, es-pe, es-ve, en-ww]

**Returns:** query, market, count, suggestions[]

**Example request body:**
```json
{
  "q": "berlin"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=ecosia
- Human docs page: https://reefapi.com/docs/ecosia
- Overview page: https://reefapi.com/ecosia-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt