Advanced SEO Mapping

SEO Mapping

Build an advanced SEO map for a site and keyword, computed and returned through an asynchronous mapping task.

POSThttps://ai.seovendor.co/api/seogptmapping/

Authenticate every request by passing your secret key as k in the JSON body. Requests are POST with Content-Type: application/json.

Asynchronous endpoint. Call createTask to start a job, poll getTaskStatus with the returned task_id until it reports complete, then fetch the result with getResult. Each stage is documented under Response below.

01Request parameters

Field	Type	Required	Description
action	string	optional	createTask Create an SEO Mapping task.getTaskStatus Get SEO Mapping task status.getResult Get SEO Mapping result.
URL	string	required	Target domain URL.
kw	string	required	Keywords to map, comma or newline separated.
scantype	integer	optional	0 Deep scan — all pages (default)1 Quick scan — top pages only
lang	integer	optional	0 US English1 UK English2 Australian English3 Spanish4 Italian5 French6 German7 Portuguese8 Dutch9 Bulgarian10 Czech11 Danish12 Estonian13 Finnish +26 more options 14 Greek15 Hungarian16 Polish17 Norwegian18 Romanian19 Swedish20 Brazilian Portuguese21 Mexican Spanish22 Colombian Spanish23 Argentine Spanish24 Peruvian Spanish25 Canadian English26 Chilean Spanish27 Bolivian Spanish28 Catalan29 Austrian German30 Canadian French31 Belgian Dutch (Flemish)32 Belgian French33 Scottish English34 Slovak35 New Zealand English36 Irish English37 Swiss German38 Croatian39 Turkish
brand	string	optional	Brand name.
task_id	string	optional	Encrypted task ID from createTask response. Required for getTaskStatus and getResult.
k	string	required	API key sent as k in query string, POST body, JSON body; api_key is also accepted, 11 to 120 characters.

02Response

Every response uses the standard envelope (success, application, action, data, meta, error). The data field for this endpoint is documented below.

successaction: createTask · HTTP 200

200 response example

{
  "success": true,
  "application": "seogptmapping",
  "action": "createTask",
  "data": {
    "task_id": "string",
    "status": "completed",
    "stage": "string",
    "percent_complete": 0
  },
  "meta": {
    "request_id": "req_3f9a7c2e8b41",
    "duration_ms": 1284,
    "upstream_http_code": 200
  },
  "error": null
}

Response schema

successboolean= true

applicationstring= "seogptmapping"

actionstring= "createTask"

dataobject

└─task_idstringEncrypted task identifier. Pass to getTaskStatus and getResult.

└─statusstringTask status. One of: pending, complete, error.

└─stagestringProcessing stage. One of: queued, processing, complete, error.

└─percent_completeintegerCompletion percentage, 0 to 100.

metaobject

└─request_idstring

└─duration_msinteger

└─upstream_http_codeinteger

errornull

successaction: getTaskStatus · HTTP 200

200 response example

{
  "success": true,
  "application": "seogptmapping",
  "action": "getTaskStatus",
  "data": {
    "task_id": "string",
    "status": "completed",
    "stage": "string",
    "percent_complete": 0
  },
  "meta": {
    "request_id": "req_3f9a7c2e8b41",
    "duration_ms": 1284,
    "upstream_http_code": 200
  },
  "error": null
}

Response schema

successboolean= true

applicationstring= "seogptmapping"

actionstring= "getTaskStatus"

dataobject

└─task_idstringEncrypted task identifier. Pass to getTaskStatus and getResult.

└─statusstringTask status. One of: pending, complete, error.

└─stagestringProcessing stage. One of: queued, processing, complete, error.

└─percent_completeintegerCompletion percentage, 0 to 100.

metaobject

└─request_idstring

└─duration_msinteger

└─upstream_http_codeinteger

errornull

successaction: getResult · HTTP 200

200 response example

