Versions Compared

Version Old Version 11 New Version Current
Changes made by

Anders Abrahamsen

Jarl Totland

Saved on

Key

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

...

  • 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

...

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/api-landingpage/swagger2/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.

...

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/12433006-558189-24488-0-2”0” 
  }, 
  owners: { 
    rel: “Person”, 
    href: “https://beta-api.ambita.com/realty/v1/cadastres/12433006-558189-24488-0-20/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 , men der det framgår av om det er eiendom eller borettsandeborettsandel:

    • Eierskap eiendom: cadastre/ownerships

    • Eierskap borettsandel: share/ownerships

Kategorier: Tjenestene er inndelt i fem kategorier:

...

  • 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.

...

  • en eller flere forekomster.

...

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:

...

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.

...