How to Use the Serplify SERP API: A Beginner's Step-by-Step Guide

You do not need to build a Google scraper to get live search results. With the Serplify SERP API, you send a keyword and a location. Serplify returns the results as clean JSON that your app, script, dashboard, or AI agent can read.

This beginner guide shows the full path. You will create an API key, run a real search in the Serplify Playground, understand 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 include a complimentary $1 SERP API balance. At the standard price of $0.005 per successful SERP, that covers up to 200 successful test searches. A blocked or failed fetch costs nothing.

You do not need a credit card for this first SERP API 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 name, such as local testing or rank tracker.
3. Create the key.
4. Copy it and 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 Run search. 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. Modern result pages contain much more than ten blue links. Advanced format can return local results, People Also Ask questions, images, news, shopping blocks, knowledge panels, and AI features when Google displays them.

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 provides a compatible /v3 surface so you can migrate with a smaller code change. The DataForSEO migration guide explains that path.

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".

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 human message. The error guide lists safe retry behavior.

A practical first project: find a domain’s rank

After your first test, add stop_on_match or track to a search request. This lets the crawler stop after it finds your target and can save the observed position with a label.

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.

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, inspect the structured answer, then use only the fields your product needs. When you are ready for more, the Serplify quickstart covers authentication and code examples in more detail.