API-referanse

Basis-URL: https://graveinfo.no/api/v1

GET/organizations/searchbeta

Søker etter infrastruktureiere og/eller entreprenører. Støtter fritekst, org.nr.-oppslag, kommunefilter og paginering. Krever scope organizations:read (valgfritt - anonym tilgang med lavere rate limit er tillatt).

Eksempel

http

GET /api/v1/organizations/search?q=Hafslund&type=owner&limit=5
Authorization: Bearer gv_live_...

Query-parametere

Parameter	Type	Påkrevd	Beskrivelse
`q`	string	Nei*	Fritekst - søker i navn og org.nr.
`orgnr`	string	Nei*	Eksakt org.nr.-oppslag (9 siffer). Kan ikke kombineres med q.
`type`	enum	Nei	"owner" (standard), "contractor" eller "all".
`municipality`	string	Nei	4-sifret kommunenummer. Filtrerer på kommunedekning (kun for type=owner eller all).
`limit`	integer	Nei	Maks resultater per side. Standard: 20, maks: 100.
`offset`	integer	Nei	Hopp over N resultater. Brukes for paginering. Standard: 0.

* Minst ett av q eller orgnr må oppgis, ellers returneres tom liste.

Responsskjema (200 OK)

json

{
  "data": [
    {
      "id": "org_...",
      "name": "Hafslund Nett AS",
      "orgnr": "980489698",
      "type": "owner",
      "address": "Drammensveien 144, 0277 Oslo",
      "email": "post@hafslundnett.no",
      "phone": null,
      "website": "https://www.hafslundnett.no",
      "gravemottak": "api",
      "claimed": true
    }
  ],
  "meta": {
    "total": 1,
    "limit": 5,
    "offset": 0
  }
}

Feltbeskrivelser

id
string

Unik intern ID for organisasjonen.

name
string

Registrert navn.

orgnr
string

9-sifret norsk organisasjonsnummer.

type
"owner" | "contractor"

Infrastruktureier eller entreprenør.

address
string | null

Postadresse.

email
string | null

Offentlig e-postadresse.

phone
string | null

Telefonnummer.

website
string | null

Nettsted.

gravemottak
"api" | "email" | "none" | null

"api" = mottar via Graveinfo-plattformen, "email" = e-postvarsel, "none" = ikke registrert. null for entreprenører.

claimed
boolean

true hvis organisasjonen har bekreftet profilen sin.

Feilkoder

400INVALID_PARAMETERUgyldig verdi på ett av parameterne. Feltet er oppgitt i error.field.

401INVALID_API_KEYManglende eller ugyldig API-nøkkel.

429RATE_LIMIT_EXCEEDEDFor mange kall. Vent til neste minutt.

500INTERNAL_ERRORIntern feil. Prøv igjen om noen sekunder.

json

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "type must be one of: owner, contractor, all",
    "field": "type"
  }
}

GET/coverage

Returnerer alle infrastruktureiere registrert i den oppgitte kommunen. Nyttig for å bygge oversikter og for å finne hvem som er mottakere av gravemeldinger i et område. Krever scope organizations:read.

Eksempel

http

GET /api/v1/coverage?municipality=0301
Authorization: Bearer gv_live_...

Query-parametere

Parameter	Type	Påkrevd	Beskrivelse
`municipality`	string	Ja	4-sifret kommunenummer (f.eks. 0301 for Oslo).
`type`	string	Nei	Filtrer på infrastrukturtype (f.eks. vann_avlop, hoyspenning). Returnerer kun eiere med denne typen.

Responsskjema (200 OK)

json

{
  "municipality": {
    "number": "0301",
    "name": "Oslo"
  },
  "owners": [
    {
      "id": "org_...",
      "name": "Oslo VAV",
      "orgnr": "970205420",
      "infrastructureTypes": ["vann_avlop"],
      "gravemottak": "api",
      "email": "gravemottak@oslo.kommune.no"
    },
    {
      "id": "org_...",
      "name": "Hafslund Nett AS",
      "orgnr": "980489698",
      "infrastructureTypes": ["lavspenning", "hoyspenning"],
      "gravemottak": "api",
      "email": "gravemottak@hafslundnett.no"
    }
  ],
  "total": 2
}

Feltbeskrivelser - owners[]

id
string

Intern ID for organisasjonen.

name
string

Navn på infrastruktureier.

orgnr
string | null

9-sifret norsk organisasjonsnummer.

infrastructureTypes
string[]

Infrastrukturtyper registrert for denne kommunen (f.eks. vann_avlop, hoyspenning, lavspenning).

gravemottak
"api" | "email" | "none"

"api" = håndteres via Graveinfo-plattformen, "email" = e-postvarsel, "none" = ikke registrert.

email
string | null

Kontakt-e-post for gravemottak.

Feilkoder

400MISSING_PARAMETERmunicipality-parameteret er ikke oppgitt.

