How to use a SERP API: your first Serplify request, step by step

A SERP API is a service that runs a Google search for you and returns the results page as data. To use one, you send a keyword, a location and a language with your API key. You get back JSON that your app, script, dashboard or AI agent can read.

The steps below use the Serplify SERP API. You will create an API key, run a real search in the Playground, read the response and copy the request into your own project. The first test takes about five minutes.

What you need before you start

You need a Serplify account and an active API key. New accounts get $1 of free SERP API credit. At $0.005 per successful SERP, that covers about 200 test searches.

A live request is billed only when the SERP comes back, so a blocked or failed fetch costs nothing. Queued tasks are billed when you submit them. Top-up sizes are on the pricing page.

You do not need a credit card for this first test. You also do not need a server, a proxy or a scraping library.

Step 1: create your API key

Sign in at app.serplify.io, then open API keys in the left menu.

1. Select New API key.
2. Give it a clear label, such as local testing or rank tracker.
3. Pick the live prefix for real searches, or test for development.
4. Create the key, then copy it right away. It is shown only once.
5. Store it in a password manager or secret store.

An API key works like a password for your Serplify account. Do not paste it into a public GitHub file, browser-side JavaScript, screenshot, or support message. On a server, keep it in an environment variable such as SERPLIFY_API_KEY.

If you use several apps, give each app its own key. Separate keys make usage easier to trace and let you revoke one integration without breaking the others.

Step 2: run your first live Google search

Open Playground in the Serplify app. The Playground sends a real request to POST /v1/serp/search, so the result matches what your code will receive later.

Use these starter values:

Choose your API key and select Send request. Most live searches finish in a few seconds. You can then switch between three useful views:

• Parsed shows the organic results in a simple table.
• JSON shows the full API response.
• cURL gives you a command you can paste into a terminal.

Start with advanced format. A results page holds far more than organic links. Advanced format can return local results, People Also Ask questions, images, news, shopping blocks, knowledge panels and AI Overviews when Google shows them. SERP features explained describes each block.

Step 3: copy the request into your own project

The Playground builds the request for you. A basic cURL version looks like this:

curl -X POST https://api.serplify.io/v1/serp/search \
  -H "Authorization: Bearer live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "coffee shops",
    "location": { "name": "London,England,United Kingdom" },
    "language": { "code": "en" },
    "device": "mobile",
    "format": "advanced",
    "depth": 20
  }'

Replace live_your_key_here with your key. For production code, read the key from a secret or environment variable instead of typing it into the file.

The native /v1 API is the best choice for a new integration. It uses normal HTTP status codes and a flat response shape. If you already use DataForSEO, Serplify also serves DataForSEO-compatible /v3 endpoints, so you can switch by changing the base URL and key. The DataForSEO migration guide explains that path, and our list of DataForSEO alternatives compares the options.

Step 4: understand the response

Every successful native response has four top-level parts:

{
  "request_id": "req_123",
  "status": "ok",
  "meta": {
    "time": 1.02,
    "cost": 0.005,
    "currency": "USD"
  },
  "data": {
    "keyword": "coffee shops",
    "items_count": 38,
    "feature_types": ["local_pack", "organic", "people_also_ask"],
    "items": []
  }
}

Here is what each part means:

• request_id is the ID to include if you ever contact support about this search.
• status is ok when the result is ready or accepted when a slower search continues as an async task.
• meta shows the processing time and exact cost.
• data holds the keyword, location, device, feature list, and result items.

Each item has a type. For example, an organic result uses type: "organic", while a local result may use type: "local_pack". We explain the item shapes in how we parse SERP features into JSON.

Two rank fields are easy to mix up:

• rank_absolute is the item’s position across the whole page, including different feature types.
• rank_group is its position inside its own group. An organic result can be organic result number one while appearing below an ad or local pack.

That difference matters in rank trackers. A user sees the whole page, not an organic-only list. The complete field guide lives in the response-format documentation.

Step 5: choose the right format and depth

Use the smallest response that answers your question.

Use standard format when:

• You only need organic links, ads, and featured snippets.
• You want a smaller response.
• Your existing pipeline expects classic search results.

Use advanced format when:

• You monitor local packs, People Also Ask, images, news, or AI Overviews.
• You study SERP layout changes.
• You need the most complete picture of what a searcher saw.

Use HTML format when:

• You maintain your own parser.
• You need the captured page for an audit or replay.
• A special result type requires custom extraction.

Depth ranges from 10 to 100. A depth of 10 is enough for a quick first-page check. Use a deeper search when you track a page that may rank on page two or later. Deeper searches return more data, so do not request 100 results by habit.

Step 6: handle the three common outcomes

A reliable integration plans for more than 200 OK.

200 OK: the result is ready

Read data.items and store the fields you need. Keep request_id, fetched_at, the location, language, and device with the result. Those fields make later comparisons trustworthy.

202 Accepted: the search is still running

A live request can take longer than the synchronous time window. Serplify then returns a task_id and status_url. Poll that URL until the result is ready. The task is charged once; fetching the finished result is free.

An error response

Common examples include an invalid location, an empty balance, or a search that could not be completed. Check the HTTP status and the error code instead of matching the message text. The error guide lists safe retry behavior.

A practical first project: find a domain’s rank

After your first test, add a track block to a search request. Serplify then saves your domain’s position each time that search runs:

{
  "keyword": "best running shoes",
  "location": { "code": 2840 },
  "language": { "code": "en" },
  "track": { "target": "nike.com", "label": "nike-brand" }
}

The response then includes a tracked_rank block with both rank numbers. Reading the saved history back with GET /v1/serp/track is free. The rank tracking docs cover the details.

For a rank tracker, always store these dimensions with the position:

• keyword;
• target domain or URL;
• location;
• language;
• device;
• search engine domain;
• capture time.

Without those details, two rank numbers may look comparable when they came from different searches. A mobile result in London is not the same measurement as a desktop result across the whole United Kingdom. Our guide on how to check Google rankings explains why location and device change the number.

Mistakes to avoid

• Do not expose the API key in browser code. Send requests from your server.
• Do not call every result an organic rank. Check the item type and both rank fields.
• Do not mix locations or devices in one trend line. Keep each measurement set consistent.
• Do not retry every error at once. Retry temporary server errors with a delay; fix invalid requests before trying again.
• Do not request deep results when you only need page one. Smaller requests are easier to store and inspect.

Your five-minute checklist

1. Create and safely store an API key.
2. Open the Playground.
3. Search one real keyword with a precise location.
4. Read the Parsed and JSON views.
5. Copy the cURL request.
6. Check meta.cost, feature_types, and the rank fields.
7. Move the request into server-side code.

That is the whole first loop: ask for a live Google SERP, read the structured answer, then keep only the fields your product needs. The Serplify quickstart has Node.js and Python versions of the same call. When you are ready to check thousands of keywords on a schedule, read how to track rankings in bulk. To let an AI assistant such as Claude Desktop or Cursor run the same search, build a Google search MCP server around this call.