Quickstart - The Data City

This guide takes you from zero to a working classification in three steps.

1. Create an account

A work email address. Consumer providers (Gmail, Outlook, Hotmail, Yahoo, iCloud, Proton) and known disposable-email domains are rejected.
A password of 8–128 characters.
To accept the Terms & Conditions. Signing up without this returns 422.

New accounts start on the free tier with a limited request quota for evaluation. See Rate limits & quotas for details.

2. Get an access token

Exchange your email and password for a JWT using the token endpoint. The token is valid for 8 days. Cache it rather than requesting one per call, because this endpoint is rate limited to 5 requests per minute.

curl -sS -X POST "https://instant-classification-api.thedatacity.com/api/v1/login/access-token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=you@yourcompany.com&password=YOUR_PASSWORD"

import httpx

resp = httpx.post(
    "https://instant-classification-api.thedatacity.com/api/v1/login/access-token",
    data={"username": "you@yourcompany.com", "password": "YOUR_PASSWORD"},
)
token = resp.json()["access_token"]

const resp = await fetch(
  "https://instant-classification-api.thedatacity.com/api/v1/login/access-token",
  {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: "username=you@yourcompany.com&password=YOUR_PASSWORD",
  }
);
const { access_token } = await resp.json();

A successful response looks like this:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Treat your access token like a password. Don’t check it into source control or include it in frontend bundles.

3. Classify a company

Send a POST to /api/v1/instantClassification with either Text (a company description) or Website (a URL) — not both. Include your token in the Authorization header.

Send one of Text or Website per request. The API forwards both if you send both, which can produce unreliable results.

Set your client timeout to at least 120 seconds on this endpoint. Classification can take over a minute when the engine is slow, because the API retries upstream before giving up. Most “API errors” reported to support turn out to be short client timeouts.

Classify by description:

curl -sS -X POST "https://instant-classification-api.thedatacity.com/api/v1/instantClassification" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"Text": "Software development and consulting services"}'

resp = httpx.post(
    "https://instant-classification-api.thedatacity.com/api/v1/instantClassification",
    headers={"Authorization": f"Bearer {token}"},
    json={"Text": "Software development and consulting services"},
)
data = resp.json()

const resp = await fetch(
  "https://instant-classification-api.thedatacity.com/api/v1/instantClassification",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${access_token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      Text: "Software development and consulting services",
    }),
  }
);
const data = await resp.json();

Or classify by website:

curl -sS -X POST "https://instant-classification-api.thedatacity.com/api/v1/instantClassification" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"Website": "https://example.com"}'

resp = httpx.post(
    "https://instant-classification-api.thedatacity.com/api/v1/instantClassification",
    headers={"Authorization": f"Bearer {token}"},
    json={"Website": "https://example.com"},
)
data = resp.json()

const resp = await fetch(
  "https://instant-classification-api.thedatacity.com/api/v1/instantClassification",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${access_token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ Website: "https://example.com" }),
  }
);
const data = await resp.json();

A successful response includes classifications across all taxonomies:

{
  "RTICs": [
    {
      "Code": "10.01.01",
      "Description": "Software Development",
      "Score": 0.92,
      "WordsMatched": 3
    }
  ],
  "RSICs": [
    {
      "Code": "62012",
      "Description": "Business and domestic software development",
      "Score": 0.88
    }
  ],
  "RNAICs": [
    {
      "Code": "541511",
      "Description": "Custom Computer Programming Services",
      "Score": 0.85
    }
  ],
  "SICs": [
    {
      "Code": "62012",
      "Description": "Business and domestic software development"
    }
  ],
  "SimilarCompanies": [
    {
      "CompanyNumber": "12345678",
      "CompanyName": "Example Software Ltd",
      "Website": "https://example-software.co.uk",
      "Similarity": 0.91
    }
  ],
  "TotalWordsProcessed": 5,
  "ProcessingTimeMs": 342,
  "Website": "https://example.com",
  "Description": "Software development and consulting services"
}

What’s next

Authentication

Token lifetime and password recovery.

Errors

What each error code means and how to handle it.

Rate limits & quotas

Free-tier quota and paid rate limits.

Endpoint reference

Full request/response schema with the interactive playground.

​1. Create an account

​2. Get an access token

​3. Classify a company

​What’s next

Authentication

Errors

Rate limits & quotas

Endpoint reference

1. Create an account

2. Get an access token

3. Classify a company

What’s next