Versions Compared

Version Old Version 22 New Version 23
Changes made by

Anders Abrahamsen

Jarl Totland

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Innhold og datakilder

EDR Realty RestAPI gir deg tilgang til eiendomsregisteret med det meste av informasjon om eiendommer og borettsandeler fra offentlige registre i Norge samlet på ett sted. Registeret inneholder nyttig informasjon om juridiske, tekniske og økonomiske forhold

Innhold

Tjenestene inneholder det meste av offentlig tilgjengelig informasjon for alle:

  • Eiendommer

  • Borettslag og borettsandeler

  • Adresser og steder

  • Boliger og bygninger

  • Personer med en relasjon til eiendom eller borettsandel

Datakilder

Tjenestene benytter blant annet data fra følgende offentlige datakilder:

  • Grunnboken: Norges offentlige register over tinglyste rettigheter og heftelser i fast eiendom og borettslagsandeler.

  • Matrikkelen: Norges offisielle eiendomsregister. Inneholder oversikt over alle eiendommer, boliger/bygninger og adresser.

  • Folkeregisteret: Norges offisielle personregister. Inneholder nøkkelopplysninger om alle personer som er eller har vært bosatt i Norge.

  • Enhetsregisteret: Enhetsregisteret samordner grunndata om enheter i næringslivet og offentlig sektor.

  • Posten: Oversikt over alle poststeder i Norge.

  • SSB: Norges offisielle statistikk relatert til økonomi, befolkning og samfunnet på nasjonalt, regionalt og lokalt nivå.

  • Landbruksregisteret: Gir informasjon om ressursgrunnlag, lokalisering og eierforhold på landbrukseiendommer i Norge.

  • Stedsnavnsregisteret: Norges offisielle register over stedsnavn i offentlig bruk

  • Riksantikvaren: Offisielle databaser over fredete kulturminner og kulturmiljøer i Norge.

  • Miljødirektoratet: informasjon om forurensning i grunnen og hvor det er mistanke om forurensning i Norge

  • Andre: Lovdata (konsesjonsforhold), NVE (ras og flomsoner), Statens kartverk (kartgrunnlag), m.fl.

Kom i gang

For å få en god forståelse for alt Realty sitt REST API har å tilby kan man lese gjennom resten av dokumentet. Men dersom man bare vil komme i gang er det en enkel oppskrift her.

Bruk av EDR Realty RestAPI

Støttetjenester

Dokumentasjon Swagger: Velg «swagger» under «Eiendom» og du kunne se og prøve ut tjenestene v.h.a. swagger-brukergrensesnittet (Swagger er et verktøy for dokumentasjon og samhandling resttjenester). Se  https://beta-api.ambita.com/realty/v1/assets/lib/swagger-ui/index.html?url=https://beta-api.ambita.com/realty/api-docs

Testklient: Ved hjelp av testklienten kan en enkelt prøve ut tjenestene for søk oppslag, samt benytte lenker videre til relaterte tjenester. For å benytte testklienten fult ut må en installere en JSON-viewer i nettleseren en benytter. Se: https://beta-api.ambita.com/realty/v1

Ordboken: EDR Realty RestAPI benytter engelsk. Om en ønsker å se norske begreper den integrerte ordboktjenesten benyttes:

Dette kan også benyttes indirekte til å oversette et svar i JSON til norsk for enhver ressurs ved å legge til parameter:AcceptLanguage:Norwegian. (Denne funksjonen er for øyeblikket ikke tilgjengelig!)

Autentisering

