Google SERP endpoint
Google rankings.
Structured results.
Send a query to /api/v1/serp and read the organic results as JSON. Monitor where your own domains and brand terms rank, by country and interface language.
organic_results{
"organic_results": [
{
"position": 1,
"title": "Rank tracking tool — example",
"link": "https://example.com/rank-tracker",
"snippet": "Track keyword positions for your own domains."
},
{
"position": 2,
"title": "Another rank tracking tool",
"link": "https://example.net/rank-tracker"
}
]
}Illustrative results from one page of one query.
Send a query, not a Google URL
POST this body to /api/v1/serp with your x-api-key header, the same key the scrape endpoint uses. The API builds the Google URL server-side from these fields.
Only desktop is supported. gl sets the Google country, hl the interface language, and start pages through the results in steps of 10 up to 90, at 10 results per page.
Check the API HTTP status first, then read organic_results and the actual charge in tokens_charged. Positions are the order within the returned page.
{
"q": "rank tracking tool",
"gl": "gb",
"hl": "en",
"start": 0
}Make repeated checks comparable
01 · Fix the query conditions
Record the query, the requested country and language, the result offset and the time of the request. Google personalises results, so compare runs that used the same conditions.
02 · Read where you actually rank
Match your own domain in
organic_results[].linkand store its position. Ads, answer boxes and local packs sit outside the organic list, so a position describes organic results only.03 · Calculate changes yourself
Your application normalises URLs, matches results across runs and calculates position changes. Scheduling, history and reports are not built into the endpoint.
Page further with start to cover the first 100 positions, or use MCP to let an agent run the same query through the google_search tool.
What this endpoint does and does not do
Is this a dedicated search or rank-tracking API?
Yes for the search itself: POST /api/v1/serp runs a Google query and returns structured results. Scheduling, storage and position history stay in your application, and tracking is for your own domains and brand queries under the Acceptable Use Policy.
Can I request results from a specific location?
Pass gl as an ISO 3166-1 alpha-2 country code and hl as the interface language; both apply to the Google search the endpoint runs. Country selection does not provide city-level targeting, and personalisation, cookies and Google experiments can still change what a result page looks like.
How often can I collect results?
Respect Google's terms and request limits, as well as your FineData plan's requests-per-second and token limits. Schedule repeated queries in your own application; the endpoint runs one synchronous search per request.
Will every search engine work?
No. The endpoint targets Google only, and Google can answer a request with a block instead of results, which returns an error and charges nothing. Test the queries and fields you need, and use an official or licensed search API where required.
One request is a flat 10 tokens, reported as tokens_charged; a blocked or empty Google response costs nothing. Track your own domains and brand terms, and follow the Acceptable Use Policy.
Start with a query you already rank for
Check where your domain appears before scaling to more queries.