---
title: "Radius search: every company within a distance, nearest first"
method: GET
path: "/postcodes/nearby"
tags: ["Postcodes"]
---

# Radius search: every company within a distance, nearest first

`GET /postcodes/nearby`

## Request

- Base URL: `https://api.companystack.co.uk`
- URL: `https://api.companystack.co.uk/postcodes/nearby`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Companies registered at every Great Britain postcode within `radius` km (at most 25) of a postcode or a point, nearest first, each with its distance (to the centre of its registered office postcode). Page with `next_cursor` until it is null; a page can hold fewer than `limit` companies in a sparse area. The first page also gives `postcodes_in_radius` and `total` (capped at 10,000). Companies at mass-registration addresses (50 or more companies at one address) and at the Companies House default address are left out unless asked for. Give `postcode`, or `lat` and `lng`. Each page is read within a few seconds: a postcode whose companies cannot be read in that time (some formation agents' postcodes hold tens of thousands) is listed in `postcodes_skipped` and paging carries on after it.

## Query parameters

- `postcode` string
- `lat` number
- `lng` number
- `radius` number
- `limit` integer
- `cursor` string
- `status` 'active' | 'all'
- `sic` string
- `include_mass_registration` 'true' | 'false'
- `include_registrar_default` 'true' | 'false'

## Response `200`

A page of companies, nearest first

- RadiusSearchResult
  - `center` object, required
    - `lat` number, required
    - `lng` number, required
    - `postcode` string
  - `radius_km` number, required
  - `radius_miles` number
  - `order` 'distance'
  - `postcodes_searched` integer: Postcodes whose companies were all read for this page
  - `postcodes_skipped` object[]: Postcodes passed over on this page because their companies could not be read in time (a formation agent's or virtual office's postcode can hold tens of thousands of companies). Their companies are not in the results; paging carries on after them.
    - `postcode` string, required
    - `distance_km` number, required
  - `postcodes_in_radius` integer, nullable: First page only: every Great Britain postcode within the radius (null when it could not be counted in time)
  - `total` integer, nullable: First page only: companies matching, up to 10,000 (null when it could not be counted in time)
  - `total_capped` boolean: First page only: more than 10,000 companies match
  - `limit` integer
  - `filters` object
  - `notice` string
  - `attribution` string
  - `results` object[], required
    - `company_number` string, required
    - `company_name` string, required
    - `company_status` string, nullable
    - `company_category` string, nullable
    - `address_postcode` string, required
    - `sic_code_1` string, nullable
    - `incorporation_date` string, date, nullable
    - `distance_km` number, required: From the point to the centre of the company's registered office postcode
    - `distance_miles` number, required
    - `latitude` number: The postcode's centre
    - `longitude` number
  - `has_more` boolean, required
  - `next_cursor` string, nullable, required: Pass as cursor for the next page; null on the last page. A page can hold fewer than limit companies in a sparse area: keep going until next_cursor is null.

## Other responses

- `400`: Neither postcode nor lat and lng, a radius over the maximum, or an invalid cursor
- `401`: API key missing, malformed or revoked
- `403`: The key's plan does not include this endpoint (`code: plan_upgrade_required`, with `upgrade_url`), the key may not call it, or the key is beyond the plan's key limit after a downgrade (`code: key_limit_exceeded`: the newest keys are paused until keys are deleted or the plan upgraded)
- `404`: The postcode has no location (Northern Ireland, or not in the ONS Postcode Directory)
- `429`: `code: radius_busy`: the account already has 4 radius searches running or waiting; retry after `Retry-After` seconds (or the usual rate limit)
- `503`: `code: radius_busy`: radius search is busy; retry after `Retry-After` seconds

---

[API](https://skmtc.dev/companystack/apis/companystack-api.md) · [All operations](https://skmtc.dev/companystack/apis/companystack-api/llms.txt) · [OpenAPI document](https://skmtc.dev/companystack/apis/companystack-api/revisions/8f3234237d2d?raw)