API Consumer Guide

This guide shows how to retrieve KE-WP and KE-GO mappings programmatically. The base URL is /api/v1. All endpoints are read-only and require no authentication. See the Interactive API Docs for an in-browser explorer.

Endpoints Overview

Endpoint	Description
GET /api/v1/mappings	List KE-WP mappings (filterable, paginated)
GET /api/v1/mappings/{uuid}	Single KE-WP mapping by UUID
GET /api/v1/go-mappings	List KE-GO mappings (filterable, paginated)
GET /api/v1/go-mappings/{uuid}	Single KE-GO mapping by UUID

Python (requests) Examples

Install: pip install requests

1. Basic retrieval -- high confidence KE-WP mappings

base = "https://your-server.org/api/v1"
resp = requests.get(f"{base}/mappings", params={"confidence_level": "High", "per_page": 50})
mappings = resp.json()["data"]

2. Filter by KE ID

resp = requests.get(f"{base}/mappings", params={"ke_id": "KE 55"})

3. Paginate all results

url, params = f"{base}/mappings", {"confidence_level": "High"}
while url:
    resp = requests.get(url, params=params)
    data = resp.json()
    process(data["data"])
    url = data["pagination"]["next"]
    params = {}

4. CSV download

resp = requests.get(f"{base}/mappings", params={"format": "csv"})
with open("ke_wp_mappings.csv", "wb") as f:
    f.write(resp.content)

5. KE-GO mappings

resp = requests.get(f"{base}/go-mappings", params={"ke_id": "KE 55", "confidence_level": "High"})
go_mappings = resp.json()["data"]

R (httr2) Examples

Install: install.packages("httr2")

1. Basic retrieval -- high confidence KE-WP mappings

library(httr2)
resp <- request("https://your-server.org/api/v1/mappings") |>
  req_url_query(confidence_level = "High", per_page = 50) |>
  req_perform() |>
  resp_body_json()
mappings <- resp$data

2. Filter by KE ID

library(httr2)
resp <- request("https://your-server.org/api/v1/mappings") |>
  req_url_query(ke_id = "KE 55") |>
  req_perform() |>
  resp_body_json()

3. Paginate all results using req_perform_iterative

library(httr2)
req <- request("https://your-server.org/api/v1/mappings") |>
  req_url_query(per_page = 200)
all_resps <- req_perform_iterative(req, function(resp, req) {
  nxt <- resp_body_json(resp)$pagination$`next`
  if (is.null(nxt)) return(NULL)
  req |> req_url(nxt)
})
all_data <- lapply(all_resps, \(r) resp_body_json(r)$data) |> do.call(c, args = _)

4. CSV download

resp <- request("https://your-server.org/api/v1/mappings") |>
  req_url_query(format = "csv") |>
  req_perform()
df <- readr::read_csv(rawToChar(resp_body_raw(resp)))

5. KE-GO mappings

resp <- request("https://your-server.org/api/v1/go-mappings") |>
  req_url_query(ke_id = "KE 55", confidence_level = "High") |>
  req_perform() |>
  resp_body_json()
go_mappings <- resp$data

Rate Limit Policy

• When the limit is exceeded the API returns HTTP 429 Too Many Requests.
• The response includes a Retry-After header containing an integer value (seconds) to wait before retrying.
• In multi-process deployments (e.g. multiple Gunicorn workers) the in-memory rate limiter is per-worker; effective per-IP limit may be higher than 100 req/hour.

Python -- handling rate limits politely

import time

resp = requests.get(url, params=params)
if resp.status_code == 429:
    wait = int(resp.headers.get("Retry-After", 60))
    time.sleep(wait)
    resp = requests.get(url, params=params)  # retry once
time.sleep(0.05)  # ~20 requests/second courtesy pause between requests

Interactive Docs

Browse and test all endpoints interactively at /api/docs.