Opprett eiendommer

POST /external/properties/ legger til en eiendom i en mappe fra dine egne systemer, for eksempel når en ny eiendom registreres i eiendomsregisteret ditt. Du sender matrikkelnummeret, og Telescope finner tomten, starter analysene og henter bygningene og energiattestene.

Før du begynner

Opprettelse må være aktivert for organisasjonen din. Be kontaktpersonen din i Telescope om å slå det på. Inntil da returnerer forespørslene 403 med koden external_api_create_not_allowed. Lesing fungerer uansett.
Bare Norge. Eiendommer finnes ut fra det norske matrikkelnummeret.
Mapper kommer fra appen. API-et kan ikke opprette mapper. Opprett dem i Telescope, og finn ID-ene deres med GET /external/portfolios/.

Kort eksempel

curlPythonPowerShell

curl -X POST https://api.telescope.eco/external/properties/ \
  -H "X-API-Key: $TELESCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "internal_reference_id": "P-1001",
    "portfolio_id": "b2a4c7e0-1d2f-4f39-8e2a-5c6d7e8f9a01",
    "name": "Storgata 1",
    "address": "Storgata 1",
    "postal_code": "0155",
    "postal_area": "Oslo",
    "country": "Norway",
    "matrikkelnummer": "0301-208/101",
    "value_estimate": 85000000
  }'

python

import requests

response = requests.post(
    "https://api.telescope.eco/external/properties/",
    headers={"X-API-Key": "your-secret"},
    json={
        "internal_reference_id": "P-1001",
        "portfolio_id": "b2a4c7e0-1d2f-4f39-8e2a-5c6d7e8f9a01",
        "name": "Storgata 1",
        "address": "Storgata 1",
        "postal_code": "0155",
        "postal_area": "Oslo",
        "country": "Norway",
        "matrikkelnummer": "0301-208/101",
        "value_estimate": 85_000_000,
    },
    timeout=60,
)
response.raise_for_status()
prop = response.json()
print(response.status_code, prop["id"])  # 201 when created, 200 when updated

powershell

