Skip to main content
POST
/
v1
/
property
/
query
Query properties with advanced filters
curl --request POST \
  --url https://api.vepler.com/v1/v1/property/query \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "area": [
    {
      "type": "postcode",
      "value": "SW1A 1AA",
      "radius": 1000
    }
  ],
  "query": {
    "priceMin": 30000000,
    "priceMax": 80000000,
    "rentMin": 150000,
    "rentMax": 350000,
    "beds": [
      2,
      3,
      4
    ],
    "baths": [
      1,
      2
    ],
    "propertyType": [
      "terraced",
      "detached"
    ],
    "epcRating": [
      "A",
      "B",
      "C"
    ],
    "tenure": [
      "freehold"
    ],
    "councilTaxBand": [
      "C",
      "D",
      "E"
    ],
    "saleStatus": [
      "live",
      "sstc"
    ],
    "rentStatus": [
      "live"
    ],
    "tags": {
      "newBuild": true,
      "chainFree": true,
      "auction": true,
      "sharedOwnership": true,
      "retirement": true,
      "cashBuyersOnly": true,
      "investment": true
    },
    "yearBuiltMin": 1900,
    "yearBuiltMax": 2024,
    "floorAreaMin": 50,
    "floorAreaMax": 150
  },
  "limit": 25,
  "offset": 0,
  "sortBy": "price",
  "sortOrder": "asc",
  "attributes": [
    "address",
    "pricing",
    "roomDetails",
    "epc"
  ]
}
'
{
  "success": true,
  "result": [
    {
      "propertyId": "prop_123abc",
      "locationId": "loc_456def",
      "address": {
        "displayAddress": "123 Example Street, London SW1A 1AA",
        "postcode": "SW1A 1AA",
        "streetName": "Example Street",
        "streetNumber": "123",
        "locality": "Westminster",
        "town": "London",
        "county": "Greater London",
        "postcodeNoSpace": "SW1A1AA",
        "outcode": "SW1A",
        "incode": "1AA",
        "country": "GB"
      },
      "spatial": {
        "lat": 51.5074,
        "lng": -0.1278,
        "boundary": "<unknown>"
      },
      "classificationCode": "RD06",
      "propertyType": "terraced",
      "propertySubType": "Victorian terrace",
      "roomDetails": {
        "beds": 3,
        "baths": 2,
        "receptions": 1
      },
      "pricing": {
        "currentSalePrice": 50000000,
        "currentRentPrice": 250000,
        "estimatedSaleValue": 52000000,
        "estimatedRentValue": 260000,
        "pricePerSqFt": 850,
        "currency": "GBP"
      },
      "marketStatus": {
        "forSale": "live",
        "forRent": "unavailable",
        "listingDate": "2024-01-15T00:00:00Z",
        "soldDate": "2024-03-20T00:00:00Z",
        "daysOnMarket": 65
      },
      "epc": {
        "currentEnergyRating": "C",
        "potentialEnergyRating": "B",
        "currentEnergyEfficiency": 69,
        "potentialEnergyEfficiency": 83,
        "validFrom": "2023-06-15",
        "validTo": "2033-06-14"
      },
      "saleHistory": [
        {
          "date": "2023-06-15",
          "price": 45000000,
          "propertyType": "terraced",
          "newBuild": false
        }
      ],
      "tenure": {
        "type": "freehold",
        "leaseYearsRemaining": 95,
        "groundRent": 25000,
        "serviceCharge": 180000
      },
      "councilTax": {
        "taxBand": "D",
        "annualCharge": 180000,
        "localAuthority": "Westminster City Council"
      },
      "tags": {
        "newBuild": false,
        "chainFree": true,
        "auction": false,
        "sharedOwnership": false,
        "retirement": false,
        "cashBuyersOnly": false,
        "investment": false
      },
      "floorAreaSqM": 85,
      "plotSizeSqM": 120,
      "yearBuilt": 1890,
      "lastUpdated": "2024-01-15T10:30:00Z"
    }
  ],
  "totalSize": 150,
  "size": 25,
  "hasMore": true,
  "nextOffset": 25
}

