Quickstart

1. Mint a key. In the dashboard open Developers → API Keys and press New key. Copy the secret when it is shown; it starts with sk_live_ or sk_test_ and is never shown again.

2. Run a search. Replace sk_live_your_key with your key.

   cURL

   curl -G "https://api.serpresult.com/v1/query" \
     -H "Authorization: Bearer sk_live_your_key" \
     --data-urlencode "query=serp api" \
     --data-urlencode "target=google_search" \
     --data-urlencode "geo=us" \
     --data-urlencode "num=3"

   Node

   const url = new URL("https://api.serpresult.com/v1/query");
   url.search = new URLSearchParams({
     query: "serp api",
     target: "google_search",
     geo: "us",
     num: "3",
   }).toString();
   
   const response = await fetch(url, {
     headers: { Authorization: "Bearer sk_live_your_key" },
   });
   if (!response.ok) throw new Error(`Search failed: ${response.status}`);
   
   const { results } = await response.json();
   for (const row of results.organic) {
     console.log(row.position, row.domain, row.url);
   }

   Python

   import requests
   
   response = requests.get(
       "https://api.serpresult.com/v1/query",
       headers={"Authorization": "Bearer sk_live_your_key"},
       params={
           "query": "serp api",
           "target": "google_search",
           "geo": "us",
           "num": 3,
       },
       timeout=30,
   )
   response.raise_for_status()
   
   for row in response.json()["results"]["organic"]:
       print(row["position"], row["domain"], row["url"])

3. Read the response. A 200 carries the organic results in rank order.

   {
     "id": "qry_bbadb104fad74005a996dcd379a072cb",
     "target": "google_search",
     "query": "serp api",
     "geo": "us",
     "locale": "en-us",
     "page": 1,
     "results": {
       "organic": [
         {
           "position": 1,
           "title": "Search engine results page - Wikipedia",
           "url": "https://en.wikipedia.org/wiki/Search_engine_results_page",
           "domain": "wikipedia.org",
           "snippet": "A search engine results page (SERP) is a webpage that is displayed by a search engine in response to a query by a user."
         },
         {
           "position": 2,
           "title": "In-depth guide to how Google Search works",
           "url": "https://developers.google.com/search/docs/fundamentals/how-search-works",
           "domain": "google.com",
           "snippet": "Google Search is a fully-automated search engine that uses software known as web crawlers that explore the web regularly to find pages to add to our index."
         },
         {
           "position": 3,
           "title": "SERP Features - What They Are & How to Rank For Them - Moz",
           "url": "https://moz.com/learn/seo/serp-features",
           "domain": "moz.com",
           "snippet": "A SERP feature is any result on a Google Search Engine Results Page (SERP) that is not a traditional organic result."
         }
       ]
     }
   }

   The response also carries X-Credits-Used, the three X-RateLimit-* headers and X-Request-Id. Understanding results explains each field.

That call cost 1 credit

Every served search costs one credit. A request rejected for a bad parameter costs nothing.

Next steps

• Authentication: live and test keys
• Targets & geo: what each of the six engines supports, the 193 countries
• GET /v1/query: every parameter and response
• POST /v1/bulk: up to 50 searches in one request