API Integration (Open API)

This document describes the SerpUpdate Open APIs in detail for customers who want to integrate. You can use these APIs to create keyword rank-checking tasks, look up location and language codes, and automatically receive results via Webhook.

1. Workflow#

1. Call the Get Locations and Get Languages APIs to obtain the locationCode and languageCode.
2. Call the Create Task API with the keyword, location, and language information to receive a taskId.
3. Wait for the system to process. When the result is ready, the system will call Ping Back (Webhook) to your server. Alternatively, you can proactively call the Get Task Result API with the taskId to retrieve the result.

2. Authentication#

All requests must include the API Key in the header. Customers create an account on app.serpupdate.com. An API Key is issued individually for each account.

Required header:
X-API-KEY: <your_api_key>

3. Common Response Structure#

All APIs return the same outer JSON wrapper structure:

Error Codes#

4. Endpoints#

API #1: Create Task#

Creates a task to check keyword rankings on a search engine. Each request can submit multiple keywords at once.

Endpoint: POST /api/v1/open-api/create-task

Request Body

Keyword Object

Response, content.tasks[]

cURL & Response Example

curl --location 'https://app.serpupdate.com/api/v1/open-api/create-task'
  --header 'X-API-KEY: <your_api_key>'
  --header 'Content-Type: application/json'
  --data '{
    "deviceCode": "desktop",
    "locationCode": 2704,
    "languageCode": "vi",
    "searchEngineCode": "GOOGLE",
    "keywords": [
      { "cstmKeywordId": "1", "keyword": "Dien thoai gia re" },
      { "cstmKeywordId": "2", "keyword": "Dien thoai dep" }
    ]
  }'

{
  "errorCode": null,
  "content": {
    "tasks": [
      { "taskId": 4, "cstmKeywordId": "1", "keyword": "Dien thoai gia re", "isSuccess": true },
      { "taskId": 5, "cstmKeywordId": "2", "keyword": "Dien thoai dep", "isSuccess": true }
    ]
  },
  "message": null,
  "isSuccess": true
}

API #2: Get Locations#

Looks up the list of locations supported by the system. Results are paginated and support open search by name.

Endpoint: POST /api/v1/open-api/locations

Request Body

Response, content.content[] (Location Object)

Response Example

{
  "errorCode": null,
  "content": {
    "content": [
      {
        "locationCode": 2704,
        "locationName": "Vietnam",
        "locationCodeParent": null,
        "countryIsoCode": "VN",
        "locationType": "Country"
      }
    ],
    "totalElements": 245,
    "totalPages": 25,
    "numberOfElements": 10
  },
  "message": null,
  "isSuccess": true
}

API #3: Get Languages#

Retrieves the list of supported language codes. No parameters are required.

Endpoint: POST /api/v1/open-api/languages

curl --location --request POST 'https://app.serpupdate.com/api/v1/open-api/languages'
  --header 'X-API-KEY: <your_api_key>'
  --header 'Content-Type: application/json'
  --data ''

API #4: Get Task Result#

Retrieves the SERP ranking results of a created task using its taskId.

Endpoint: POST /api/v1/open-api/task-result

Request Body

You must pass the required parameter: { "taskId": 4 }

Response, content

SerpItem Object (serpItems)

AiOverview Object

Response Example

{
  "errorCode": null,
  "content": {
    "taskId": 4,
    "serpItems": [
      {
        "rank": 1,
        "url": "https://www.thegioididong.com/dtdd",
        "domain": "thegioididong.com",
        "title": "Dien thoai gia re - The Gioi Di Dong",
        "description": "Danh sach dien thoai gia re..."
      }
    ],
    "aiOverview": {
      "markdown": "## Dien thoai gia re tot nhat...",
      "references": [
        { "rank": 1, "url": "https://...", "domain": "...", "title": "...", "description": "..." }
      ]
    }
  },
  "message": null,
  "isSuccess": true
}

API #5: Ping Back (Webhook)#

Instead of continuously polling Get Task Result, you can register an Endpoint (callback URL) with the SerpUpdate team.

As soon as a task completes, the system automatically makes an HTTP POST call to deliver the result to your server.

Payload the System Sends to You

The JSON data sent directly to you has exactly the same structure as the content section of the Get Task Result API.

POST https://your-server.com/your-callback-endpoint
Content-Type: application/json

{
  "taskId": 4,
  "serpItems": [
    {
      "rank": 1,
      "url": "https://...",
      "domain": "...",
      "title": "...",
      "description": "..."
    }
  ],
  "aiOverview": {
    "markdown": "## ...",
    "references": []
  }
}

Handling Example (Java Spring Boot)

@PostMapping("/your-callback-endpoint")
public ResponseEntity receivePingBack(@RequestBody TaskOpenApiResponse payload) {
    // Process the data: payload.getTaskId(), payload.getSerpItems()...
    log.info("Received task result: {}", payload);

    // Return 200 OK so the system records it as successful
    return ResponseEntity.ok().build();
}

See also#

• Rank Checker Overview
• Profile and account settings
• Registering an account
• Rank Checker landing page