Søk API

Søkjeendepunktet lar deg søkje på Data.norge.no med Elastic search. Tenesten som er ansvarleg for å handtere søk er fdk-search-service(Github).

Viktig: Dette API-et vert nytta internt i tenesteutviklinga på Data.norge.no, og kan av den grunn bli endra over tid. Vi anbefaler ikkje å nytte dette API-et om ein er avhengig av stabilitet og konsistens.

Endepunkt i ulike miljø

Produksjonsmiljø: https://search.api.fellesdatakatalog.digdir.no/search
Demomiljø: https://search.api.demo.fellesdatakatalog.digdir.no/search

Dokumentasjon

OpenAPI-spesifikasjon for søkjeendepunktet (Swagger)

Slik får du tilgang

API-et er ope for offentleg bruk og krev ingen autentisering. Du kan byrje å nytte endepunktet med ein gong.

Hastigheitsavgrensing

API-et har hastigheitsavgrensing (rate limiting) konfigurert for å sikre stabil drift. Avgrensningane er:

10 førespurnader per minutt (requests per minute)
Burst-grense på 20 førespurnader (2x multiplikator)

Viss du overskrid desse grensene, vil du motta ein HTTP 429 (Too Many Requests) respons.

Utforming av spørjingar

Du kan søkje mot endepunktet med heilt enkle spørjingar. I eksempelet under har vi søkt på test. Denne spørjinga vil gje treff på alle ressursar som har ordet test i tittel, beskriving eller søkeord.

Kopier
curl -X POST 'https://search.api.demo.fellesdatakatalog.digdir.no/search' \
  -H 'Content-Type: application/json' \
  -d '{"query":"test"}'

Søkbare felt

Det er tre søkbare felt du kan søkje på gjennom søkjetenesta. Desse er 'title'(tittel), 'description'(beskriving) og 'keyword'(søkeord). Søket vil som utgangspunkt prøve å finne treff på spørjinga i alle tre feltane, men det er mogleg å definere kva for eit felt det skal inkludere i søket.

I eksempelet nedanfor har vi avgrensa søket til å berre søkje i feltet 'description'(beskriving).

Kopier
curl -X POST 'https://search.api.demo.fellesdatakatalog.digdir.no/search' \
  -H 'Content-Type: application/json' \
  -d '{"query":"test", "fields": {"title":false, "description":true, "keyword":false}}'

Vekting av søketreff

Treff i enkelte felt vert prioritert over andre, til dømes vil eit treff på tittel vektast høgare enn eit treff i feltet for beskriving.

Felt	Vekting
tittel, nøyaktig treff på frase	30
tittel, delvis treff på frase	15
søkeord	5
beskriving	1

La oss nytte tittelen "test søkjeendepunkt demo " og dei to spørjingane "test demo" og "søkjeendepunkt demo". Den fyrste spørjinga vil ha to delvise treff, "test" og "demo", med ein kombinert søkeverdi på 15 + 15 = 30. Den andre spørjinga vil ha tre treff, hvor to er delvise treff, "søkjeendepunkt" og "demo", og eit er eit nøyaktig treff på frase, "søkjeendepunkt demo", med ein kombinert søkeverdi på 15 + 15 + 30 = 60.

Spesifikke ressurstypar

Kvar ressurstype som er tilgjengelege på Data.norge.no har sitt eige endepunkt.

Ressurstype	Endepunkt
Datasett	'/datasets'
API-ar	'/data-services'
Omgrep	'/concepts'
Informasjonsmodellar	'/information-models'
Tenester	'/services'
Hendingar	'/events'

I dette eksempelet går spørjinga vår mot endepunktet for datasett i demomiljøet.

Kopier
curl -X POST 'https://search.api.demo.fellesdatakatalog.digdir.no/search/datasets' \
  -H 'Content-Type: application/json' \
  -d '{"query":"test"}'

Paginering

Alle søkeresultat vil være paginert, det er mogleg å tilpasse antall treff og sidenummer med pagineringsfeltet i søket.

Eksempel på bruk av pagineringsfelt, med gjeldande side satt til nummer 5 og kor det er 10 treff på sida:

Kopier
curl -X POST 'https://search.api.demo.fellesdatakatalog.digdir.no/search' \
  -H 'Content-Type: application/json' \
  -d '{"query":"test","pagination":{"size":10,"page":5}}'

Filtrering

Det er mogleg å filtrere på søkeresultatet. Du finn ei oversikt over moglege søkefiltre og kva type verdiar dei godtek i OpenAPI-spesifikasjonen for søkjetenesta.

Her har vi filtrert på feltet datatema, med verdien for miljø.

Kopier
curl -X POST 'https://search.api.demo.fellesdatakatalog.digdir.no/search' \
  -H 'Content-Type: application/json' \
  -d '{"query":"test","filters":{"dataTheme":{"value":["ENVI"]}}}'

I dette eksempelet filtrerer vi på åpne data.

Kopier
curl -X POST 'https://search.api.demo.fellesdatakatalog.digdir.no/search' \
  -H 'Content-Type: application/json' \
  -d '{"query":"test","filters":{"openData":{"value":true}}}'

Og her brukar vi format-filteret for å få treff som inneheld mediatypen JSON.

Kopier
curl -X POST 'https://search.api.demo.fellesdatakatalog.digdir.no/search' \
  -H 'Content-Type: application/json' \
  -d '{"query":"test","filters":{"formats":{"value":["MEDIA_TYPE application/json"]}}}'

Aggregering

Kvart søkeresultat vil innehalde aggregeringar av spørjinga med moglege filterverdiar. Det er alltid inkludert ein verdi for kvart filter, dette er ei liste over filtreringsmoglegheitene representert i det totale søkeresultatet og ei telling av kor mange treff som treffer kvar filtreringsmoglegheit.

Gitt at dette søket:

Kopier
curl -X POST 'https://search.api.demo.fellesdatakatalog.digdir.no/search' \
  -H 'Content-Type: application/json' \
  -d '{"query":"test"}'

Gjev følgjande agreggering i resultatet:

Kopier
"aggregations":{"accessRights":[{"key":PUBLIC","count":5},{"key":"RESTRICTED","count"16}]}

Så vil det neste eksempelet gje fem treff i resultatet sitt, fordi dei aggregerte verdiane viser at spørjinga gjev fem treff kor verdien for access rights (tilgangsrettigheter) er PUBLIC (tilgjengelige for allmenta) og 16 kor verdien er RESTRICTED (avgrensa).

Kopier
curl -X POST 'https://search.api.demo.fellesdatakatalog.digdir.no/search' \
  -H 'Content-Type: application/json' \
  -d '{"query":"test","filters":{"accessRights":{"value":["PUBLIC"]}}}'