ads reference

Get ads reference

The code below gives an example of how to use the client to get ads references.

import valueguard

vgClient = valueguard.Client()
vgClient.authenticate("<username>", "<password>")


print(vgClient.ads_reference(search_criteria={
    "home_type":["apartment"],
    "living_area_reference":"78",
    "wgs84lat":"59.864908174031974",
    "wgs84lon":"17.648463519218435"
}))

Response

Field list

Field name	Description	Example
id	Ad id	324234
residential_registry_id	Residential registry id	unique id (serial number) for all residences source: Valueguard
street	Street name in address	1:a villagatan
number	Street number in address	1
letter	Letter after street number in address, if any	A
rooms	Number of rooms	5
living_area	Area of residence in sqm	137
construction_year	Year it was built	1920
ancillary_area	Ancillary area in sqm, not part of the primary building area	23
home_type	Apartment for apartments, house for detached houses, town houses etc.	apartment
price	Last price on the ad	1900000
monthly_fee	Monthly fee	3654
error_code	1 = suspected error in data 0 = no suspected error in data	0
firm	Firm	notar
active	That the ad is currently active	True
has_pdf	If the ad has and pdf snapshot	True
registered_date	When the ad was registered	2012-03-23
url	Url of ad	https://webpage.se/ad/2
rt90x	X-coordinate (longitude) from RT90. a Swedish positioning system by LMV used before 2007	6586700
rt90y	Y-coordinate (latitude) from RT90. a Swedish positioning system by LMV used before 2007	1367905

Summary

Field name	Description	Example
id	Id of the summary	324234
average_rooms	Average amount of rooms for all objects	3
average_living_area	Average living area in sqm for all objects	72
average_ancillary_area	Average ancillary area in sqm (not part of the primary building area) for all objects	15
average_construction_year	Average construction year for all objects	1985
average_price	Average price for all objects	2100000
average_recounted_price	Average price today for all objects	2300000
average_monthly_fee	Average monthly fee for all objects	2300
average_registered_date	Average registered date for all objects	"2024-02-02"
average_advertising_days	Average amount of advertising days for all objects	35
average_monthly_fee_sqm	Average monthly fee per sqm for all objects	305
average_price_sqm	Average price per square for all objects	17000
average_distance	Average distance between all objects in meters	28
average_plot_area	Average plot area in sqm for all objects	28

Search criteria fields

Reference object

Field name	Description	Example
registered_date_reference	When the ad was registered	2012-03-23
price_reference	Last price on the ad	1900000
living_area_reference	Area of residence in sqm	78
wgs84lat	Y-coordinate (latitude) from WGS84. a global positioning system	59.864908174031974
wgs84lon	X-coordinate (longitude) from WGS84. a global positioning system	17.648463519218435
floor_reference	The floor of this particular residence	3
floors_reference	The highest floor on the address	4
rooms_reference	Number of rooms	4
ancillary_area_reference	Ancillary area in sqm, not part of the primary building area	23
construction_year_reference	Year it was built	1976
monthly_fee_reference	Monthly fee	6000

Ad filter

Field name	Description	Example
home_type	Category of residence	[apartment]
ownership_type	List of form of ownership of residence	[co_operative, property_right]
registered_date_min	Earliest date when the ad can be registered	2022-03-23
registered_date_max	Latest date when the ad can be registered	2023-03-23
price_min	Lowest allowed price on the ad	1900000
price_max	Highest allowed price on the ad	2900000
living_area_min	Lowest allowed area of residence in sqm	78
living_area_max	Highest allowed area of residence in sqm	88
rooms_min	Lowest allowed nubmer of rooms	3
rooms_max	Highest allowed nubmer of rooms	4
construction_year_min	Earliest allowed year when the building was built	1956
construction_year_max	Latest allowed year when the building was built	1986
advertising_days_min	Lowest amount of days the ad is allowed to have been active	10
advertising_days_max	Highest amount of days the ad is allowed to have been active	30
error_code	1 = suspected error in data 0 = no suspected error in data	0
is_close_to_population_centre	If the property needs to be in proximity to population centers.	0
is_new_construction	Show obejcts that are likely new constructions.	0
excluded_ids	List of ads that have been filtered out	["550e8400-e29b-41d4-a716-446655440000", "550e8400-e29b-41d4-a716-446655440001"]
selected_ids	List of ad UUIDs to include in the reply	["550e8400-e29b-41d4-a716-446655440002", "550e8400-e29b-41d4-a716-446655440003"]
limit	Maximum number of responses	20

Weights

Reflecting importance in the reference ads search, between 0 to 1000

Field Name	Description	Default	Example
registered_date_weight	Weight assigned to the contract date.	500	900
living_area_weight	Weight given to the living area.	500	500
construction_year_weight	Weight allocated to the year of construction.	500	350
monthly_fee_weight	Weight for the monthly fee.	500	600
floor_weight	Weight of the property's floor level.	500	500
floors_weight	Weight for the total number of floors in the building.	500	400
rooms_weight	Weight assigned to the number of rooms.	500	700
ancillary_area_weight	Weight assigned to the ancillary_area.	500	700
population_center_weight	Weight for the property's proximity to population centers.	500	500
distance_weight	Weight for the distance to the reference ad.	500	800

Raw request

Post

curl --location 'https://api.valueguard.se/v1/ads/reference?access_token=<ACCESS_TOKEN>' \
--data '{"living_area_reference":78,"rooms_reference":1,"advertising_days_min":0,"advertising_days_max":500,"home_type":["apartment","house"],
"ownership_type":["property_rights"],"living_area_min":0,"living_area_max":500,"price_min":0,"price_max":12000000,"rooms_min":0,"rooms_max":10,"error_code":0,"excluded_ids":[],"limit":15,"selected_ids":null,"excluded_ids":null,"wgs84lat":"59.85856380000001","wgs84lon":"17.6389267"}'