{
  "success": true,
  "application": "seogptmapping",
  "action": "getResult",
  "data": {
    "task_id": "string",
    "ready": true,
    "status": "completed",
    "stage": "string",
    "percent_complete": 0,
    "message": "The kw field is required.",
    "url": "https://seovendor.co",
    "brand": "SEO Vendor",
    "created_at": "string",
    "result": {
      "<content_type_index>": {
        "type": "ai",
        "data": []
      },
      "5": {
        "kwcannibal": []
      }
    }
  },
  "meta": {
    "request_id": "req_3f9a7c2e8b41",
    "duration_ms": 1284,
    "upstream_http_code": 200
  },
  "error": null
}

Response schema

successboolean= true

applicationstring= "seogptmapping"

actionstring= "getResult"

dataobject

└─task_idstringEncrypted task identifier.

└─readybooleanTrue when processing is complete and results are available, false when still in progress.

└─statusstringTask status. One of: pending, complete, error.

└─stagestringProcessing stage. One of: queued, processing, complete, error.

└─percent_completeintegerCompletion percentage, 0 to 100.

└─messagestringStatus message. Present when ready is false.

└─urlstringWebsite URL that was analyzed.

└─brandstringBrand name used in analysis.

└─created_atstringTask creation timestamp.

└─resultobjectKeyword mapping analysis output. Present when ready is true. Integer-keyed by content type; key 5 holds keyword cannibalization data.

└─<content_type_index>objectMapping results for a content type, keyed by integer index.

└─typestringContent type label.

└─dataarrayMapping block results for this content type.

└─5objectKeyword cannibalization data.

└─kwcannibalarrayDetected keyword cannibalization entries.

metaobject

└─request_idstring

└─duration_msinteger

└─upstream_http_codeinteger

errornull

errorHTTP 400, 401, 502, 503, or 504

error response example

{
  "success": false,
  "application": "seogptmapping",
  "action": "string",
  "data": null,
  "meta": {
    "request_id": "req_3f9a7c2e8b41"
  },
  "error": {
    "code": "invalid_request",
    "message": "The kw field is required.",
    "field": "kw",
    "details": [],
    "apidefinitions": "https://ai.seovendor.co/api/seogptmapping/definitions"
  }
}

Response schema

successboolean= false

applicationstring= "seogptmapping"

actionstring

datanull

metaobject

└─request_idstring

errorobject

└─codestringError code returned by the API.

└─messagestringHuman-readable error message.

└─fieldstringInput field associated with the error.

└─detailsarrayAdditional error details.

└─apidefinitionsstringPublic API definitions URL.

POST /api/seogptmapping/

curl -X POST "https://ai.seovendor.co/api/seogptmapping/" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "k": "[API KEY]",
  "action": "createTask",
  "URL": "https://seovendor.co",
  "kw": "white label seo",
  "brand": "SEO Vendor"
}'
<?php
$ch = curl_init("https://ai.seovendor.co/api/seogptmapping/");

$payload = [
    "k" => "[API KEY]",
    "action" => "createTask",
    "URL" => "https://seovendor.co",
    "kw" => "white label seo",
    "brand" => "SEO Vendor",
];

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Accept: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
const response = await fetch("https://ai.seovendor.co/api/seogptmapping/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    k: "[API KEY]",
    action: "createTask",
    URL: "https://seovendor.co",
    kw: "white label seo",
    brand: "SEO Vendor",
  })
});

const data = await response.json();
console.log(data);
import requests

url = "https://ai.seovendor.co/api/seogptmapping/"

payload = {
    "k": "[API KEY]",
    "action": "createTask",
    "URL": "https://seovendor.co",
    "kw": "white label seo",
    "brand": "SEO Vendor",
}

headers = {
    "Content-Type": "application/json",
    "Accept": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)

← PreviousSEO Strategist Next →RankLens

SEO Vendor API

Overview API Home seovendor.co