​
Overview

The property query endpoint provides powerful filtering capabilities for searching properties across the UK. You can combine geographic area filters with advanced property attribute filters to find exactly what you’re looking for.

​
Request Structure

Both area and query fields are required and accept arrays:
  • area: Array of geographic filters (combined with OR logic)
  • query: Array of query operators for property filtering

​
Area Filter Types

The endpoint supports 6 different area filter types:

​
1. Location ID Filter

Search by internal location identifier: 
{
  "area": [
    {
      "locationId": "loc_abc123"
    }
  ],
  "query": []
}

​
2. Postcode Filter

Search by full or partial postcode with optional radius: 
{
  "area": [
    {
      "type": "postcode",
      "value": "SW1A 1AA",
      "radius": 1000
    }
  ],
  "query": []
}

​
3. Outcode Filter

Search by postcode outcode: 
{
  "area": [
    {
      "type": "outcode",
      "value": "SW1A"
    }
  ],
  "query": []
}

​
4. Point Filter

Search within a radius of coordinates (latitude, longitude): 
{
  "area": [
    {
      "type": "point",
      "coordinates": [51.5074, -0.1278],
      "radius": 2000
    }
  ],
  "query": []
}

​
5. Polygon Filter

Search within a custom polygon boundary: 
{
  "area": [
    {
      "type": "polygon",
      "coordinates": [
        [
          [51.5074, -0.1278],
          [51.508, -0.128],
          [51.507, -0.1275],
          [51.5074, -0.1278]
        ]
      ]
    }
  ],
  "query": []
}

​
6. MultiPolygon Filter

Search across multiple polygon areas: 
{
  "area": [
    {
      "type": "multipolygon",
      "coordinates": [
        [
          [
            [51.5074, -0.1278],
            [51.508, -0.128],
            [51.507, -0.1275],
            [51.5074, -0.1278]
          ]
        ],
        [
          [
            [51.510, -0.130],
            [51.511, -0.131],
            [51.509, -0.129],
            [51.510, -0.130]
          ]
        ]
      ]
    }
  ],
  "query": []
}

​
Multiple Area Filters

You can combine multiple area filters - they will be combined with OR logic: 
{
  "area": [
    {
      "type": "postcode",
      "value": "SW1A",
      "radius": 1000
    },
    {
      "type": "postcode",
      "value": "W1A",
      "radius": 1000
    }
  ],
  "query": []
}

​
Query Filter Structure

The query field accepts an array of query operators with a nested structure: 
query: Array<PropertyQueryOperator>
  └─ PropertyQueryOperator
      ├─ operator: "AND" | "OR"
      └─ groups: Array<PropertyQueryGroup>
          └─ PropertyQueryGroup
              └─ conditions: Array<PropertyQueryCondition>
                  ├─ field: string
                  ├─ comparator: "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "contains" | "startswith" | "endswith"
                  └─ value: string | number | boolean | array

​
Available Comparators

  • eq: Equals
  • ne: Not equals
  • gt: Greater than
  • gte: Greater than or equal
  • lt: Less than
  • lte: Less than or equal
  • in: In array
  • nin: Not in array
  • contains: Contains substring
  • startswith: Starts with
  • endswith: Ends with

​
Complete Examples

​
Example 1: Properties for Sale in London (2-3 beds, £300k-£600k)

{
  "area": [
    {
      "type": "postcode",
      "value": "SW1",
      "radius": 5000
    }
  ],
  "query": [
    {
      "operator": "AND",
      "groups": [
        {
          "conditions": [
            {
              "field": "pricing.currentSalePrice",
              "comparator": "gte",
              "value": 30000000
            },
            {
              "field": "pricing.currentSalePrice",
              "comparator": "lte",
              "value": 60000000
            }
          ]
        },
        {
          "conditions": [
            {
              "field": "roomDetails.beds",
              "comparator": "in",
              "value": [2, 3]
            }
          ]
        },
        {
          "conditions": [
            {
              "field": "marketStatus.forSale",
              "comparator": "eq",
              "value": "live"
            }
          ]
        }
      ]
    }
  ],
  "limit": 50,
  "offset": 0,
  "attributes": ["address", "pricing", "roomDetails", "marketStatus"]
}

