API Documentation

Base URL

All endpoints are relative to your backend base URL.

Common Headers

Header Name	Required	Description
x-access-key	Yes	Your API key for authentication
Accept-Encoding	Yes	Must contain gzip or br
X-Request-Id	No	Optional request ID; one will be generated automatically if not provided

Endpoints

Google Web Search

Proxies a Google web search request. Enjoy a 20% discount for requesting 10 pages of data in a single batch. The minimum price is $0.064 per 1,000 requests.

Endpoint: GET /request/google/web

Query Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	Google search URL (must contain google.com, path /search, and q parameter)
pageCount	int	No	10	Number of pages to retrieve
isMobile	boolean	Yes	-	true for mobile search results, false for desktop

Example Request:

GET /request/google/web?url=https%3A%2F%2Fwww.google.com%2Fsearch%3Fq%3Djustsearch&pageCount=10&isMobile=false
x-access-key: your-api-key
Accept-Encoding: gzip

Success Response:

• Status: 200 OK
• Content-Type: text/plain;charset=UTF-8
• Body: Raw HTML content from Google search

---

Google Any Request

Proxies any Google URL request, also supports AJAX URL format.

Endpoint: GET /request/google/any

Query Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	Any Google URL (domain must be google.com)
isMobile	boolean	Yes	-	true for mobile user agent, false for desktop

Example Request:

GET /request/google/any?url=https%3A%2F%2Fwww.google.com&isMobile=false
x-access-key: your-api-key
Accept-Encoding: gzip

Success Response:

• Status: 200 OK
• Content-Type: text/plain;charset=UTF-8
• Body: Raw HTML content from the requested URL

---

Error Responses

All error responses have the following structure:

{
  "code": 400,
  "message": "Error message",
  "requestId": "unique-request-id"
}

Common Error Codes

HTTP Status	Code	Message	Description
400	400	URL domain must contain 'google'	The provided URL's domain does not include 'google'
400	400	URL path must be '/search'	The URL path is not '/search' (for /google/web endpoint)
400	400	URL must contain 'q' parameter	The URL is missing the search query parameter 'q'
400	400	Invalid URL format	The URL is malformed
400	400	request header must contain Accept-Encoding: gzip or br	Missing or invalid Accept-Encoding header
403	403	Invalid API Key	The provided x-access-key is invalid
403	403	Insufficient balance	Your account balance is insufficient to process this request
429	429	Too Many Requests	You have exceeded the rate limit
503	503	Service Unavailable	The service is temporarily unavailable

---

Request Flow

1. Request ID Interceptor (Order 1): Generates a unique X-Request-Id and attaches it to the response.
2. Access Limit Interceptor (Order 2): Enforces rate limiting based on x-access-key.
3. Force Gzip Header Interceptor (Order 3): Validates that Accept-Encoding includes gzip or br.
4. Controller Logic: Validates API key, checks/deducts balance, proxies the request.