API Reference

The UniversityDB Resolution API lets you resolve messy university names and course titles to canonical UK education records.

Base URL: https://universitydb.io

Authentication

All API requests require a Bearer token in the Authorization header. You can generate an API key from the API dashboard.

Authorization: Bearer udb_live_xxxxx

API keys use the prefix udb_live_ for production and udb_test_ for testing. Test keys return mocked data and do not count toward your quota.

POST /api/v1/resolve

Resolve a university name and/or course title to their canonical records. Supports fuzzy matching, common aliases (e.g. "UCL", "Imperial"), and returns confidence scores for each match.

Request Body

interface ResolveRequest {
  /** University name, alias, or abbreviation */
  university?: string;
  /** Course title or partial name */
  course?: string;
  /** Filter by course level: "Undergraduate" | "Postgraduate" */
  level?: string;
}

At least one of university or course is required.

Examples

cURL

curl -X POST https://universitydb.io/api/v1/resolve \
  -H "Authorization: Bearer udb_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"university": "Imperial", "course": "MSc Computing"}'

JavaScript

const res = await fetch("https://universitydb.io/api/v1/resolve", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    university: "Imperial",
    course: "MSc Computing"
  })
});

const data = await res.json();

Python

import requests

response = requests.post(
    "https://universitydb.io/api/v1/resolve",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "university": "Imperial",
        "course": "MSc Computing"
    }
)

data = response.json()

Response

{
  "university": {
    "id": 42,
    "name": "Imperial College London",
    "location": "London",
    "confidence": 0.95
  },
  "course": {
    "id": 1847,
    "title": "Computing (Machine Learning)",
    "level": "Postgraduate",
    "confidence": 0.82
  },
  "query_id": "550e8400-e29b-41d4-a716-446655440000"
}

Confidence Scoring

Each match includes a confidence score between 0 and 1:

Score	Match Type	Description
1.0	Exact	Input matches the canonical name exactly
0.9 – 0.99	Alias	Input matches a known alias (e.g. "UCL" → "University College London")
0.5 – 0.89	Fuzzy	Input partially matches via fuzzy string comparison
< 0.5	Low	Weak match — consider prompting the user to verify

Rate Limits

Plan	Quota	Reset
Free	100 requests/month	1st of each month, 00:00 UTC
Pro	Custom	Contact us

When you exceed your quota, the API returns 429 Too Many Requests with a body indicating when your quota resets:

{
  "error": "rate_limit_exceeded",
  "message": "Monthly quota exceeded. Resets at 2026-06-01T00:00:00Z.",
  "reset_at": "2026-06-01T00:00:00Z"
}

Error Codes

Status	Error Code	Meaning
400	invalid_request	Missing or malformed request body. At least one of `university` or `course` is required.
401	unauthorized	Missing or invalid API key.
404	not_found	No match found for the given query.
429	rate_limit_exceeded	Monthly request quota exceeded. Check the `reset_at` field.
500	internal_error	Unexpected server error. Retry or contact support.

All error responses follow a consistent format:

{
  "error": "error_code",
  "message": "A human-readable description of the problem."
}

Response Fields

A successful 200 response includes the following top-level fields. Fields are omitted if the corresponding input was not provided.

`university` object

Field	Type	Description
id	number	Unique university identifier in UniversityDB
name	string	Canonical university name
location	string	Primary campus city
confidence	number	Match confidence score (0 – 1)

`course` object

Field	Type	Description
id	number	Unique course identifier in UniversityDB
title	string	Canonical course title
level	string	"Undergraduate" or "Postgraduate"
confidence	number	Match confidence score (0 – 1)

`query_id`

A UUID v4 string uniquely identifying this resolution request. Include this when contacting support about a specific query.