400INVALID_PARAMETERmunicipality er ikke et 4-sifret tall.

401UNAUTHORIZEDManglende eller ugyldig API-nøkkel.

404MUNICIPALITY_NOT_FOUNDKommunenummeret finnes ikke i Graveinfo.

429RATE_LIMIT_EXCEEDEDFor mange kall. Vent til neste minutt.

GET/gravemeldinger

Lister gravemeldinger for din organisasjon, sortert nyeste først. Krever scope gravemeldinger:read og en organisasjons-API-nøkkel (ikke en entreprenør-nøkkel).

Eksempel

http

GET /api/v1/gravemeldinger?status=sent&limit=10
Authorization: Bearer gv_live_...

Query-parametere

Parameter	Type	Påkrevd	Beskrivelse
`status`	enum	Nei	"draft", "sent", "in_progress" eller "completed".
`from`	ISO 8601	Nei	Vis kun gravemeldinger opprettet på eller etter denne datoen.
`to`	ISO 8601	Nei	Vis kun gravemeldinger opprettet på eller før denne datoen.
`limit`	integer	Nei	Maks resultater per side. Standard: 20, maks: 100.
`offset`	integer	Nei	Hopp over N resultater. Standard: 0.

Responsskjema (200 OK)

json

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "referenceNumber": "GI-2026-00042",
      "status": "sent",
      "title": "Graving Storgata 12",
      "plannedStart": "2026-06-01",
      "plannedEnd": "2026-06-14",
      "createdAt": "2026-05-28T10:00:00.000Z",
      "sentAt": "2026-05-28T10:00:01.000Z",
      "summary": {
        "total": 8,
        "responded": 3,
        "pending": 5,
        "hasConflicts": false
      }
    }
  ],
  "meta": {
    "total": 42,
    "limit": 10,
    "offset": 0
  }
}

Statuskoder

draftUtkast - ikke sendt ennå.

sentSendt - venter på svar fra mottakere.

in_progressAlle har svart - behandles videre.

completedFullført eller arkivert.

Feilkoder

400INVALID_PARAMETERUgyldig verdi på ett av parameterne.

401INVALID_API_KEYManglende eller ugyldig API-nøkkel.

403FORBIDDENNøkkelen mangler scope gravemeldinger:read, eller er ikke en organisasjonsnøkkel.

429RATE_LIMIT_EXCEEDEDFor mange kall. Vent til neste minutt.

POST/gravemeldinger

Oppretter og sender umiddelbart en gravemelding til alle relevante infrastruktureiere i det oppgitte området. Mottakere finnes automatisk basert på polygon-overlapp med kommunedekning i Graveinfo.

Krever scope gravemeldinger:write og en entreprenør-API-nøkkel (nøkkel koblet til en godkjent entreprenørprofil i Graveinfo).

Rate limit: 10 POST-kall per minutt - strengere enn andre endepunkter. Design systemet ditt for å batche eller spre sendingene over tid.

Polygon-koordinater: Koordinater MÅ bruke EPSG:25833 (UTM sone 33N). WGS84-koordinater (bredde-/lengdegrad) gir feil NO_MUNICIPALITY-feil. Se guiden for sending av gravemeldinger for konverteringseksempler.

Eksempel

http

POST /api/v1/gravemeldinger
Authorization: Bearer gv_live_...
Content-Type: application/json

{
  "title": "Graving Storgata 12",
  "description": "Legging av fiberkabel langs Storgata 12-18",
  "work_types": ["telekommunikasjon", "grunnarbeid"],
  "polygon": {
    "type": "Polygon",
    "coordinates": [
      [
        [258000, 6648000],
        [258100, 6648000],
        [258100, 6648100],
        [258000, 6648100],
        [258000, 6648000]
      ]
    ]
  },
  "planned_start": "2026-06-01",
  "planned_end": "2026-06-14",
  "contact_person": "Ola Nordmann",
  "contact_phone": "91234567",
  "adresse": "Storgata 12, Oslo"
}

Request body-felt

title
string (påkrevd)

Kort beskrivelse av arbeidet.

work_types
string[] (påkrevd)

Arbeidstyper. Minst én. Gyldige verdier: telekommunikasjon, vann_avlop, hoyspenning, lavspenning, veiarbeid, grunnarbeid, fjernvarme, annet.

polygon
GeoJSON Polygon (påkrevd)

Arbeidsområdet. type="Polygon", coordinates i EPSG:25833 (UTM sone 33N).

planned_start
string (påkrevd)

Planlagt startdato, format YYYY-MM-DD.

planned_end
string (påkrevd)

Planlagt sluttdato, format YYYY-MM-DD.

contact_person
string (påkrevd)

Navn på kontaktperson.

contact_phone
string (påkrevd)

Telefonnummer til kontaktperson.

description
string (valgfritt)

Utfyllende beskrivelse av arbeidet.

