HTTP API
Submit search
Run a Google Search and wait for structured results.
POST /serp
Runs one Google Search synchronously. The connection stays open until the page is fetched or the timeout is reached.
Request
Content-Type: application/json
| Field | Type | Required | Description |
|---|---|---|---|
url | string | yes | Full https://www.google.*/search?... URL |
keyword | string | yes | Short label for the query (for your logs and support) |
country | "us" | "de" | "jp" | yes | Target market |
timeoutMs | number | no | Max wait in ms (default 85000, max 95000) |
includeHtml | boolean | no | Include raw HTML in the response (default false) |
Example
curl -sS -X POST "https://serp.lexis-solutions-apis.com/serp" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.google.com/search?q=weather+today&hl=en&gl=us&pws=0",
"keyword": "weather today",
"country": "us"
}'Response 200 (success)
{
"success": true,
"code": "ok",
"keyword": "weather today",
"country": "us",
"url": "https://www.google.com/search?q=...",
"finalUrl": "https://www.google.com/search?q=...",
"httpStatus": 200,
"durationMs": 8421,
"organicCount": 10,
"adCount": 0,
"queryEchoed": true,
"topOrganicUrls": ["https://example.com/..."],
"results": [
{
"searchQuery": {
"term": "weather today",
"url": "https://www.google.com/search?q=...",
"device": "DESKTOP",
"page": 1,
"type": "SEARCH",
"domain": "google.com",
"countryCode": "US",
"languageCode": "en",
"locationUule": null
},
"relatedQueries": [{ "title": "weather forecast", "url": "https://www.google.com/search?..." }],
"paidResults": [],
"paidProducts": [],
"organicResults": [
{
"title": "Example result",
"url": "https://example.com/",
"displayedUrl": "example.com",
"description": "Snippet text…",
"emphasizedKeywords": [],
"siteLinks": [],
"productInfo": {},
"type": "organic",
"position": 1
}
],
"peopleAlsoAsk": []
}
],
"html": null,
"message": null
}Response 502 (fetch failed)
{
"success": false,
"code": "blocked",
"message": "The search page was blocked or showed a verification challenge.",
"keyword": "weather today",
"country": "us",
"url": "https://www.google.com/search?q=...",
"finalUrl": null,
"httpStatus": 200,
"durationMs": 3200,
"organicCount": null,
"adCount": null,
"queryEchoed": null,
"topOrganicUrls": [],
"html": null
}code is one of ok, blocked, timeout, or error.
Response 504
The job did not finish before timeoutMs.
Errors
| Status | Body | Cause |
|---|---|---|
| 400 | { "error": "missing fields" } | Required JSON fields absent |
| 400 | { "error": "url must be a google.com/search URL" } | URL failed validation |
| 401 | { "error": "unauthorized" } | Missing or invalid API key |