API

Search the registers over HTTP

Search all three UK charity registers by name or registration number. JSON out, highest income first, with tidied names and addresses and a logo for each charity.

Keys and limits

You can try the API without a key: each IP address gets 60 requests a minute. For more, ask us for a key and send it with every request:

curl -H 'Authorization: Bearer clk_…' '/v1/charities?q=oxfam'

A key allows 600 requests a minute. X-API-Key: clk_… works too. Keep keys on your server: anyone who can see one can use it. Over the limit you'll get 429 with a Retry-After header.

Logos have their own limit of 300 a minute, and only count when we have to fetch one: logos served from our cache are never limited. Logo URLs work without a key; a server fetching them can add ?key= to use its key's limit.

Responses allow any origin (CORS), so you can call the API from a browser without a key.

One charity

GET /v1/charities/{register}/{regno}
curl '/v1/charities/ew/202918'

Returns {"data": { … }}, or 404 if that register has no such number.

Fields

{
    "register": "ew",
    "regno": "202918",
    "name": "OXFAM",
    "known_as": ["OXFAM GB"],
    "company_number": "00612172",
    "income": 339366903,
    "website": "https://www.oxfam.org.uk/",
    "logo": "https://charities.superlawyer.io/v1/charities/ew/202918/logo",
    "address": {
        "lines": ["2600 John Smith Drive", "Oxford Business Park South", "Oxford"],
        "postcode": "OX4 2JY"
    },
    "display": {
        "name": "Oxfam",
        "address": {
            "lines": ["2600 John Smith Drive", "Oxford Business Park South", "Oxford"],
            "postcode": "OX4 2JY"
        }
    }
}
FieldNotes
registerew, sc or ni.
regnoRegistration number, always a string. Scottish numbers start SC.
nameRegistered name, exactly as the register has it (often in capitals).
known_asOther names the charity uses. Always an array, possibly empty. Searches match these too.
company_numberCompanies House number if the charity is also a company, otherwise null. Always null for Scotland.
incomeLatest reported income in pounds, or null. Results are ordered by it.
websiteThe register's website as a full URL, or null.
logoURL of the site's icon, ready for an <img> (no key needed). null if the charity has no website. It can still 404 when the site has no icon, so handle the image's error event.
addressAs the register has it: lines without blanks, a first line that repeats the name, or the postcode; postcode or null.
displayThe name and address tidied for showing to people: title case, with ordinals (3rd Floor), postcodes and abbreviations such as UK and LTD kept right.

Errors

Errors are JSON with a status code: {"error": {"code": "query_too_short", "message": "…"}}.

StatusCodes
400missing_query, query_too_short, invalid_register, invalid_limit
401invalid_api_key: a key was sent but isn't valid.
404not_found
429rate_limited: wait for Retry-After seconds.

Health

GET /health

When the dataset was built and how many charities each register has, with the date of each register's extract. Live right now:

Loading…

Legacy endpoint

GET /charities/search

The old Laravel service's API, kept byte for byte so existing callers don't need to change. New integrations should use /v1/charities. Returns up to 15 charities, highest income first.

curl '/charities/search?term=oxfam&jurisdiction=all&lower=1'

Parameters

ParamMeaning
termName contains term, or registration number starts with it. Overrides name and reg_no.
nameName contains name.
reg_noRegistration number starts with reg_no. Combined with name using AND.
jurisdictioneng (default), scot (or sco), ni or all. Anything else returns [].
lower1 to title-case names and addresses (OXFAM becomes Oxfam).
keyYour API key, if you have one (or send it as a header, as for /v1). An unrecognised key isn't an error: the request just counts as anonymous.

Matching ignores case and accents, so cafe finds CAFÉ. Charities that have been removed from a register aren't included.

Response

A JSON array. Here's ?term=oxfam&jurisdiction=eng&lower=1:

[
    {
        "regno": 202918,
        "name": "Oxfam",
        "add1": "Oxfam",
        "add2": "2600 John Smith Drive",
        "add3": "Oxford Business Park South",
        "add4": "Oxford",
        "add5": "",
        "postcode": "OX4 2JY",
        "web": "www.oxfam.org.uk",
        "full_address": "Oxfam, 2600 John Smith Drive, Oxford Business Park South, Oxford, OX4 2JY",
        "known_as": [
            "OXFAM GB"
        ],
        "company_number": "00612172",
        "logo_url": "https:\/\/charities.example.com\/charities\/202918\/logo"
    }
]
FieldNotes
regnoRegistration number. A number when jurisdiction=eng, a string otherwise (Scottish numbers start SC).
nameRegistered name.
add1–add5Address lines, without the postcode. Unused lines are "".
postcodeCan be "".
webWebsite as the register has it, often without https://. null if there isn't one.
full_addressThe address lines and postcode, joined with ", ".
known_asOther names the charity uses. Always an array, possibly empty.
company_numberCompanies House number if the charity is also a company, otherwise null. Always null for Scotland (OSCR doesn't publish it). Northern Ireland numbers are as CCNI has them, without the NI prefix or leading zeros.
logo_urlPublic URL of the charity's site icon, ready to drop into an <img>. null if the charity has no website. A URL doesn't promise an icon: it 404s when the site hasn't got one, so handle the image's error event.