Main Search API

The main google Search API provides structured search results including organic listings, "People Also Ask" questions, and related searches. This powerful endpoint allows you to perform Google searches with precise location and language targeting.

Base URL

https://app.serpextractor.com

Authentication

All API requests require authentication using an API key. Include your key in the X-API-Key header with every request.

-H 'X-API-Key: YOUR_API_KEY'

Main Search Endpoint

Endpoint Details

GET /api/google

This endpoint executes a Google search and returns structured results including organic listings, related questions, and similar searches.

Request Parameters

Parameter	Description	Example	Required	Notes
`query`	The search term	`café`	Yes	Must be URL encoded
`location`	Geographic location	`Paris,Paris,Ile-de-France,France`	No	Must follow format: `City,City,Region,Country`. Must be URL encoded, for more info check our locations API
`google_domain`	Google domain to use	`google.fr`	No	Domain name without `https://www.`
`gl`	Google country code	`fr`	No	Two-letter country code
`hl`	Interface language	`fr`	No	Two-letter language code
`search_type`	Type of search	`main`	No	Default is `main`
`device`	Device type	`desktop`	No	Options: `desktop`, `mobile` or `tablet`

Example URL with parameters

https://app.serpextractor.com/api/google?
  query=caf%C3%A9&
  location=Paris%2CParis%2CIle-de-France%2CFrance&
  google_domain=google.fr&
  gl=fr&
  hl=fr&
  search_type=main&
  device=desktop

note

The location parameter must be in a specific format. Use our Location API to get the correct format for your desired location.

Example Request

curl -X 'GET' \
  'https://app.serpextractor.com/api/google?query=café&location=Paris%2CParis%2CIle-de-France%2CFrance&google_domain=google.fr&gl=fr&hl=fr&search_type=main&device=desktop' \
  -H 'accept: */*' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

{
  organic_results: Array<{
    position: number,    // Ranking position in results
    title: string,      // Page title
    link: string,       // URL of the result
    content: string     // Snippet or description
  }>,
  people_also_ask: Array<{
   zy question: string    // Related question
  }>,
  people_also_search_for: Array<{
    query: string       // Related search query
  }>,
  metadata: {
    status: string,     // Success/failure status
    request_id: string, // Unique identifier for the request
    created_at: string, // Timestamp of when the request was received
    updated_at: string, // Timestamp of when the response was generated
    params: {           // Echo of the input parameters
      query: string,
      location: string,
      google_domain: string,
      gl: string,
      hl: string,
      search_type: string,
      device: string
    }
  }
}

Status Codes

Status Code	Description
200	Request successful
400	Invalid parameters provided
401	Authentication failed - check API key
429	Rate limit exceeded or no requests available
500	Server-side error occurred

Examples

1. Basic Search Request

Search for "coffee shops" in English:

curl -X 'GET' \
  'https://app.serpextractor.com/api/google?query=coffee%20shops' \
  -H 'accept: */*' \
  -H 'X-API-Key: YOUR_API_KEY'

2. Localized Search Request

Search for "restaurants" in Spanish, targeting Madrid:

curl -X 'GET' \
  'https://app.serpextractor.com/api/google?query=restaurantes&location=Madrid%2CMadrid%2CCommunity%20of%20Madrid%2CSpain&google_domain=google.es&gl=es&hl=es' \
  -H 'accept: */*' \
  -H 'X-API-Key: YOUR_API_KEY'

3. Mobile Search Request

Search for "hotels" optimized for mobile devices:

curl -X 'GET' \
  'https://app.serpextractor.com/api/google?query=hotels&device=mobile' \
  -H 'accept: */*' \
  -H 'X-API-Key: YOUR_API_KEY'

Example Responses

1. Example response from the first curl with Paris localization

