Skip to content

Transaction Search

POST transactions/search

Returns transactions that match the specified search criteria.

Request#

curl -X POST 'https://api.pricehubble.com/api/v1/transactions/search?access_token=74126eab0a9048d993bda4b1b55ae074' \
  -H 'Content-Type: application/json' \
  -d '{
    "referenceLocation": {
        "address": {
            "city": "Paris",
            "houseNumber": "5",
            "postCode": "75013",
            "street": "Parvis Alan Turing"
        }
    },
    "filters": {
        "transactionDate": {
            "min": "2018-01-01"
        },
        "salePrice": {
            "currency": "EUR",
            "max": 1000000
        },
        "location": [
            {
                "circle": {
                    "center": {
                        "coordinates": {
                            "latitude": 48.833985,
                            "longitude": 2.371335
                        }
                    },
                    "radius": 30000
                }
            }
        ],
        "propertyType": [
            {
                "code": "apartment",
                "subcode": "apartment_normal"
            },
            {
                "code": "apartment",
                "subcode": "apartment_attic"
            }
        ],
        "livingArea": {
            "min": 80,
            "max": 110
        },
        "numberOfRooms": {
            "min": 4,
            "max": 4.5
        }
    },
    "offset": 0,
    "limit": 10,
    "orderBy": [
        {
            "field": "distance"
        },
        {
            "field": "transactionDate",
            "direction": "desc"
        }
    ],
    "countryCode": "FR"
}'
Field Description Type Remarks
referenceLocation Reference location of the search. Distances of transactions are computed relative to this location Location
filters Allows to specify various search criteria object
filters.transactionDate Filter on transaction date object
filters.transactionDate.min Lower bound for transaction date date Date format: YYYY-MM-DD
filters.transactionDate.max Upper bound for transaction date date Date format: YYYY-MM-DD
filters.salePrice Filter on sale price object
filters.salePrice.currency Currency of the sale price filter Currency Only EUR is currently supported
filters.salePrice.min Lower bound for sale price integer
filters.salePrice.max Upper bound for sale price integer
filters.location Filters on location. If multiple filters are provided, they are connected by a logical "or" array of LocationFilters
filters.propertyType Filter on property type. Matches transactions which have one of the specified property types array of PropertyTypes
filters.livingArea Filter on net living area object
filters.livingArea.min Lower bound for net living area, in m2 integer
filters.livingArea.max Upper bound for net living area, in m2 integer
filters.buildingYear Filter on building year object
filters.buildingYear.min Lower bound for building year integer
filters.buildingYear.max Upper bound for building year integer
filters.numberOfRooms Filter on number of rooms object
filters.numberOfRooms.min Lower bound for number of rooms float
filters.numberOfRooms.max Upper bound for number of rooms float
filters.hasParkingSpaces Filter on the transaction's hasParkingSpaces flag boolean
filters.isNew Filter on the transaction's isNew flag boolean
offset Offset of the query (allows pagination) integer min: 0, max: 1'000, default: 0
limit Maximum number of results to return integer min: 0, max: 500, default: 10
orderBy Sort order array of OrderByCriterions
countryCode ISO country code string Only FR is currently supported

LocationFilter#

To filter by location, either a circle or a divisionLevel* must be provided. If you would like to filter by division levels but only have an address or coordinates and don't know the official ID of the administrative division, you can use the Administrative Divisions endpoint to look up the administrative division and the respective ID.

Field Description Type Remarks
circle Location filter of type "circle". Matches transactions which lie within the circle defined by center and radius object
circle.center Center of the circle Location
circle.radius Radius of the circle, in m integer min: 0, max: 30'000, default: 20'000
divisionLevel6 The official ID of the level 6 division string
divisionLevel8 The official ID of the level 8 division string
divisionLevel100 The official ID of the level 100 division string

OrderByCriterion#

Field Description Type Remarks
field Field by which to sort enum distance, transactionDate, or salePrice
direction Sort direction enum asc (default) or desc

Response#

{
    "items": [
        {
            "address": {
                "city": "PARIS ",
                "houseNumber": "181",
                "postCode": "75013",
                "street": "RUE DU CHEVALERET"
            },
            "buildingYear": 1958,
            "coordinates": {
                "latitude": 48.833667755127,
                "longitude": 2.36874389648438
            },
            "currency": "EUR",
            "distance": 193,
            "floorNumber": 11,
            "hasParkingSpaces": false,
            "isNew": false,
            "livingArea": 83,
            "numberOfParkingSpaces": 0,
            "numberOfRooms": 4,
            "propertyType": {
                "code": "apartment",
                "subcode": "apartment_normal"
            },
            "salePrice": 600000,
            "transactionDate": "2018-05-01",
            "transactionId": "FR-532e76828877d9ec9d67bf738f5956734c3526830b3f3eba58019639aa6bccb6"
        },
        ...
    ],
    "totalItems": 5068
}
Field Description Type Remarks
totalItems Total number of matching transactions found integer min: 0
This field is capped and is only accurate if there are less than 1’500 results. If there are more results, this field will equal 1’500
items List of matching transactions array of Transactions empty array if no results

Transaction#

Field Description Type Remarks
transactionId Technical ID of the transaction string
transactionDate Transaction date date Format: YYYY-MM-DD
salePrice Transaction price integer
currency Currency of the transaction string
address Address of the property Address
coordinates Coordinates of the property Coordinates
distance Distance of the property to the reference location, in m integer Only returned if the request contains a referenceLocation
floorNumber Floor number integer
buildingYear Building year of the property integer
propertyType Type of the property PropertyType
livingArea Net living area (SIA standard) of the property, in m2 integer
landArea Total area of the lot/parcel on which the house is standing, in m2 integer
numberOfRooms Number of rooms of the property float
hasParkingSpaces Does the property have parking spaces? boolean
numberOfParkingSpaces Number of parking spaces integer
isNew Has the property never been used before, i.e. has it never been sold or rented out? boolean