# Google Search API ## Getting Started The [AvesAPI](https://avesapi.com) was built to let you scrape Google SERP data in real-time removing the complexity of managing proxy and solving CAPTCHA challenges. The application takes only a few minutes using the simple HTTP GET URL structure, and the results are returned as JSON or HTML. AvesAPI is based on [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) technology to interact with data between your application and our service. This documentation will outline in detail specifications, access, and available API endpoints. In case any technical questions are left unanswered, please feel free to contact AvesAPI support for assistance. #### Prohibited Keywords We deduct **1** credit per each successful request except for some restrictions in order to maintain our service sustainable. All operator search is strictly prohibited and if you make such query, 25 credits will be deducted. Some of them are listed below `site:` , `inurl:` , `domain:` , `link:` , `title:` , `intitle:` , `intext:` , `allintext:` , `cache:` , `before:` , `after:` ### ### API Access Key & Authentication After signing up for an account, each user will be assigned a unique API Access Key. This key will be used to authenticate with the API via REST and access any of the available endpoints. If you are a current user of AvesAPI, obtain the API Key from your [account page](https://app.avesapi.com/profile) to access our API. If you are not a member of AvesAPI you can [create your account](https://app.avesapi.com/register) to benefit from our service. To authenticate with the API, simply append your API key to the API's base URL using the `apikey` parameter shown below. ``` https://api.avesapi.com/search?apikey=YOUR_API_KEY ``` ### Common API Error Codes The response will be returned as **400** Status code If there is a problem with your request. | **Code** | **Type** | **Info** | | -------- | ---------------------- | ------------------------------------------------------------------ | | 405 | missing\_apikey | The user did not provide an API Key. | | 406 | invalid\_apikey | Invalid API Key. | | 409 | missing\_search\_query | The user did not provide a valid value inside the query parameter. | | 411 | invalid\_search\_type | The user did not provide a valid value inside the type parameter. | | 429 | usage\_limit\_reached | The user has reached his allowance credits. | ## API Endpoints To query the API for Google search results, simply append the query parameter to the API's base URL and set it to a search query of your choice. **Example request:**\ [**`https://api.avesapi.com/search?apikey=YOUR_API_KEY&query=covid19`**](https://api.avesapi.com/search?apikey=YOUR_API_KEY\&query=covid19) ### ### HTTP Get Requests Parameters | Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apikey` | **\[Required]** Your API Access key, available on your account dashboard. | | `query` | **\[Required]** Specify any query to search for. | | `device` | \[Optional] Specify which device to use: `desktop` (**default**), or mobile. | | `location` | \[Optional] Adding a location parameter to your API request helps to gather location-based search results. Download list of our supported places [resources.places.json](https://avesapi.com/places.json) which contains thousands of places as JSON array. If you want to gather local-based results you should use the value of "place\_slug" key in the file. For example, **"place\_slug": "london"** Adding location=london parameter to API URL means that you will get search results for London city. | | `google_domain` | \[Optional] Specify a Google domain to use for your query. (**Default**: `google.com`). Download a list of supported google domains: [resource.google.domains.json](https://avesapi.com/google-domains.json) | | `gl` | \[Optional] Specify a country code to use for your query. (**Default**: `us` for United States). Download a list of supported 2-letter country codes: [resource.google.countries.json](https://avesapi.com/countries.json) | | `hl` | \[Optional] Specify a language to use for your query. (**Default**: `en` for English). Download a list of all supported languages: [resource.google.languages.json](https://avesapi.com/languages.json) | | `num` | \[Optional] Specify the number of results to show per page. (**Default**: `10` - shows 10 organic results). | | `page` | \[Optional] Specify the number of page between 1-10. (**Default**: `1` - shows the first page). | | `uule` | \[Optional] Returns the location-based search results. | | `output` | \[Optional] Specify which API response format to return: `json` (**default**) or `html`. | ### ### Response and Definitions Your API response strongly depends on your search query and the parameters you choose to make use of. Find below a representative example API response, returned for the query `adidas` and containing some of Google's key response objects. Each available response object will be explained further below in this section. #### Response Object: | Object | Description | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `request` > `success` | Returns `true` if your API request has succeeded. | | `request` > `search_url` | Returns the exact search URL used for your API request. | | `request` > `total_time_taken` | Returns the total processing time as milliseconds of your request. | | `search_parameters` > `query` | Returns the requested search query. | | `search_parameters` > `type` | Returns the type of Google search used for your API request. Possible values: `web` (**default**), `images`, `videos`, `news`, `shopping` | | `search_parameters` > `device` | Returns the name of the device type used for your API request. | | `search_parameters` > `google_domain` | Returns the Google domain used for your request. | | `search_parameters` > `hl` | Returns the content of the `hl` parameter sent along with your API request. | | `search_parameters` > `gl` | Returns the content of the `gl` parameter sent along with your API request. | | `search_parameters` > `page` | Returns the specified numbers of results per page as an integer. | | `search_parameters` > `output` | Returns the output requested along with your API request. (Default: `json` ) | | `result` > `total_results` | Returns the estimated total results about your search term. | | `result` > `top_ads` | Returns as Array if there are ads about your search term | | `result` > `organic_results` | Returns the search results as an object with (`position`, `block_position`, `title`, `link`, `description`) keys in organic\_results array | ####