API Documentation
Surfapi exposes a simple, stable JSON contract. Every request is a single GET to
/search.json with an engine and
query parameters; the response is JSON with search_metadata,
search_parameters, and the parsed results.
Already using a hosted search API? Point your client at
surf-api.com and use your Surfapi key —
the request parameters and response shapes are standard and well-documented below.
Authentication
Pass your API key as api_key in the query string, or as an
X-API-Key header.
curl "https://surf-api.com/search.json?engine=google_news&q=coffee&api_key=YOUR_API_KEY"
Sign up to get a key — your examples below will be pre-filled.
Endpoints
| Endpoint | Description |
|---|---|
GET /search.json | Run a search. Returns JSON. |
GET /search | Alias of /search.json. |
GET /account | Your plan, usage, and searches left. |
GET /searches/:t/:id.json | Retrieve an archived search. |
GET /engines | List available engines. |
Google Search ● needs residential proxy
Organic results, snippets, related searches. engine=google
| Parameter | Description |
|---|---|
q required | Search query. |
location | Geographic location to originate the search from. |
google_domain | Domain, e.g. google.com (default). |
gl | Two-letter country code (default us). |
hl | Two-letter language code (default en). |
num | Number of results. |
start | Result offset for pagination. |
# cURL curl "https://surf-api.com/search.json?engine=google&q=coffee&gl=us&hl=en&api_key=YOUR_API_KEY"
Google Images ● live, no proxy
Image results with thumbnails, source, and original URLs (no proxy required). engine=google_images
| Parameter | Description |
|---|---|
q required | Search query. |
gl | Country code. |
hl | Language code. |
safe | Safe search: active or off. |
# cURL curl "https://surf-api.com/search.json?engine=google_images&q=coffee&api_key=YOUR_API_KEY"
Google News ● live, no proxy
News articles and story clusters with sources and timestamps. engine=google_news
| Parameter | Description |
|---|---|
q | Search query (omit for top headlines). |
gl | Country code. |
hl | Language code. |
# cURL curl "https://surf-api.com/search.json?engine=google_news&q=coffee&api_key=YOUR_API_KEY"
Google Shopping ● needs residential proxy
Product listings with prices, ratings, sources, and thumbnails. engine=google_shopping
| Parameter | Description |
|---|---|
q required | Search query. |
gl | Country code. |
hl | Language code. |
# cURL curl "https://surf-api.com/search.json?engine=google_shopping&q=coffee+maker&api_key=YOUR_API_KEY"
Google Hotels ● live, no proxy
Property search and details (property_token mode). engine=google_hotels
| Parameter | Description |
|---|---|
q required | Search query (or use property_token for details). |
check_in_date | YYYY-MM-DD. |
check_out_date | YYYY-MM-DD. |
adults | Number of adults. |
property_token | Fetch a single property’s details. |
# cURL curl "https://surf-api.com/search.json?engine=google_hotels&q=Bali+Resorts&api_key=YOUR_API_KEY"
Google Hotels Autocomplete ● live, no proxy
Typeahead suggestions resolving to property tokens. engine=google_hotels_autocomplete
| Parameter | Description |
|---|---|
q required | Partial hotel/location query. |
# cURL curl "https://surf-api.com/search.json?engine=google_hotels_autocomplete&q=Hilton+Malta&api_key=YOUR_API_KEY"
Google Flights ● live, no proxy
Best and other flight options with prices, segments, and carbon estimates. engine=google_flights
| Parameter | Description |
|---|---|
departure_id required | Departure airport code, e.g. JFK. |
arrival_id required | Arrival airport code, e.g. LHR. |
outbound_date required | YYYY-MM-DD. |
return_date | YYYY-MM-DD (round trip). |
type | 1 round trip (default), 2 one-way, 3 multi-city. |
adults | Number of adults. |
currency | Currency code, e.g. USD. |
# cURL curl "https://surf-api.com/search.json?engine=google_flights&departure_id=JFK&arrival_id=LHR&outbound_date=2026-07-10&return_date=2026-07-17&api_key=YOUR_API_KEY"