# Google SERP API

### Overview

Seodity SERP API allows you to execute search requests in real time, returning clean, structured JSON data based on different parameters such as query, location, language, and device.

### Authorization

Authorization is required for making requests to the Seodity SERP API. It involves passing your unique API key that you receive when you register with Seodity, so the server can validate and grant access to the resources requested.

The API key should be included in the header of every API request, under the field "Authorization". The key needs to be prefixed with the term "APIKey" followed by a space. So, your HTTP GET request should contain an Authorization header that looks like this: `Authorization: APIKey <api_key>`. Replace `<api_key>` with your actual API key.

This ensures that your requests to the Seodity SERP API are authenticated and properly processed. If the API key is missing or invalid, the server responds with an error.

### Requests

#### Searching Google

To perform a search in Google SERP:

```http
GET https://api.seodity.com/v1/api/serp/google/search
```

**Parameters:**

* `query`: required, string.
* `location`: optional, string. (default: "United States")
* `language`: optional, string. (default: "English")
* `device`: optional, string. (default: "desktop")

**Example:**

```curl
curl -X GET 'https://api.seodity.com/v1/api/serp/google/search?query=pizza&location=United States&language=English&device=desktop'
```

#### Searching Google for Ads

To perform a search in Google SERP with higher possibility to return ads:

```http
GET https://api.seodity.com/v1/api/serp/google/search/ads
```

**Parameters:**

* `query`: required, string.
* `location`: optional, string. (default: "United States")
* `language`: optional, string. (default: "English")
* `device`: optional, string. (default: "desktop")
* `proxy_location`: optional, string. (default: empty)

**Example:**

```curl
curl -X GET 'https://api.seodity.com/v1/api/serp/google/search/ads?query=pizza&location=United States&language=English&device=desktop'
```

#### Getting Language Information

To fetch the list of available languages:

```http
GET https://api.seodity.com/v1/api/serp/google/languages
```

**Parameters:**

* `search`: optional, string. (default: empty)

**Example:**

```curl
curl -X GET 'https://api.seodity.com/v1/api/serp/google/languages?search=english'
```

#### Getting Location Information

To fetch the list of available locations:

```http
GET https://api.seodity.com/v1/api/serp/google/locations
```

**Parameters:**

* `q`: required, string.
* `type`: optional, string. (available options: "country")
* `country_code`: optional, string (for example: "us").

**Example:**

```curl
curl -X GET 'https://api.seodity.com/v1/api/serp/google/locations?q=united states&type=country&country_code=us'
```

### Response Object

Responses from Seodity SERP API calls contain the following data:

* `request_info`: Contains details about the request.
  * `uid`: Unique identifier of the request.
  * `account_uid`: Unique identifier of the account making the request.
  * `success`: Indicates if the request was successful or not.
  * `api`: The API being used for the request.
  * `api_function`: The specific function of the API being used.
  * `parameters`: The parameters sent in the request.
  * `started_at`: The time when the request started.
  * `finished_at`: The time when the request finished.
  * `credits_used`: The number of credits used for the request.
  * `total_time_taken`: The total time taken to execute the request (in seconds).
* `metadata`: Contains further details about the request.
  * `google_url`: The URL of the Google Search Results Page (SERP) queried.
* `result`: Contains the search results.
  * `total_results`: Total number of results found.
  * `answer_box`: The answer box from the SERP, if any.
  * `organic_results`: An array of organic search results. Each element contains:
    * `position`: The rank of the result.
    * `title`: The title of the result.
    * `description`: A short description of the result.
    * `url`: The URL of the result.
  * `related_questions`: Array of related questions to the search query. Each element contains:
    * `title`: The related question title.
  * `related_searches`: Array of related searches to the search query. Each element contains:
    * `query`: The related search query.
  * `local_results`: Array of local search results.
  * `knowledge_graph`: Information from the Google Knowledge Graph, if any.
  * `inline_images`: Array of inline images related to the search query. Each element contains:
    * `title`: The title of the image.
    * `link`: The source URL of the image.
  * `inline_videos`: Array of inline video results related to the search query.

If an error occurs during a request, the `success` field in `request_info` becomes `false` and an `error` field will be appended to `request_info` with details about the error.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.seodity.com/api/google-serp-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.