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' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 74126eab0a9048d993bda4b1b55ae074' \
  -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"
        }
    ],
    "dossierId": "3bac39b8-2d84-4ae9-a693-40502071ea5d",
    "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	DateValueRange
filters.salePrice	Filter on sale price	PriveValueRance
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	ValueRange	Living area, in m2 For UK: in sq.ft
filters.buildingYear	Filter on building year	ValueRange
filters.numberOfRooms	Filter on number of rooms	ValueRange
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
dossierId	ID of the dossier	string	If this field is added to the request, then the location must be the same as the dossier's location (address or coordinates)
countryCode	ISO country code	string	Only FR and UK are 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	string	Valid values are distance, transactionDate, salePrice or salePricePerSqm
direction	Sort direction	string	Valid values are 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
salePricePerSqm	Transaction price per m2	integer	Only available for FR
salePricePerSqft	Transaction price per sq.ft	integer	Only available for UK
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	integer	For FR: in m2 For UK: in sq.ft
landArea	Total area of the lot/parcel on which the house is standing	integer	For FR: in m2 For UK: in acres
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
isLeasehold	Is leasehold	boolean	Only available for UK