adresse
string (valgfritt)

Gateadresse for arbeidsstedet.

Responsskjema (201 Created)

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_number": "GI-2026-00042",
  "status": "sendt",
  "kart_frist": "2026-06-07",
  "pavisning_frist": "2026-06-11",
  "municipality_names": ["Oslo"],
  "recipient_count": 8,
  "created_at": "2026-05-28T10:00:00.000Z",
  "sent_at": "2026-05-28T10:00:01.000Z"
}

Feltbeskrivelser - respons

reference_number
string

Menneskelig lesbart referansenummer, f.eks. GI-2026-00042.

kart_frist
date

Frist for kartrespons - 5 virkedager fra sendingstidspunkt.

pavisning_frist
date

Frist for påvisning - 7 virkedager fra sendingstidspunkt.

municipality_names
string[]

Kommuner som polygonet overlapper med.

recipient_count
integer

Antall infrastruktureiere som ble varslet.

Feilkoder

400MISSING_FIELDSEtt eller flere påkrevde felt mangler. Feltene er listet i error.fields.

400INVALID_WORK_TYPEEn av work_types-verdiene er ugyldig. Gyldige verdier listes i error.message.

400INVALID_POLYGONPolygon-objektet er ikke gyldig GeoJSON.

400NO_MUNICIPALITYIngen norsk kommune ble funnet for polygonets koordinater. Koordinater må bruke EPSG:25833.

400NO_RECIPIENTSIngen infrastruktureiere er registrert i det oppgitte området.

401UNAUTHORIZEDManglende eller ugyldig API-nøkkel.

403FORBIDDENNøkkelen er ikke koblet til en entreprenørprofil, eller mangler scope gravemeldinger:write.

429RATE_LIMIT_EXCEEDEDFor mange kall. Maks 10 POST per minutt.

500SERVER_ERRORIntern feil. Prøv igjen om noen sekunder.

json

{
  "error": {
    "code": "MISSING_FIELDS",
    "message": "Mangler påkrevde felt: polygon, planned_end",
    "fields": ["polygon", "planned_end"]
  }
}

GET/gravemeldinger/:id

Returnerer full informasjon om én gravemelding, inkludert mottakerliste og svarstatus fra hver infrastruktureier. Polygon returneres konvertert til WGS84 (EPSG:4326). Du kan kun hente dine egne gravemeldinger. Krever scope gravemeldinger:read.

Eksempel

http

GET /api/v1/gravemeldinger/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer gv_live_...

Responsskjema (200 OK)

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "referenceNumber": "GI-2026-00042",
  "status": "in_progress",
  "title": "Graving Storgata 12",
  "location": {
    "type": "Polygon",
    "coordinates": [
      [[10.7522, 59.9139], [10.7533, 59.9139], [10.7533, 59.9148],
       [10.7522, 59.9148], [10.7522, 59.9139]]
    ]
  },
  "plannedStart": "2026-06-01",
  "plannedEnd": "2026-06-14",
  "createdAt": "2026-05-28T10:00:00.000Z",
  "sentAt": "2026-05-28T10:00:01.000Z",
  "recipients": [
    {
      "organizationId": "org_...",
      "name": "Oslo VAV",
      "status": "responded",
      "response": "conflict",
      "responseNote": "Vi har ledninger i dette området.",
      "respondedAt": "2026-05-29T08:30:00.000Z"
    },
    {
      "organizationId": "org_...",
      "name": "Hafslund Nett AS",
      "status": "pending",
      "response": null,
      "responseNote": null,
      "respondedAt": null
    }
  ],
  "summary": {
    "total": 8,
    "responded": 3,
    "pending": 5,
    "hasConflicts": true
  }
}

Feltbeskrivelser - recipients[]

organizationId
string

Intern ID for mottakerorganisasjonen.

name
string | null

Navn på organisasjonen.

status
"pending" | "responded"

Om mottakeren har svart.

response
"no_conflict" | "conflict" | "needs_meeting" | null

"conflict" = har infrastruktur i området, "no_conflict" = ingen konflikt, "needs_meeting" = trenger avklaring, null hvis ikke svart.

responseNote
string | null

Fritekstkommentar fra mottaker.

respondedAt
ISO 8601 | null

Tidspunkt for svar.

Feilkoder

401INVALID_API_KEYManglende eller ugyldig API-nøkkel.

403FORBIDDENNøkkelen mangler scope gravemeldinger:read.

404NOT_FOUNDGravemeldingen finnes ikke, eller tilhører en annen organisasjon.

429RATE_LIMIT_EXCEEDEDFor mange kall. Vent til neste minutt.

Fullstendig maskinlesbar spec er tilgjengelig i docs/openapi.yaml i kildekoden. Flere endepunkter (PATCH gravemeldinger, webhooks) er under utvikling. Følg med på endringsloggen for nye tillegg.