Skip to main content
API docs by Redocly

Nimbus Property Search API (1.0.0)

Download OpenAPI specification:Download

Nimbus API Support: support@nimbusproperty.co.uk

The Nimbus Property Search API provides access to comprehensive UK property data from the Nimbus golden record index. Search, filter, and retrieve property titles using a flexible query syntax — filter by location, property characteristics, geographic bounds, ownership, and more. For field reference and examples, see the Field Reference documentation.

Search for an address

Find matching addresses by free-text query. Returns up to 10 results with full address, coordinates, UPRN UUID, and Title UUID/tenure.

Filtering: Addresses that cannot be resolved to a UPRN are excluded from results.

Title selection: When a UPRN is linked to multiple titles, the best match is selected by tenure priority (Freehold > OWNERSHIP > PROPRIETOR > SUPERIOR, then smallest area). If no title is linked, titleRef is null.

Authorizations:
OAuth2
query Parameters
address
required
string >= 3 characters
Example: address=30 Penarth Road Bolton

Free-text address to search (e.g., "30 Penarth Road Bolton" or "BL3 5RJ")

Responses

Response samples

Content type
application/vnd.api+json
Example
{
  • "jsonapi": {
    },
  • "data": [
    ],
  • "meta": {
    }
}

Titles

Property title search and data retrieval

Find a single title by ID or number

Retrieve a property title by UUID or title number. Supports lookups by ID (direct), or by number with optional country code (defaults to ENG). If both parameters provided, ID takes precedence.

Authorizations:
OAuth2
query Parameters
id
string <uuid>
Example: id=4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID for direct lookup

number
string^[A-Z]{2,3}[0-9]+$
Example: number=LA135828

Title number (case-insensitive, e.g., "LA135828")

country
string
Default: "ENG"
Enum: "ENG" "SCT"
Example: country=ENG

Country ISO code (only used with 'number' parameter)

Responses

Response samples

Content type
application/json
Example
{
  • "id": "4665bc0b-69d6-4e04-8117-48bb25dfba2c",
  • "number": "LA135828",
  • "countryIsoCode": "ENG",
  • "tenure": "Leasehold",
  • "propertyCategory": "Residential",
  • "propertyType": [
    ],
  • "areaInAcres": 0.023483,
  • "mainAddress": {
    },
  • "owners": [ ]
}

Search titles

Search property titles using a flexible query syntax. Limits: max 25 results, 5s timeout, from+size≤10000. Supports match, term, bool, range, and geo queries. See the Field Reference for available fields.

Authorizations:
OAuth2
Request Body schema: application/json
required
query
required
object

Query object describing the search criteria.

Examples:

  • {"match": {"mainAddress.town": "Bolton"}}
  • {"term": {"tenure": "Freehold"}}
  • {"bool": {"must": [...], "filter": [...]}}
  • {"range": {"areaInAcres": {"gte": 0.1, "lte": 10}}}
size
integer [ 0 .. 25 ]
Default: 10

Number of results to return (enforced max: 25)

from
integer >= 0
Default: 0

Offset for pagination (from + size must be ≤ 10,000)

sort
Array of objects

Sort specification.

Examples:

  • [{"areaInAcres": {"order": "desc"}}]
  • [{"_score": "desc"}, {"lastModified": "desc"}]
boolean or string or Array of strings or object

Fields to include/exclude in response.

Examples:

  • ["id", "number", "mainAddress"] - include only these fields
  • {"includes": ["mainAddress.*"], "excludes": ["geometry"]} - include/exclude patterns
  • false - exclude all fields (return only metadata)
track_total_hits
boolean

Whether to track total hits accurately (can be expensive for large result sets). Default: true for queries, but limited to 10,000.

Responses

Request samples

Content type
application/json
Example
{
  • "query": {
    },
  • "size": 10
}

Response samples

Content type
application/json
{
  • "took": 42,
  • "timed_out": false,
  • "_shards": {
    },
  • "hits": {
    }
}

List available brochures for a title/property

Returns metadata about brochure PDFs archived to blob storage across all comparable deals for a title. Use the index value with the /brochures/download endpoint to fetch a specific PDF. Returns empty array if no brochures are archived.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: cb534ec8-6059-49ad-b40d-3e836a91c36e

Title UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Download a brochure PDF for a title/property

Downloads the actual PDF file for a brochure archived for a title's comparable deals. Use the /titles/{titleId}/brochures endpoint first to list available brochures, then use the index parameter to select which one to download.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: cb534ec8-6059-49ad-b40d-3e836a91c36e

Title UUID

query Parameters
index
integer >= 0
Default: 0

Zero-based index of the brochure to download (default 0)

Responses

Response samples

Content type
application/json
Example
{
  • "error": {
    }
}

Get footfall estimates for a title

Returns hourly pedestrian footfall estimates for the grid cell that best overlaps the title polygon. Selects the cell with the highest daily average when multiple cells overlap. Includes both overall averages and monthly time-series data.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: 4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID

