API Documentation

Public REST API for accessing AI displacement risk data. Base URL: https://api.takeovertracker.com/api/v1

Occupations

GET/occupations

List occupations with optional search.

Parameters

q(string)— Search query for title

limit(int)— Results per page (1-200, default 50)

offset(int)— Pagination offset

Response

{
  "data": [
    {
      "id": 1,
      "soc_code": "15-1252.00",
      "title": "Software Developers",
      "slug": "software-developers",
      "job_zone": 4,
      "description": "..."
    }
  ],
  "count": 50,
  "limit": 50,
  "offset": 0
}

GET/occupations/{soc_code}

Get full occupation detail including risk score, labor data, and protective factors.

Response

{
  "id": 1,
  "soc_code": "15-1252.00",
  "title": "Software Developers",
  "labor_data": { "median_annual_wage": 132270, ... },
  "risk_score": { "final_score": 52.3, "risk_tier": "high", ... },
  "protective_factors": { "creativity": 0.68, ... }
}

GET/occupations/{soc_code}/tasks

Get task breakdown with AI capability scores and risk scores per task.

Response

{
  "soc_code": "15-1252.00",
  "title": "Software Developers",
  "tasks": [
    {
      "description": "Analyze user needs...",
      "task_category": "non_routine_analytical",
      "ai_capability_score": 65.0,
      "task_risk_score": 53.0,
      "time_fraction": 0.15
    }
  ]
}

GET/occupations/{soc_code}/risk

Get risk score, protective factors, and skill gaps for an occupation.

Response

{
  "soc_code": "15-1252.00",
  "title": "Software Developers",
  "risk_score": {
    "final_score": 52.3,
    "risk_tier": "high",
    "displacement_year_low": 2032,
    "displacement_year_high": 2035,
    "confidence": "high"
  },
  "protective_factors": { ... },
  "skill_gaps": [ ... ]
}

GET/occupations/{soc_code}/votes

Get community vote statistics for an occupation.

Response

{
  "total": 342,
  "agree": 267,
  "too_high": 51,
  "too_low": 24,
  "agree_pct": 78.1,
  "too_high_pct": 14.9,
  "too_low_pct": 7.0
}

Industries

GET/industries

List industries, optionally filtered by NAICS hierarchy level.

Parameters

level(int)— NAICS level: 2 (sector), 3 (subsector), 4 (industry group)

Response

{
  "data": [
    {
      "id": 1,
      "naics_code": "51",
      "title": "Information",
      "level": 2
    }
  ],
  "count": 20
}

GET/industries/{naics_code}

Get industry detail with occupations in the industry.

Response

{
  "naics_code": "51",
  "title": "Information",
  "occupations": [ ... ]
}

Personal Assessment

POST/displacement/assess

Compute a personalized displacement risk score based on personal factors.

Parameters

soc_code(string)— O*NET SOC code

personal_factors(object)— Personal factor key-value pairs

Response

{
  "soc_code": "15-1252.00",
  "title": "Software Developers",
  "base_score": 52.3,
  "personalized_score": 44.1,
  "total_adjustment": -8.2,
  "adjustments": {
    "ai_proficiency": -8.0,
    "years_experience": -3.0,
    "client_relationship_depth": -6.0,
    ...
  },
  "risk_tier": "medium"
}

GET/displacement/factors

Get all available personal factor options and their score adjustments.

Response

{
  "factors": {
    "years_experience": [
      { "value": "0-2", "label": "0-2 years", "adjustment": 5.0 },
      { "value": "20+", "label": "20+ years", "adjustment": -5.0 }
    ],
    ...
  }
}

Code Examples

curl

# Search occupations
curl "https://api.takeovertracker.com/api/v1/occupations?q=software&limit=5"

# Get risk score
curl "https://api.takeovertracker.com/api/v1/occupations/15-1252.00/risk"

# Personalized assessment
curl -X POST "https://api.takeovertracker.com/api/v1/displacement/assess" \
  -H "Content-Type: application/json" \
  -d '{"soc_code":"15-1252.00","personal_factors":{"ai_proficiency":"advanced"}}'

JavaScript (fetch)

const BASE = "https://api.takeovertracker.com/api/v1";

// Search occupations
const res = await fetch(`${BASE}/occupations?q=nurse&limit=10`);
const data = await res.json();

// Get risk details
const risk = await fetch(`${BASE}/occupations/29-1141.00/risk`);
const riskData = await risk.json();
console.log(riskData.risk_score.final_score);

Python (requests)

import requests

BASE = "https://api.takeovertracker.com/api/v1"

# Search
r = requests.get(f"{BASE}/occupations", params={"q": "accountant"})
occupations = r.json()["data"]

# Risk score
r = requests.get(f"{BASE}/occupations/13-2011.00/risk")
print(r.json()["risk_score"]["final_score"])

Embed Widget

Embed a compact risk card on your site using an iframe:

<iframe
  src="https://takeovertracker.com/embed/software-developers"
  width="320"
  height="280"
  frameborder="0"
  style="border-radius: 12px; border: 1px solid #e5e7eb;"
></iframe>

Replace software-developers with any occupation slug.