{
  "organic_results": [
    {
      "position": 1,
      "title": "LES 10 MEILLEURS cafés Paris",
      "link": "https://www.tripadvisor.fr/Restaurants-g187147-c8-Paris_Ile_de_France.html",
      "content": "13 nov. 2019 — Meilleurs cafés à Paris · 1. Jozi Brunch. (226). Fermé. Thé et café, Française€ Menu · 2. Zia. (235). Fermé. Française, Américaine€€-€€€ Menu."
    },
    {
      "position": 2,
      "title": "THE 10 BEST Cafés for Lunch in Paris",
      "link": "https://www.tripadvisor.com/Restaurants-g187147-c8-zfp30-Paris_Ile_de_France.html",
      "content": "Best Cafés in Paris, Ile-de-France: Find Tripadvisor traveller reviews of Paris Cafés and search by price, location, and more."
    },
    {
      "position": 3,
      "title": "Café",
      "link": "https://fr.wikipedia.org/wiki/Caf%C3%A9",
      "content": "Le café (de l'arabe قهوة : qahwa, « boisson stimulante ») est une boisson énergisante psychotrope stimulante, obtenue à partir des graines torréfiées de ..."
    },
    {
      "position": 4,
      "title": "Café Appliances",
      "link": "https://www.cafeappliances.com/",
      "content": "It's time to make appliances personal. With custom hardware, matte and sleek glass finishes, Café offers distinct appliances to match your style and tastes."
    },
    {
      "position": 5,
      "title": "Café de Flore",
      "link": "https://en.wikipedia.org/wiki/Caf%C3%A9_de_Flore",
      "content": "One of the oldest coffeehouses in Paris, known for its emblematic shopfront and celebrated for its famous clientele."
    },
    {
      "position": 6,
      "title": "21 Best Cafés in Paris",
      "link": "https://www.cntraveler.com/gallery/best-cafes-and-coffee-shops-in-paris",
      "content": "10 avr. 2023 — The 21 Best Cafés in Paris · Ten Belles · Café Loustic · Télescope · Holybelly · Café Méricourt · Fringe Coffee · O Coffeeshop · Lomi. $$."
    },
    {
      "position": 7,
      "title": "20 of the Best Cafés in Paris: From Classic to Modern",
      "link": "https://frenchly.us/best-cafes-in-paris/",
      "content": "15 oct. 2024 — 10 of the Most Iconic Parisian Cafés · 1. Bar du Marché · 2. Le Consulat · 3. La Fontaine de Belleville · 4. Café Charlot · 5. Café de Flore · 6 ..."
    },
    {
      "position": 8,
      "title": "TOP 10 BEST Cafes in Paris, France - Updated 2024",
      "link": "https://www.yelp.com/search?find_desc=Cafes&find_loc=Paris",
      "content": "Top 10 Best Cafes Near Paris, Paris · 1. Café Blanc · 2. Carette · 3. A. Lacroix · 4. Le Café · 5. Baguett's Café · 6. Anticafé · 7. Le Café Laurent · 8."
    },
    {
      "position": 9,
      "title": "The best Paris cafés to visit all year-round",
      "link": "https://www.cntraveller.com/gallery/best-cafes-in-paris",
      "content": "26 juin 2024 — The 33 best cafes in Paris – from old classics to hip new spaces, these are the places to visit for coffee and a light bite year-round in ..."
    }
  ],
  "people_also_ask": [
    {
      "question": "Quels sont les bienfaits du café sur la santé ?"
    },
    {
      "question": "Quelle est la meilleure marque de café au monde ?"
    },
    {
      "question": "Quel est le pays qui a inventé le café ?"
    },
    {
      "question": "Quel café le matin ?"
    }
  ],
  "people_also_search_for": [
    {
      "query": "Café à proximité"
    },
    {
      "query": "Café marque"
    },
    {
      "query": "Café Paris"
    },
    {
      "query": "Café ouvert actuellement"
    },
    {
      "query": "Café grain"
    },
    {
      "query": "Café moulu"
    },
    {
      "query": "Meilleur café Paris"
    },
    {
      "query": "Café maps"
    }
  ],
  "metadata": {
    "status": "Success",
    "request_id": "c6c97438-52f2-4a8e-a5ce-9297393d6a39",
    "created_at": "2024-11-13T08:54:32.057395+00:00",
    "updated_at": "2024-11-13T08:54:32.062946",
    "params": {
      "query": "café",
      "location": "Paris,Paris,Ile-de-France,France",
      "google_domain": "google.fr",
      "gl": "fr",
      "hl": "fr",
      "cr": null,
      "lr": null,
      "search_type": "main",
      "page": null,
      "device": "desktop"
    }
  }
}

Response Schema

{
  // Organic search results
  organic_results: Array<{
    position: number,    // Position in search results (1-based)
    title: string,      // Page title
    link: string,       // Result URL
    content: string     // Result snippet/description
  }>,
  
  // "People Also Ask" questions
  people_also_ask: Array<{
    question: string    // Related question
  }>,
  
  // Related searches
  people_also_search_for: Array<{
    query: string       // Related search term
  }>,
  
  // Request metadata
  metadata: {
    status: string,     // Request status
    request_id: string, // Unique request identifier
    created_at: string, // Request timestamp
    updated_at: string, // Response timestamp
    params: {           // Request parameters
      query: string,
      location: string,
      google_domain: string,
      gl: string,
      hl: string,
      search_type: string,
      device: string
    }
  }
}

Best Practices

Rate Limiting: Implement appropriate rate limiting in your application to avoid hitting concurrent connection limits.
URL Encoding: Always URL encode your query and location parameters to ensure proper handling of special characters.
Error Handling: Implement robust error handling for all status codes, especially 429 (rate limiting) and 500 (server errors).
Caching: Consider caching responses to improve performance and reduce API calls for frequently requested searches.
Location Format: Use the Location API to ensure correct formatting of the location parameter.

note

The location parameter requires a specific format. Use our Location API to obtain the correct format for your desired location. Incorrect formatting may result in unexpected results or errors.

tip

Consider implementing rate limiting and caching in your application to avoid hitting the concurrent connection limit.

Base URL​

Authentication​

Main Search Endpoint​

Endpoint Details​

Request Parameters​

Example Request​

Response​

Status Codes​

Examples​

1. Basic Search Request​

2. Localized Search Request​

3. Mobile Search Request​

Example Responses​

1. Example response from the first curl with Paris localization​

Response Schema​

Best Practices​