Responses

Response samples

Content type
application/json
{
  • "titleId": "4665bc0b-69d6-4e04-8117-48bb25dfba2c",
  • "indexId": "630949366352100863",
  • "averages": {
    },
  • "monthly": [
    ]
}

Search titles using natural language query

Search UK land title records using natural language queries, automatically interpreted and executed.

Accepts plain English like "houses in Bolton over 3 acres". The response includes results and a description of the executed query, enabling conversational refinement.

How it works:

  1. Submit a plain English query describing the properties you want
  2. The query is automatically interpreted and executed against the property index
  3. Results are returned with a natural language description of what was searched

Use this endpoint when:

  • You prefer natural language over structured query syntax
  • You want to explore data without writing queries manually
  • You need conversational query refinement

Limits: Same as POST /titles - max 25 results, 5s timeout, from+size≤10000

Authorizations:
OAuth2
Request Body schema: application/json
required
query
required
string [ 1 .. 500 ] characters

Natural language query describing the properties you're looking for

size
integer [ 1 .. 25 ]
Default: 25

Maximum number of results to return (1-25, default 25)

Responses

Request samples

Content type
application/json
Example
{
  • "query": "houses in Bolton",
  • "size": 10
}

Response samples

Content type
application/json
{
  • "queryDescription": "Searching for residential terraced properties in Bolton with an area between 0.02 and 0.05 acres",
  • "elasticsearchQuery": {
    },
  • "results": {
    }
}

Get comparable deal summaries for a title

Retrieve public comparable deal summaries associated with a specific title.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: cb534ec8-6059-49ad-b40d-3e836a91c36e

Title UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get planning applications for a title

Retrieve all planning applications associated with a specific property title.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: 4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get planning and environmental constraints for a title

Retrieve all planning and environmental constraints affecting a specific property title.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: 4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get sales history for a title

Retrieve all property sale transactions for a specific title.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: 4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get lease information for a title

Retrieve all lease information associated with a specific title.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: 4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get leasehold information for a title

Retrieve all leasehold titles associated with a specific freehold title.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: 4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get geometry data for a title

Retrieve geographic data including boundaries and location for a specific title.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: 4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID

Responses

Response samples

Content type
application/json
{
  • "area": 0.1,
  • "centroid": {
    },
  • "multiPolygonGeometry": {
    },
  • "titleId": "60746213-d1d1-480c-9a5b-6ee857d5228f"
}

Get building information for a title

Retrieve all buildings associated with a specific property title.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: 4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get EPC (Energy Performance Certificate) data for a title

Retrieve all EPC data from UPRNs associated with a specific title.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: 4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get top-level property data for a title

Retrieve core property information including main address, tenure, category, and area measurements.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: 4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "number": "string",
  • "countryIsoCode": "ENG",
  • "tenure": "string",
  • "propertyCategory": "Residential",
  • "propertyType": [
    ],
  • "areaInAcres": 0.1,
  • "areaInSquareFeet": 0.1,
  • "areaInSquareMeters": 0.1,
  • "buildingFootprint": 0.1,
  • "siteCoverage": 0.1,
  • "totalFloorAreaSqFt": 0.1,
  • "sizeOfCommercialSpaceInSquareFeet": 0.1,
  • "ownerType": [
    ],
  • "mainAddress": {
    }
}

Get planning use classes for a title

Retrieve all UK Planning Use Class codes from UPRNs associated with a specific title.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: 4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get owner information for a title

Retrieve all owner information for a specific title. May be empty for privacy reasons.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: 4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get VOA classifications and rateable values for a title

Retrieve Valuation Office Agency (VOA) property classifications and rateable values from UPRNs associated with a specific title.

Authorizations:
OAuth2
path Parameters
titleId
required
string <uuid>
Example: 4665bc0b-69d6-4e04-8117-48bb25dfba2c

Title UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Comps

Comparable deal search and data retrieval

Find a single comparable deal by ID

Retrieve one public comparable deal document by UUID.

Authorizations:
OAuth2
query Parameters
id
required
string <uuid>
Example: id=f1a0087f-8647-420f-9c72-fbcc9320ecb0

Comparable deal UUID for direct lookup

Responses

Response samples

Content type
application/json
{
  • "id": "f1a0087f-8647-420f-9c72-fbcc9320ecb0",
  • "titleId": "cb534ec8-6059-49ad-b40d-3e836a91c36e",
  • "comparableType": "Residential",
  • "comparableStatus": "RegisteredSale",
  • "dealType": "Residential",
  • "ownershipType": "Freehold",
  • "propertyType": [
    ],
  • "siteSizeInAcres": 0.337,
  • "mixedUse": false,
  • "validationStatus": "Validated",
  • "dealData": {
    }
}

Search comparable deals

Search comparable deal records using a flexible query syntax. Limits: max 25 results, 5s timeout, from+size≤10000.

