ads_reference_2

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>")


result = vgClient.ads_reference(search_criteria={
    "living_area_reference": 81,
    "rooms_reference": 2,
    "advertising_days_min": 0,
    "advertising_days_max": 500,
    "home_type": ["apartment", "house"],
    "construction_year_min": 1850,
    "contract_date_start": "1850-01-01",
    "contract_date_end": "2024-08-05",
    "distance_center": False,
    "error_code": 0,
    "excluded_ids": [],
    "limit": 15,
    "living_area_min": 0,
    "living_area_max": 500,
    "monthly_fee_min": 0,
    "monthly_fee_max": 12000,
    "price_min": 0,
    "price_max": 12000000,
    "rooms_min": 0,
    "rooms_max": 10,
    "distance_weight": 50,
    "polygons": {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "geometry": {
                    "type": "MultiPolygon",
                    "crs": {
                        "type": "name",
                        "properties": {
                            "name": "EPSG:3021"
                        }
                    },
                    "coordinates": [
                        [[
                            [1603359.765, 6639251.261],
                            [1603673.096, 6639545.17],
                            [1603330.038, 6639721.021],
                            [1603000.557, 6639454.841],
                            [1603359.765, 6639251.261]
                        ]]
                    ]
                }
            }
        ]
    }
})

print(result)

Response

Field list

Field name	Description	Example
id	Ad id	4b966449-5a34-11ef-b390-0242ac110006
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	Type of residence: apartment, house, plot, terraced_house, townhouse, unknown	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	1 = the ad is currently active 0 = the ad is currently inactive	1
has_pdf	If the ad has a 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
wgs84lon	longitude from wgs84	17.651505
wgs84lat	latitude from wgs84	59.868478

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_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	45
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	List of type of residence	[apartment, house, plot, terraced_house, townhouse, unknown]
ownership_type	List of type of ownership of residence	[co_operative_apartment, property_rights, site_leasehold, unknown]
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
active	1 = the ad should be currently active 0 = the ad should be currently inactive	1
rt90x_square_min	Minimum RT90 X-coordinate of the search square	6580000
rt90x_square_max	Maximum RT90 X-coordinate of the search square	6581000
rt90y_square_min	Minimum RT90 Y-coordinate of the search square	1620000
rt90y_square_max	Maximum RT90 Y-coordinate of the search square	1621000
Polygons	GeoJSON format for the search region	View Example

GeoJson

Here is a simple example of a GeoJSON format that can be used for filtering.

Polygon

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [17.5288, 59.7500],
            [17.8094, 59.7500],
            [17.8094, 60.0000],
            [17.5288, 60.0000],
            [17.5288, 59.7500]
          ]
        ]
      },
      "properties": {}
    }
  ]
}

Multipolygon

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [17.638927, 59.858562],
              [17.641931, 59.858562],
              [17.641931, 59.860562],
              [17.638927, 59.860562],
              [17.638927, 59.858562]
            ]
          ],
          [
            [
              [17.650927, 59.857562],
              [17.653931, 59.857562],
              [17.653931, 59.859562],
              [17.650927, 59.859562],
              [17.650927, 59.857562]
            ]
          ]
        ]
      },
      "properties": {}
    }
  ]
}

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-prod.valueguard.se/v1/ads/reference?access_token=<ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{"0":["distance_weight",50],"living_area_reference":81,"rooms_reference":2,"advertising_days_min":0,"advertising_days_max":500,"home_type":["apartment","house"],"construction_year_min":1850,"contract_date_start":"1850-01-01","contract_date_end":"2024-08-05","distance_center":false,"error_code":0,"excluded_ids":[],"limit":15,"living_area_min":0,"living_area_max":500,"monthly_fee_min":0,"monthly_fee_max":12000,"price_min":0,"price_max":12000000,"rooms_min":0,"rooms_max":10
}'