$body = @{
    internal_reference_id = "P-1001"
    portfolio_id          = "b2a4c7e0-1d2f-4f39-8e2a-5c6d7e8f9a01"
    name                  = "Storgata 1"
    address               = "Storgata 1"
    postal_code           = "0155"
    postal_area           = "Oslo"
    country               = "Norway"
    matrikkelnummer       = "0301-208/101"
    value_estimate        = 85000000
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
    -Uri "https://api.telescope.eco/external/properties/" `
    -Headers @{ "X-API-Key" = $env:TELESCOPE_API_KEY } `
    -ContentType "application/json" `
    -Body $body

Svaret er hele eiendommen, i samme format som GET /external/properties/{id}/, med status 201 Created for en ny eiendom eller 200 OK for en oppdatert eiendom.

Felter i forespørselen

Felt	Påkrevd	Type	Beskrivelse
`portfolio_id`	Ja	UUID	Mappen eiendommen skal legges i. Må tilhøre organisasjonen din. Ignoreres når eiendommen finnes fra før, se nedenfor.
`country`	Ja	tekst	Må være `Norway`.
`matrikkelnummer`	Ja	tekst	Tomtens norske matrikkelnummer, for eksempel `0301-208/101/0/0`. Brukes til å finne tomten. Se Matrikkelnummer.
`internal_reference_id`	Nei, men anbefalt	tekst, maks 255	Din egen ID for eiendommen. Hvis det allerede finnes en eiendom med denne referansen, oppdateres den i stedet for at det opprettes en ny.
`name`	Nei	tekst, maks 255	Visningsnavn i Telescope. Blir adressen hvis det mangler, eller matrikkelnummeret hvis det heller ikke finnes en adresse.
`address`	Nei	tekst, maks 255	Gateadresse, for eksempel `Storgata 1`. Lagres bare for visning og brukes aldri til å finne tomten.
`postal_code`	Nei	tekst, maks 255	Postnummeret til adressen.
`postal_area`	Nei	tekst, maks 255	Poststedet til adressen.
`value_estimate`	Nei	heltall eller `null`	Verdiestimat i NOK, fra 0 til 999 999 999 999.

Send JSON med Content-Type: application/json. Ukjente felter ignoreres.

Matrikkelnummer

Matrikkelnummeret er det Telescope bruker for å finne eiendommens tomt, og dermed geometrien alle analysene kjøres på. Skriv det som kommune-gnr/bnr/fnr/snr:

Inndata	Lagres som
`0301-208/101/0/0`	`0301-208/101/0/0`
`0301-208/101`	`0301-208/101/0/0`

Kortere former godtas og lagres alltid i full lengde. Hvis verdien ikke er et matrikkelnummer i det hele tatt, for eksempel en adresse, feiler forespørselen med invalid_matrikkelnummer. Hvis det er gyldig, men ingen tomt blir funnet, feiler den med property_geometry_not_found.

Lange nummer

Tomter med gårdsnummer eller bruksnummer på mer enn fire sifre, eller festenummer på mer enn tre, kan ikke slås opp ennå og gir property_geometry_not_found.

Hva skjer etter at du har opprettet en eiendom

Telescope validerer forespørselen og slår opp tomten ut fra matrikkelnummeret. Dette skjer før noe lagres, så et mislykket oppslag oppretter ingenting.
Eiendommen lagres og returneres med en gang. hazards og biodiversity er fortsatt tomme, og som regel er buildings og energy_certificates det også.
I bakgrunnen kjører Telescope analysene for eiendommen og henter bygningene og energiattestene.
Hent eiendommen på nytt senere med GET /external/properties/{id}/ for å lese resultatene etter hvert som de kommer.

Opprett eller oppdater

internal_reference_id gjør det trygt å kalle endepunktet flere ganger:

Situasjon	Resultat
Ingen `internal_reference_id` sendt	Det opprettes alltid en ny eiendom. Et nytt forsøk etter en feilet forespørsel kan lage duplikater.
Ingen eiendom har denne referansen ennå	Det opprettes en ny eiendom i `portfolio_id`. `201 Created`.
Én eiendom har denne referansen	Den eiendommen oppdateres der den er. `200 OK`.
Flere eiendommer deler denne referansen	`400` med koden `ambiguous_internal_reference_id`. Rydd opp i duplikatene i appen først.

Når en eiendom oppdateres:

Den blir liggende i mappen den er i nå. portfolio_id er fortsatt påkrevd og blir validert, men eiendommen flyttes ikke. Flytt den i appen.
Felter du utelater, beholder verdiene sine. Felter du sender, erstatter dem.
Analysene kjøres på nytt bare hvis tomten er endret, det vil si når det nye matrikkelnummeret gir en annen geometri.
Bygninger og energiattester hentes på nytt bare hvis matrikkelnummeret er endret. De som ble hentet for den gamle tomten, fjernes, og de som er lagt til for hånd i appen, beholdes. Bygningene for den nye tomten hentes bare hvis det ikke er noen bygninger igjen, og energiattestene bare hvis det ikke er noen energiattester igjen. En bygning eller energiattest som er lagt til for hånd, gjør altså at nye av samme slag ikke hentes.

Forespørsler med samme referanse behandles én om gangen, så to systemer som sender den samme eiendommen samtidig, kan ikke lage to kopier.

Tips

Send alltid internal_reference_id, med ID-en fra kildesystemet ditt. Da kan integrasjonen sende alt på nytt ved hver kjøring uten å lage duplikater.

Masseimport fra en CSV-fil

Endepunktet oppretter én eiendom per forespørsel. For å importere mange går du gjennom radene dine i en løkke. Takket være internal_reference_id kan du kjøre skriptet på nytt etter at du har rettet radene som feilet.

python

import csv

import requests

session = requests.Session()
session.headers["X-API-Key"] = "your-secret"
PORTFOLIO_ID = "b2a4c7e0-1d2f-4f39-8e2a-5c6d7e8f9a01"

with open("properties.csv", newline="", encoding="utf-8") as file:
    for row in csv.DictReader(file):
        response = session.post(
            "https://api.telescope.eco/external/properties/",
            json={
                "internal_reference_id": row["reference"],
                "portfolio_id": PORTFOLIO_ID,
                "address": row["address"],
                "postal_code": row["postal_code"],
                "postal_area": row["postal_area"],
                "country": "Norway",
                "matrikkelnummer": row["matrikkelnummer"],
            },
            timeout=60,
        )
        if response.ok:
            print(f"{row['reference']}: {response.status_code}")
        else:
            print(f"{row['reference']}: failed, {response.json()}")

Feil

Valideringsfeil returnerer 400 med én oppføring per felt. For eksempel et matrikkelnummer uten tomt:

json

{
  "matrikkelnummer": {
    "detail": "Couldn't find a plot for this matrikkelnummer.",
    "code": "property_geometry_not_found"
  }
}

Status	Felt	Kode	Betydning
400	`matrikkelnummer`	`required`, `blank`	Matrikkelnummeret mangler eller er tomt.
400	`matrikkelnummer`	`invalid_matrikkelnummer`	Verdien er ikke et norsk matrikkelnummer.
400	`matrikkelnummer`	`property_geometry_not_found`	Det ble ikke funnet noen tomt for det.
400	`country`	`invalid_choice`	Landet er ikke `Norway`.
400	`portfolio_id`	`does_not_exist`	Ingen mappe med denne ID-en i organisasjonen din.
400	`internal_reference_id`	`ambiguous_internal_reference_id`	Flere eiendommer deler denne referansen.
400	`value_estimate`	`min_value`, `max_value`, `invalid`	Verdien er negativ, for stor eller ikke et heltall.
401		`authentication_failed`	API-nøkkelen mangler eller er ugyldig.
403		`external_api_create_not_allowed`	Opprettelse er ikke aktivert for organisasjonen din.

Se Feil for det generelle feilformatet.

Opprett eiendommer ​

Kort eksempel ​

Felter i forespørselen ​

Matrikkelnummer ​

Hva skjer etter at du har opprettet en eiendom ​

Opprett eller oppdater ​

Masseimport fra en CSV-fil ​

Feil ​