Skip to main content

​
Overview

The API supports multiple filtering mechanisms:
  • Filter-based searching: AND/OR logic for multi-value filters
  • Date-based searching: Date ranges with various formats
  • Location-based searching: Geographic queries (single point and polygons)
  • Text searching: Full-text search across multiple fields

​
Filter-Based Searching

Some endpoints support AND and OR filtering. The syntax used determines the outcome.

​
OR Logic (Comma-Separated)

Use comma-separated values for OR logic: 
GET /items?options=option1,option2
SQL Equivalent: 
SELECT * FROM items WHERE option1 = true OR option2 = true;
Result: Items that have option1 OR option2 OR both set to true will be returned.

​
AND Logic (Repeated Parameters)

Repeat the parameter for AND logic: 
GET /items?options=option1&options=option2
SQL Equivalent: 
SELECT * FROM items WHERE option1 = true AND option2 = true;
Result: Only items that have both option1 AND option2 set to true will be returned.

​
Combining AND and OR

You can combine both approaches: 
GET /items?options=option1&options=option2&reference=123
SQL Equivalent: 
SELECT * FROM items 
WHERE option1 = true 
  AND option2 = true 
  AND reference = 123;
Mixed Example: 
GET /items?options=option1,option2&reference=123
SQL Equivalent: 
SELECT * FROM items 
WHERE (option1 = true OR option2 = true) 
  AND reference = 123;
Result: Items that have (option1 OR option2 OR both) AND reference=123.

​
Real-World Examples

​
Filtering Applications by Type

OR logic - Get planning permission OR listed building consent: 
GET /api/@next/public/applications?applicationType=planningPermission,listedBuildingConsent
AND logic - Applications must match both conditions: 
GET /api/@next/public/applications?stage=consultation&status=undetermined

​
Filtering Public Comments

OR logic - Get objections OR neutral comments: 
GET /api/@next/public/applications/{id}/publicComments?sentiment=objection,neutral
AND logic - Comments about design AND privacy: 
GET /api/@next/public/applications/{id}/publicComments?topic=design&topic=privacy
Mixed logic - Design or privacy concerns, only objections: 
GET /api/@next/public/applications/{id}/publicComments?topic=design,privacy&sentiment=objection

​
Filtering Documents

GET /api/@next/public/applications/{id}/documents?type=floorPlan.existing,floorPlan.proposed&publishedAtFrom=2024-01-01T00:00:00Z
Gets floor plans (existing OR proposed) published after January 1, 2024.

​
Date-Based Searching

When searching with dates, follow these conventions:
  • Date fields (suffix Date): Format as YYYY-MM-DD
  • DateTime fields (suffix At): Format as ISO 8601 UTC YYYY-MM-DDTHH:MM:SSZ

​
Date-Only Ranges

GET /items?consultationEndDateFrom=2024-03-01&consultationEndDateTo=2024-03-10
​
consultationEndDateFrom
date
required
Start date in YYYY-MM-DD formatRequires: consultationEndDateTo must also be specified
​
consultationEndDateTo
date
required
End date in YYYY-MM-DD formatRequires: consultationEndDateFrom must also be specified

​
DateTime Ranges

GET /items?receivedAtFrom=2024-03-01T00:00:00Z&receivedAtTo=2024-03-10T23:59:59Z
​
receivedAtFrom
datetime
required
Start datetime in ISO 8601 UTC formatRequires: receivedAtTo must also be specified
​
receivedAtTo
datetime
required
End datetime in ISO 8601 UTC formatRequires: `receivedAtFrom” must also be specified

​
Common Date Parameters

Parameter PairTypeDescription
receivedAtFrom / receivedAtTodatetimeApplication received date range
validatedAtFrom / validatedAtTodatetimeValidation date range
publishedAtFrom / publishedAtTodatetimePublication date range
withdrawnAtFrom / withdrawnAtTodatetimeWithdrawal date range
consultationEndDateFrom / consultationEndDateTodateConsultation end date range
councilDecisionDateFrom / councilDecisionDateTodateCouncil decision date range
appealLodgedDateFrom / appealLodgedDateTodateAppeal lodged date range
appealDecisionDateFrom / appealDecisionDateTodateAppeal decision date range
Date pairs are required: Both From and To parameters must be specified together.

​
Location-Based Searching

This section is still under development and may change in future versions.
Search within a radius of a specific point: 
GET /items?lat=51.519389&lng=-0.108128&radius=10000
​
lat
float
required
Latitude coordinateRequires: lng and radius
​
lng
float
required
Longitude coordinateRequires: lat and radius
​
radius
number
default:"10000"
Search radius in metersConversion: To convert miles to meters: miles / 0.000621371
These parameters are geocoded into lat/lng coordinates: 
GET /items?loc_postcode=EC1N 8BA&radius=10000
GET /items?loc_address=123 Main Street&radius=10000
​
loc_postcode
string
Postcode to geocodeRequires: radius
​
loc_address
string
Address to geocodeRequires: radius
Default radius values depend on the search context:
Use CaseRecommended Radius
Small-scale searches (ATMs, cafes)500–1,000 meters
Local searches (restaurants, businesses)2,000–5,000 meters
City-wide searches (delivery zones)10,000–20,000 meters
Regional searches (hospitals, large areas)50,000+ meters

​
GeoJSON Format

GET /items?polygon={"type":"Polygon","coordinates":[[[-73.97,40.77],[-73.98,40.75],[-73.96,40.74],[-73.97,40.77]]]}
GeoJSON Structure:
  • type: “Polygon” to specify geometry type
  • coordinates: Array of [longitude, latitude] pairs
  • Important: First and last coordinates must be identical to close the polygon

​
Simple Coordinate Pairs

Alternatively, pass coordinates as a comma-separated string: 
GET /items?polygon=-73.97,40.77,-73.98,40.75,-73.96,40.74,-73.97,40.77
Format: longitude1,latitude1,longitude2,latitude2,...

​
Text Search

Many endpoints support a general query parameter for full-text search: 
GET /api/@next/public/applications?query=extension
​
query
string
Search term applied across multiple fieldsApplication endpoints: Searches reference, description, and addressDocument endpoints: Searches name, type, and descriptionComment endpoints: Searches comment text
Some endpoints support searching specific fields: 
GET /api/@next/public/applications?reference=ABC-2024
GET /api/@next/public/applications/{id}/documents?name=Floor Plan

​
Sorting Results

Combine filtering with sorting:
​
sortBy
string
default:"varies"
Field to sort byCommon options:
  • receivedAt
  • publishedAt
  • name
  • id
  • councilDecisionDate
​
orderBy
string
default:"desc"
Sort orderOptions:
  • asc - Ascending order
  • desc - Descending order
GET /api/@next/public/applications?stage=consultation&sortBy=receivedAt&orderBy=desc

​
Complex Query Example

Combining multiple filter types: 
GET /api/@next/public/applications?
  applicationType=planningPermission,priorApproval&
  stage=consultation&
  receivedAtFrom=2024-01-01T00:00:00Z&
  receivedAtTo=2024-03-31T23:59:59Z&
  lat=51.5074&
  lng=-0.1278&
  radius=5000&
  sortBy=receivedAt&
  orderBy=desc&
  page=0&
  resultsPerPage=20
This query finds:
  • Planning permission OR prior approval applications
  • Currently in consultation stage
  • Received in Q1 2024
  • Within 5km of central London
  • Sorted by received date (newest first)
  • First page with 20 results

​
Next Steps

Endpoints

See filtering in action on specific endpoints

Response Structure

Understand the response format

Build docs developers (and LLMs) love

Get started for freeTalk to us