Ambita sine APIer bruker en egenimplementert autentisering som følger OAuth2 spesifikasjonen (se https://oauth.net/2/). Alle kall mot APIet må inneholde en header parameter som ser slik ut:

Code Block
Authorization: Bearer <UUID token>

Dette tokenet er ikke-informasjonsbærende men alle API tjenester kan validere det og finne ut om den som utfører kallet har tilstrekkelig rettigheter. Om man ikke har det vil man få 401 Unauthorized i retur.

Man får tak i et token ved å kalle authentication på URL (dette er for beta):

POST https://beta-api.ambita.com/authentication/v2/token med enten:

  • client_credentials flow: client_id og client_secret
    Dette brukes for sikker server til server kommunikasjon

  • non confidential password flow: client_id, bruker og passord
    Dette brukes for usikker klient til server kommunikasjon, f.eks. fra nettleser. Med usikker menes her at man ikke har kontroll på stedet trafikken mot APIet kommer fra. All trafikk mot APIene er kryptert.

  • confidential password flow: client_id, client_secret, bruker og passord
    Dette brukes for sikker flyt der identifikasjon av sluttbruker er vesentlig. Kommunikasjon mot API må da komme fra en server slik at ikke client_secret kan lekke. Denne flyten blir ikke brukt så ofte.

Se: Swagger UI create token for dokumentasjon på selve tjenesten.

Autentiseringstjenesten gir tilgang til alle Ambita sine APIer. Hvilke eksakte tilganger man har er styrt av scopes (se https://oauth.net/2/scope/). En klient har et sett med scopes som blir tilordnet alle tokens som opprettes. Et scope kan f.eks. være realty.basic som gir tilgang til alle basistjenestene i Realty sitt API. Når man kaller en tjeneste vil man få 401 Unauthorized dersom man mangler et gyldig scope.

Et token har normalt gyldighet i en time. Sammen med access tokenet følger det med et refresh token som kan benyttes til å opprette et nytt access token dersom dette går ut på tid. Merk at dersom et access token blir benyttet like før det utløper kan dette medføre at kallet likevel feiler da det i noen tilfeller blir validert flere ganger i prosessen. Dette kan unngås ved at man ikke benytter et token som har mindre varighet enn en par sekunder.

Realty har en rekke scopes og de tildeles etter avtale. For detaljer se https://beta-api.ambita.com/realty/v1/scopes/

PS! Merk at alle brukere av APIet vil få tildelt egne klienter for bruk mot BETA miljø og PROD miljø. Prøver man å bruke en BETA klient i produksjon vil ikke dette virke.

Generell beskrivelse

EDR Realty RestAPI er benytter rene REST-operasjoner. Resultatet leveres som JSON-dokumenter.

REST: REST (Representational State Transfer) er designet for å utnytte eksisterende protokoller. REST kan brukes over nesten hvilken som helst protokoll (vanligvis benyttes HTTP når i web-APIer). Utviklere ikke trenger å installere biblioteker eller tilleggsprogramvare for å kunne dra nytte av en REST API. REST API Design ble definert av Dr. Roy Fielding i sin 2000 doktorgradsavhandling. Det er kjent for sitt utrolige lag av fleksibilitet. For nærmere beskrivelse se:https://en.wikipedia.org/wiki/Representational_state_transfer

JSON: JSON (JavaScript Object Notation) er en enkel tekstbasert standard for å formatere meldinger som brukes for datautveksling. Den er opprinnelig avledet fra JavaScript for å representere enkle datastrukturer. Standarden er imidlertid uavhengig av JavaScript eller andre programmeringsspråk. For ytterligere informasjon, se: https://json.org/

Konvolutt: Vi har valgt å bruke konvolutt i stedet for et JSON-element eller et JSON-array. Tjenestene svarer med data i JSON-formatet med en konvoluttstruktur i retur. Konvolutten inneholder en liste over elementer fra søkeressursen (List<Item>, Pagination og Error) eller generell oppslagsressurs (Item og Error)

Ident og nøkkel: Et objekt er identifisert ved hjelp av en ident. En ident kan bestå av flere felter. For eksempel er identen til en eiendom kommunenr, gardsnr, bruksnr, festenr og seksjonsnr. 

Code Block
 ident: {
   municipalityNumber:301,
   cadastralUnitNumber:1,
   unitNumber:1,
   leaseholdUnitNumber:0,
   sectionNumber:0,
   section:false
 }

Alle ressurser har i tillegg et nøkkelfelt. Det feltet er strengen du bruker når du henter samme ressurs med et oppslag. Nøkkelen er en sammenstilling av feltene som i Ident-strukturen

Eksempel på matrikkelnøkkel: 301-1-1-0-0

Eksempler oppslag:

Lenker: For å forenkle videre søk fra en tjeneste til neste er det lagt til lenker i tjenestene. Lenker er lagt inn for det mest brukte kallsekvensene som benyttes. For eksempel kan en for en eiendom benytte lenker for å finne eiere, adresser, boliger og bygninger til denne eiendommen Lenker fra eiendom til eiere 
Eksemplel lenke fra eiendom til eiere:

Code Block
languagejson
links: { 
  self: { 
    rel: “Cadastre”, 
    href: “https://beta-api.ambita.com/realty/v1/cadastres/3006-8189-88-0-0” 
  }, 
  owners: { 
    rel: “Person”, 
    href: “https://beta-api.ambita.com/realty/v1/cadastres/3006-8189-88-0-0/owners/”
  }
}

Kvalifisering lenker:

  • Skille mellom søk og opplag. Tjenester for søk og opplag har samme navn, men det framgår av lenke om det er søk eller oppslag:

    • Søk eiendom: search/cadastres

    • Opplag eiendom: cadastres

  • Tjenester med de samme data for eiendommer og borettsandeler som eierforhold og omsetninger, men der det framgår av om det er eiendom eller borettsandel:

    • Eierskap eiendom: cadastre/ownerships

    • Eierskap borettsandel: share/ownerships

Kategorier: Tjenestene er inndelt i fem kategorier:

Alle tjenestene i samme kategori skal oppføre seg på samme måte. Det er også svært små forskjeller mellom de forskjellige kategoriene. To typene skiller seg ut:

  • Støtteressursene som ikke følger noen spesifikke regler.

  • Oppslaget av egne ident som alltid returnerer en enkel forekomst.

Paginering: En tjeneste som returnerer en liste over elementer vil også returnere et paginasjonselement for å gi brukeren muligheten til å aksessere mange elementer Der ytterligere filtrering ikke er mulig. Paginering styres gjennom variablene: pagesize (sidestørrelse) og page (side). Hvis du ber om side = 2 og sidestørrelse = 10, får du element 11-20.

Parameringsmuligheter: Flere av tjenestene har ulike parameringsmuligheter for å forenkle bruken av tjenestene. Hvilke parameringsmuligheter som støttes vil framgå av dokumentasjonen til den enkelte tjeneste. Eksempler på slike parameringsmuligheter:

  • Generelt:

    • Posisjon: positions=true/false: Inkludere posisjonsdata i JSON-retur til bruk for eksempel ved visning av objekter i kart. Default=false

    • Språk: AcceptLanguage:Norwegian/english: Om navn, strukturer og felter skal returneres på engelsk eller norsk. Default=engelsk

  • Eierforhold og omsetninger:

    • Eiernivå: onlyMaxCadastreLevel=true/false eiendom og onlyMaxShareLevel=true/false: Angir om en ønsker alle eller bare høyeste eiernivå for en eiendom (hjemmel, feste, framfeste) eller borettsandel (hjemmel, borett). Vanligvis er en bare interessert i høyeste eiernivå da det er eier av høyeste eiernivå som disponerer eiendommen / borettandelen. Default=false

    • Fritt salg: freeMarketOnly=true/false: Angir om bare omsetninger av type «fritt salg» (utlyst og solgt i det åpne markedet) vise. Default=false

    • Eier: hasProperty=true/false. Filtrere bort personer som ikke eier eiendommer eller borettsandeler. Default=false

    • Sortering: sortByDateDescending=true/false. Angir om dokumenter skal returneres i synkende eller stigende datorekkefølge. Default=false

  • Adresser:

    • Søk på eksakt adressenr (husnr): exactAddressNumber=true/false: Angir om en ønsker at tegn for tegn søk returnerer alle adresser med som starter med oppgitt adressenr (husnr) (som 1, 11.19 om en oppgir 1) eller bare adresse med eksakt oppgitt adressenr (husnr). Default=false

Typer tjenester

Søk: Søketjenestene hjelper deg å finne fram til ønsket objekt selv om du ikke kjenner identen til objektet. Du kan for eksempel finne en eiendom selv om du ikke kjenner matrikkelen til eiendommen ved å søke på eiernavn, adresse, koordinat, m.m. Søketjenestene gir mulighet for tegn for tegn søk

Eierskap: Viser oversikt over eiendommer og borettsandeler en person eller organisasjon eier, med informasjon om tilhørende boliger / bruksenheter, bygninger og adresser

Basistjenester: Basistjenester viser detaljert informasjon om ulike objekter. Informasjonen er hentet fra ulike offentlige registre. For en eiendom kan en for eksempel se informasjon om eiere, eiendomsgrenser og areal, adresser, boliger og bygninger, belåning, begrensninger, servitutter m.m. Tjenestene viser både aktiv og historisk informasjon

Stedfesting og kartvisning: Tjenester som kan benyttes for å plassere objekter (for eksempel eiendommer, bygninger / boliger og omsetninger) i kart. Kan benyttes mot Ambitas kartløsninger, men også mot andre kartløsninger som Google Maps.

Verdiøkte tjenester: Verdiøkte tjenester viser bearbeidet informasjon om ulike objekter. Eksempler på bearbeidet informasjon er beregnet boligverdi, pant (lån) presentert i prioritetsrekkefølge med gjeldende kreditor og beløp, m.v.

Oversikt tjenester

Søk og oppslag

Søke og oppslagstjenester som hjelper en å finne fram til ønsket objekt selv om du ikke kjenner identen til objektet. Søketjenestene gir mulighet for:

  • Query: Tegn for tegn søk (som for eksempel ønsket antall tegn i et gatenavn for å få returnert alle gater som starter med den oppgitte tegnstrengen. Krav om at minimum 3 tegn oppgis. Søk foretas v.h.a. elastic seach engine for å ivareta ulike skrivemåter, ulik rekkefølge på felter, m.v.

  • Oppslag: Oppslag med relaterte identer (som for eksempel oppslag med adresse for å finne en eiendom der en ikke kjenner eiendommens matrikkel). Ved opplag v.h.a. relaterte identer returneres lister med ingen, en eller flere forekomster.

Image RemovedImage Added

Lenker fra ressursene går til Realty beta av Swagger UI for APIet vårt. Dette gjør vi fordi de som starter å ta i bruk APIet ikke har produksjonstilgang. Da er det lettere å gjøre testing mot beta.

Hovedlenke til swagger for beta og prod miljø er: Swagger UI Realty Beta og Swagger UI Realty Prod

Opplisting av ressurser:

Eierskap

Viser oversikt over eiendommer og borettsandeler en person eller organisasjon eier, med informasjon om tilhørende boliger / bruksenheter, bygninger og adresser.

Basistjenester

Basistjenester viser detaljert informasjon om ulike objekter. Informasjonen er hentet fra ulike offentlige registre. For en eiendom kan en for eksempel se informasjon om eiere, eiendomsgrenser og areal, adresser, boliger og bygninger, belåning, begrensninger, servitutter m.m. Tjenestene viser både aktiv og historisk informasjon.

Stedfesting og kartvisning

Tjenester som kan benyttes for å plassere objekter (for eksempel eiendommer, bygninger / boliger og omsetninger) i kart. Kan benyttes mot Ambitas kartløsninger, men også mot andre kartløsninger som Google Maps.

  • Stedfesting:

    • Omsetningsdokument i kart. POCs er forkortelse for Points of Conveyance og stedfester omsetningsinformasjon, se: /realty/v1/pocs/

Verdiøkte tjenester

Verdiøkte tjenester viser bearbeidet informasjon om ulike objekter. Eksempler på bearbeidet informasjon er beregnet boligverdi, pant (lån) presentert i prioritetsrekkefølge med gjeldende kreditor og beløp, m.v.