Google Search

Search Google and retrieve web search results in JSON format.

Endpoint

GET /v1/search/{query}

Description

The Google Search endpoint allows you to perform web searches and retrieve results from Google. The query parameter should be a URL-encoded query string that follows Google's search parameter format.

For reference on Google search parameters, check out our Google Search Operators guide.

Authentication

All requests require authentication using the X-Api-Key header. See the Authentication guide for more details.

Path Parameters

query (required)

Type: string

A URL-encoded query string. This should follow Google's search parameter format.

Examples:

  • q=search+api
  • q=search+api&num=100

Request Headers

X-Proxy-Location (optional)

Type: string

Specify the proxy location for the search. This determines the geographic location from which the search is performed.

Allowed values:

  • EU - European Union
  • CA - Canada
  • US - United States
  • IE - Ireland
  • GB - United Kingdom
  • FR - France
  • DE - Germany
  • SE - Sweden
  • IN - India
  • JP - Japan
  • KR - South Korea
  • SG - Singapore
  • AU - Australia
  • BR - Brazil

X-User-Agent (optional)

Type: string

Specify the device type for the search. Defaults to desktop if not provided.

Allowed values:

  • desktop - Desktop browser (default)
  • mobile - Mobile device

Request Example

Using cURL

curl --request GET \
  --url 'https://api.serply.io/v1/search/q=search+api' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'X-Proxy-Location: US' \
  --header 'X-User-Agent: desktop'

Using JavaScript/Node.js

const response = await fetch('https://api.serply.io/v1/search/q=search+api', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Proxy-Location': 'US',
    'X-User-Agent': 'desktop'
  }
});
const data = await response.json();
console.log(data);

Using Python

import requests

headers = {
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Proxy-Location': 'US',
    'X-User-Agent': 'desktop'
}

response = requests.get(
    'https://api.serply.io/v1/search/q=search+api',
    headers=headers
)
data = response.json()
print(data)

Response

The API returns a JSON object containing an array of search results, plus several other Google SERP feature arrays (ads, images, shopping, local places, etc.) that are populated only when Google's results page includes them.

Response Structure

{
  "results": [
    {
      "title": "Result Title",
      "description": "Result description text...",
      "position": 1,
      "realPosition": 1,
      "result_type": "organic",
      "metadata": {
        "display_url": "example.com"
      },
      "link": "https://example.com"
    }
  ],
  "ads": [],
  "ads_count": 0,
  "answers": [],
  "image_results": [],
  "shopping_ads": [],
  "places": [],
  "local_businesses": [],
  "related_searches": [],
  "carousel": [],
  "company": {},
  "total": null,
  "knowledge_graph": "",
  "related_questions": [],
  "carousel_count": 0,
  "ts": 0.9,
  "device_region": "",
  "device_type": null,
  "query": "search api"
}

Response Fields

  • results (array): An array of organic search result objects
    • title (string): The title of the search result
    • description (string): The description/snippet of the search result
    • position (number): Rank within the result set, starting at 1
    • realPosition (number): Same as position for organic results; differs when other SERP features are interleaved
    • result_type (string): Result classification, e.g. organic
    • metadata (object): Additional details — usually display_url; can include attributes (array of strings, e.g. a publish date) and, for local-business-style results, rating/reviews
    • link (string): The URL of the search result. Results served from certain buckets carry Google's own tracking params (client=, ved=, usg=, etc.) rather than a bare URL
  • total (number | null): Google's estimated result count. Usually null — Google only surfaces this on some result pages, so do not rely on it being populated
  • answers (array): Answer box content, if Google shows one for the query. Empty array when absent
  • ads, image_results, shopping_ads, places, local_businesses, related_searches, carousel, related_questions (arrays): Other SERP feature results, populated only when present on the page
  • ads_count, carousel_count (number): Counts for the corresponding arrays
  • company (object), knowledge_graph (string): Knowledge panel data, when present; otherwise empty
  • ts (number): Time in seconds the request took to complete
  • device_region (string): Proxy region used, if specified via X-Proxy-Location
  • device_type (string | null): Device type used for the search
  • query (string): The search query that was run

Example Response

{
  "results": [
    {
      "title": "The tutorial — Python 3.14.7 documentation",
      "description": "Python is an easy to learn, powerful programming language...",
      "position": 1,
      "realPosition": 1,
      "result_type": "organic",
      "metadata": {
        "display_url": "docs.python.org"
      },
      "link": "https://docs.python.org/3/tutorial/"
    },
    {
      "title": "Python Tutorial - W3Schools",
      "description": "Python is a popular programming language. Python can be used on a server to create web applications...",
      "position": 2,
      "realPosition": 2,
      "result_type": "organic",
      "metadata": {
        "display_url": "www.w3schools.com"
      },
      "link": "https://www.w3schools.com/python/"
    }
  ],
  "ads": [],
  "ads_count": 0,
  "answers": [],
  "image_results": [],
  "shopping_ads": [],
  "places": [],
  "local_businesses": [],
  "related_searches": [],
  "carousel": [],
  "company": {},
  "total": null,
  "knowledge_graph": "",
  "related_questions": [],
  "carousel_count": 0,
  "ts": 1.02,
  "device_region": "",
  "device_type": null,
  "query": "python tutorial"
}

Status Codes

  • 200 OK - Successful response
  • 404 Not Found - The requested resource was not found
  • 422 Unprocessable Entity - The request was well-formed but contains semantic errors
  • 429 Too Many Requests - Rate limit exceeded

Error Responses

See the Errors guide for information on error response formats.

View as Markdown