​
Example 2: High EPC Rated Flats in Multiple Areas

{
  "area": [
    {
      "type": "postcode",
      "value": "E14",
      "radius": 2000
    },
    {
      "type": "postcode",
      "value": "SE1",
      "radius": 2000
    }
  ],
  "query": [
    {
      "operator": "AND",
      "groups": [
        {
          "conditions": [
            {
              "field": "propertyType",
              "comparator": "eq",
              "value": "flat"
            }
          ]
        },
        {
          "conditions": [
            {
              "field": "epc.currentEnergyRating",
              "comparator": "in",
              "value": ["A", "B", "C"]
            }
          ]
        }
      ]
    }
  ],
  "limit": 25,
  "attributes": ["address", "propertyType", "epc"]
}

​
Example 3: Complex Query with OR Logic

{
  "area": [
    {
      "locationId": "loc_london_central"
    }
  ],
  "query": [
    {
      "operator": "OR",
      "groups": [
        {
          "conditions": [
            {
              "field": "propertyType",
              "comparator": "eq",
              "value": "detached"
            },
            {
              "field": "roomDetails.beds",
              "comparator": "gte",
              "value": 4
            }
          ]
        },
        {
          "conditions": [
            {
              "field": "pricing.currentSalePrice",
              "comparator": "gte",
              "value": 100000000
            }
          ]
        }
      ]
    }
  ]
}

​
Pagination

Use limit and offset for pagination:
  • limit: 1 to 10,000 (default: 25)
  • offset: 0 to 100,000 (default: 0)
{
  "area": [...],
  "query": [...],
  "limit": 100,
  "offset": 200
}

​
Field Selection

Use the attributes field to select specific fields (supports both string and array formats): 
{
  "area": [...],
  "query": [...],
  "attributes": ["address", "pricing", "roomDetails", "epc"]
}
Or as a comma-separated string: 
{
  "attributes": "address,pricing,roomDetails,epc"
}

​
Response

{
  "success": true,
  "result": [
    {
      "propertyId": "prop_123",
      "address": {
        "displayAddress": "123 Example St, London SW1A 1AA",
        "postcode": "SW1A 1AA"
      },
      "pricing": {
        "currentSalePrice": 45000000,
        "currency": "GBP"
      },
      "roomDetails": {
        "beds": 3,
        "baths": 2
      }
    }
  ],
  "totalSize": 150,
  "size": 25,
  "hasMore": true,
  "nextOffset": 25
}

Authorizations

​
x-api-key
string
header
required

API Key authentication for Vepler API. Get your API key from the Vepler dashboard.

Body

application/json

Property search criteria

​
area
object[]
required

Geographic search areas (multiple areas will be combined with OR logic)

Minimum array length: 1
​
query
object

Property attribute filters

​
limit
number
default:25

Number of results to return per page

Required range: 1 <= x <= 100
Example:

25

​
offset
number
default:0

Number of results to skip for pagination

Required range: x >= 0
Example:

0

​
sortBy
enum<string>

Field to sort results by

Available options:
price,
date,
beds,
floorArea,
yearBuilt
Example:

"price"

​
sortOrder
enum<string>
default:asc

Sort order

Available options:
asc,
desc
Example:

"asc"

​
attributes
string[]

Specific fields to include in response

Example:
["address", "pricing", "roomDetails", "epc"]

Response

Properties matching search criteria

​
success
boolean
required
​
result
object[]
required

Array of property data objects

​
totalSize
number
required

Total number of properties matching the query

Example:

150

​
size
number
required

Number of properties returned in this response

Example:

25

​
hasMore
boolean

Indicates if more results are available

Example:

true

​
nextOffset
number

Offset to use for next page of results

Example:

25