---
title: Search endpoint
description: Run keyword searches on any supported site (search engines, marketplaces, job boards, and more) and get ranked results with positions, prices, ratings, and images.
order: 20
---

# `GET /api/v1/{site}/search`

Returns ranked search-results for a keyword query. `search` is the most widely available resource: it works on search engines (`google`, `bing`), marketplaces (`walmart`, `ebay`), job boards (`indeed`), app stores, and more. This page is the canonical **list pattern**: a keyword in, ranked results out. The example below uses `google`; swap the site for any other that exposes a `search` endpoint.

Marketplace search cards include commerce fields (price, rating, sponsored flags); search-engine results return web fields (title, url, snippet). The shape adapts to the target.

## Request

```http
GET /api/v1/google/search?query=wireless+headphones&api_key=cd_live_YOUR_KEY
```

### Query parameters

| Param | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | ✅ yes |  -  | Search keywords |
| `domain` | enum |  -  | site default | Regional storefront / locale for sites that have one |
| `sort_by` | enum |  -  | `best_match` | Marketplace sort: `best_match` · `price_asc` · `price_desc` · `avg_customer_review` · `newest` (where the site supports it) |
| `start_page` | int |  -  | `1` | Page to start from (1-10) |
| `pages` | int |  -  | `1` | Number of consecutive pages to fetch (1-10)  -  each counts as a request |

### Response (200) - marketplace search

For a marketplace site, each card carries commerce fields:

```json
{
  "page": 1,
  "products": [
    {
      "id": "5085206428",
      "title": "Acqua Di Gio By Giorgio Armani For Men. Eau De Toilette Spray 3.4 Fl Oz",
      "url": "https://www.walmart.com/ip/5085206428",
      "price": 19.57,
      "price_strikethrough": null,
      "highest_price": null,
      "currency": "USD",
      "rating": 4.5,
      "reviews_count": 150532,
      "sales_volume": "20K+ bought in past month",
      "image": "https://cdn.example.com/images/acqua-di-gio-71…",
      "is_sponsored": false,
      "best_seller": true,
      "organic_position": 1,
      "sponsored_position": null,
      "shipping_information": null,
      "pricing_count": null,
      "manufacturer": null,
      "is_video": false
    }
  ],
  "html": ""
}
```

### Response (200) - search engine

For a search engine like Google, each result carries web fields:

```json
{
  "query": "wireless headphones",
  "results": [
    {
      "position": 1,
      "title": "The 6 Best Wireless Headphones of 2026, Tested",
      "url": "https://www.example.com/best-wireless-headphones",
      "snippet": "We tested 30 pairs over three months to find the…"
    }
  ],
  "related_searches": ["noise cancelling headphones", "wireless earbuds"],
  "total_results": 48300000
}
```

### Field notes (marketplace cards)

| Field | Notes |
|---|---|
| `price_strikethrough` | The list price ("was") when the product is on sale. `null` when the product is at its normal price. We explicitly filter out per-unit prices (`$0.23/fluid ounce`, `$11.15/milliliter`, etc.) so this only ever holds a real discount anchor. |
| `highest_price` | Same value as `price_strikethrough` on the search card. Search cards never expose a multi-tier price range (only product pages do), so the strikethrough is the implicit upper bound. |
| `reviews_count` | Precise integer count parsed from the rating wrapper (e.g. `"5,054 ratings"`). Not the rounded `(5K)` display value. `null` when the site hides reviews (typical for brand-new listings). |
| `sales_volume` | Verbatim site string, e.g. `"5K+ bought in past month"`, `"200+ bought in past week"`. `null` when the site doesn't surface a badge for that card (low-velocity categories often omit it). |
| `organic_position` | 1-indexed rank among non-sponsored cards. Sponsored cards have `organic_position: null` and a positive `sponsored_position` instead. The first organic card after any run of sponsored cards still gets `organic_position: 1`. |

### Empty-result response (200)

When a site legitimately returns zero matches for a query, the response stays HTTP 200 with an empty results array and a `no_results: true` flag, so you can tell "the site returned nothing" from "we failed to scrape":

```json
{
  "page": 1,
  "products": [],
  "no_results": true,
  "total_results": 0,
  "html": null
}
```

## Common errors

Same as the product endpoint. `502 target_unreachable` on international storefronts is more common than on the default region - see our [country routing guide](/docs/guides/country-and-language) and the full [error codes](/docs/guides/errors) list.

## Related

- [Endpoint reference](/docs/endpoint-reference) - the resource model
- [Product endpoint](/docs/endpoints/product) - the specific-item pattern
- [Universal Web Scraper API](/docs/endpoints/universal) - for sites without a dedicated endpoint
- [Batch a hundred search queries](/docs/endpoints/batch)