Authorizations:
OAuth2
Request Body schema: application/json
required
query
required
object

Query object describing the search criteria.

Examples:

  • {"match": {"mainAddress.town": "Bolton"}}
  • {"term": {"tenure": "Freehold"}}
  • {"bool": {"must": [...], "filter": [...]}}
  • {"range": {"areaInAcres": {"gte": 0.1, "lte": 10}}}
size
integer [ 0 .. 25 ]
Default: 10

Number of results to return (enforced max: 25)

from
integer >= 0
Default: 0

Offset for pagination (from + size must be ≤ 10,000)

sort
Array of objects

Sort specification.

Examples:

  • [{"areaInAcres": {"order": "desc"}}]
  • [{"_score": "desc"}, {"lastModified": "desc"}]
boolean or string or Array of strings or object

Fields to include/exclude in response.

Examples:

  • ["id", "number", "mainAddress"] - include only these fields
  • {"includes": ["mainAddress.*"], "excludes": ["geometry"]} - include/exclude patterns
  • false - exclude all fields (return only metadata)
track_total_hits
boolean

Whether to track total hits accurately (can be expensive for large result sets). Default: true for queries, but limited to 10,000.

Responses

Request samples

Content type
application/json
Example
{
  • "query": {
    },
  • "sort": [
    ],
  • "size": 10
}

Response samples

Content type
application/json
{
  • "took": 42,
  • "timed_out": false,
  • "_shards": {
    },
  • "hits": {
    }
}

Get sale detail records for a comparable deal

Retrieve up to 10 sale detail records for a comparable deal. The response includes ownership type, corporate ownership where available, linked investment-sale leases, tenants, and agents.

Authorizations:
OAuth2
path Parameters
dealId
required
string <uuid>
Example: f1a0087f-8647-420f-9c72-fbcc9320ecb0

Comparable deal UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get lease detail records for a comparable deal

Retrieve up to 10 lease detail records for a comparable deal. The response includes break clauses, covenants, tenants, and agents.

Authorizations:
OAuth2
path Parameters
dealId
required
string <uuid>
Example: f1a0087f-8647-420f-9c72-fbcc9320ecb0

Comparable deal UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get listing detail records for a comparable deal

Retrieve up to 10 listing detail records for a comparable deal. The response includes price history, marketing resources, images, and agents.

Authorizations:
OAuth2
path Parameters
dealId
required
string <uuid>
Example: f1a0087f-8647-420f-9c72-fbcc9320ecb0

Comparable deal UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List available brochures for a comparable deal

Returns metadata about brochure PDFs archived to blob storage for a comparable deal's listings. Use the index value with the /brochures/download endpoint to fetch a specific PDF. Returns empty array if no brochures are archived.

Authorizations:
OAuth2
path Parameters
dealId
required
string <uuid>
Example: dace1cb1-6cbf-4529-be74-316c236083d6

Comparable deal UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Download a brochure PDF for a comparable deal

Downloads the actual PDF file for a brochure that has been archived to blob storage. Use the /comps/{dealId}/brochures endpoint first to list available brochures, then use the index parameter to select which one to download.

Authorizations:
OAuth2
path Parameters
dealId
required
string <uuid>
Example: dace1cb1-6cbf-4529-be74-316c236083d6

Comparable deal UUID

query Parameters
index
integer >= 0
Default: 0

Zero-based index of the brochure to download (default 0)

Responses

Response samples

Content type
application/json
Example
{
  • "error": {
    }
}

Search comparable deals using natural language

Search comparable deal records using natural language queries, automatically interpreted and executed.

Authorizations:
OAuth2
Request Body schema: application/json
required
query
required
string [ 1 .. 500 ] characters

Natural language query describing the properties you're looking for

size
integer [ 1 .. 25 ]
Default: 25

Maximum number of results to return (1-25, default 25)

Responses

Request samples

Content type
application/json
Example
{
  • "query": "commercial office sales in Birmingham over 500k since 2022",
  • "size": 10
}

Response samples

Content type
application/json
{
  • "queryDescription": "Searching for commercial comparable sales in Manchester over 500000 pounds",
  • "elasticsearchQuery": { },
  • "results": {
    }
}

Utilities

Utility and diagnostic endpoints

Get footfall estimates by grid cell index

Returns hourly pedestrian footfall estimates for a specific grid cell by its index ID. Includes both overall averages and monthly time-series data.

Authorizations:
OAuth2
path Parameters
indexId
required
string
Example: 630949366352100863

Footfall grid cell index ID

Responses

Response samples

Content type
application/json
{
  • "indexId": "630949366352100863",
  • "averages": {
    },
  • "monthly": [
    ]
}

Health check

Check the health status of the API

Responses

Response samples

Content type
application/json
{
  • "status": "healthy",
  • "timestamp": "2026-01-10T12:34:56Z",
  • "version": "2.0.0"
}