Søk API

Søkeendepunkt i ulike miljøer

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

Dokumentasjon

OpenAPI-spesifikasjon for søkeendepunktet (Swagger)

Slik får du tilgang

API-et er åpent for offentlig bruk og krever ingen autentisering. Du kan begynne å bruke endepunktet umiddelbart.

Hastighetsbegrensning

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

• 10 forespørsler per minutt (requests per minute)
• Burst-grense på 20 forespørsler (2x multiplikator)

Hvis du overskrider disse grensene, vil du motta en HTTP 429 (Too Many Requests) respons.

Utforming av spørringer

Du kan søke mot endepunktet med helt enkle spørringer. I eksempelet under har vi søkt på test. Denne spørringen vil gi treff på alle ressurser som har ordet test i tittel, beskrivelse eller søkeord.

KopierKopier
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øke på gjennom søketjenesten. Disse er 'title'(tittel), 'description'(beskrivelse) og 'keyword'(søkeord). Søket vil som utgangspunkt prøve å finne treff på spørringen i alle tre feltene, men det er mulig å definere hvilke(t) felt det skal inkludere i søket.

I eksempelet nedenfor har vi avgrenset søket til å kun søke i feltet 'description'(beskrivelse).

KopierKopier
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 prioriteres over andre, for eksempel vil et treff på tittel vektes høyere enn et treff i feltet for beskrivelse.

La oss bruke tittelen "test søkendepunkt demo " og de to spørringene "test demo" og "søkeendepunkt demo". Den første spørringen vil ha to delvise treff, "test" og "demo", med en kombinert søkeverdi på 15 + 15 = 30. Den andre spørringen vil ha tre treff, hvor to er delvise treff, "søkeendepunkt" og "demo", og et er et nøyaktig treff på frase, "søkeendepunkt demo", med en kombinert søkeverdi på 15 + 15 + 30 = 60.

Spesifikke ressurstyper

Hver ressurstype som er tilgjengelige på Data.norge.no har sitt eget endepunkt.

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

KopierKopier
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 mulig å tilpasse antall treff og sidenummer med pagineringsfeltet i søket.

Eksempel på bruk av pagineringsfelt, med gjeldende side satt til nummer 5 og hvor det er 10 treff på siden:

KopierKopier
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 mulig å filtrere på søkeresultatet. Du finner en oversikt over mulige søkefiltre og hvilken type verdier de aksepterer i OpenAPI-spesifikasjonen for søketjenesten.

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

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

KopierKopier
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 bruker vi format-filteret for å få treff som inneholder mediatypen JSON.

KopierKopier
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

Hvert søkeresultat vil inneholde aggregeringer av spørringen med mulige filterverdier. Det er alltid inkludert en verdi for hvert filter, dette er en liste over filtreringsmulighetene representert i det totale søkeresultatet og en telling av hvor mange treff som treffer hver filtreringsmulighet.

Gitt at dette søket:

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

Gir følgende agreggering i resultatet:

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

Så vil det neste eksempelet gi fem treff i sitt resultat, fordi de aggregerte verdiene viser at spørringen gir fem treff hvor verdien for access rights (tilgangsrettigheter) er PUBLIC (tilgjengelige for allmennheten) og 16 hvor verdien er RESTRICTED (begrenset).

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