Endpoints

At a glance

Four endpoints, all under https://api.topicloops.com/v1:

GET /account

Reads your account's current credit status. Takes no parameters, and returns the credits left on your account — the number that replenishes on the 1st of each month while your subscription is active.

{
  "status": "success",
  "data": {
    "credits": 14500
  }
}

POST /topic-graphs

Creates a topic graph and schedules it. Because a graph can take up to a minute to build in edge cases, this endpoint does not wait for the result: it returns an id immediately, and you poll for the data.

The body takes three fields, all required:

• keyword — the keyword to map. Under 80 characters, and lowercased for you.
• country_code — the country to fetch SERPs and metrics for.
• language_code — the language to fetch them in.

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "keyword": "camping",
       "country_code": "us",
       "language_code": "en"
     }' \
     https://api.topicloops.com/v1/topic-graphs

The response gives you the job id and a status of processing:

{
  "status": "success",
  "data": {
    "id": "67b1b0680bbe25ee376a05b2",
    "status": "processing"
  }
}

GET /topic-graphs/:id

Reads a job back, using the id from the create call. Poll it until status leaves processing: most jobs finish in under ten seconds. Polling is free and generously limited, but it is still metered, so prefer a short interval over a tight loop.

While the job is processing, topic_graph is null. On succeeded it holds the graph: a root node whose children nest recursively, each node carrying a label.

{
  "id": string
  "created_at": Date
  "parameters": {
    "country_code": string
    "language_code": string
    "keyword": string
  }
  "status": "processing" | "failed" | "succeeded"
  "topic_graph": {
    "label": string
    "children": {
      "label": string
      "children": ...  // Recursive
    }[]
  } | null
}

A failed status is terminal — retry by creating a new job rather than polling on.

GET /locations

The lookup for the two code parameters above. It returns every supported country and language with a human-readable label, so you can validate input or build a picker without hardcoding a list.

{
  "country_codes": [
    { "country_code": "dz", "label": "Algeria" },
    { "country_code": "ao", "label": "Angola" },
    ...
  ],
  "language_codes": [
    { "language_code": "al", "label": "Albanian" },
    { "language_code": "ar", "label": "Arabic" },
    ...
  ]
}