Søk i Person‑API
Dette dokumentet forklarer hoved‑endepunktene for søk i Person‑API, valideringsreglene som hver forespørsel må oppfylle, og hvordan resultatene sorteres.
- /search/person – Enkelt‑kall‑søk
- /search/paged-match-list – Bulk‑søk med paginering
- /search/match-count – Totalt antall treff
- /event/filtered – Filtrerte hendelser
/search/person – Enkelt‑kall‑søk
Utfører en engangs‑spørring og returnerer de første 100 unike person‑dokumentene som matcher de angitte kriteriene. Endepunktet støtter ikke paginering; dersom flere enn 100 personer matcher, returneres kun de første 100.
Minimumskrav til en forespørsel
- Navnefelt – minst ett av følgende må være tilstede:
GivenName,MiddleName,FamilyNameellerFullName. - To bokstaver totalt – når alle navnefeltene settes sammen, skal strengen inneholde minst to alfabetiske tegn (mellomrom ignoreres).
- Tilleggsfilter – ett av følgende må også angis:
BirthDate(minst år)MunicipalityNumber(nøyaktig fire sifre)PostalCode(nøyaktig fire sifre)StreetAddresssom inneholder minst tre bokstaver (mellomrom ignoreres)
Disse reglene hindrer altfor brede søk og holder belastningen på databasen på et akseptabelt nivå.
Parametere
| Felt | Beskrivelse |
|---|---|
| BirthDate | Personens fødselsdato, ISO‑8601 format YYYY‑MM‑DD. Kun år (YYYY) eller år‑og‑måned (YYYY‑MM) er også akseptert. |
| Gender | Personens kjønn (Female/Male). |
| FullName | Hele eller deler av personens fulle navn, kun bokstaver, maks 600 tegn. Strengen splittes i inntil tre søkeord; hvert ord må inneholde minst én bokstav, og samlet må ordene ha minst to bokstaver. Overskytende søkeord ignoreres. |
| GivenName, MiddleName, FamilyName | Del av respektive navnedeler, kun bokstaver, maks 200 tegn. |
| StreetAddress | Gatenavn med husnummer/husbokstav, maks 200 tegn. |
| PostalCode | Postnummer – nøyaktig fire sifre. |
| CityName | Stadnavn, kun bokstaver, maks 100 tegn (det samme som norsk “poststed”). |
| MunicipalityNumber | Kommunenummer – nøyaktig fire sifre. |
| Valgfrie flagg | InformationParts, IncludeAINs, IncludeHistory – styrer hvilke deler av person‑dokumentet som inkluderes. IncludeAINs gir også personer med alternativ identifikasjonsnummer. |
Resultat
Svaret inneholder hele person‑dokumentet, dvs. alle personopplysninger (inkludert sensitive felter). Kun de første 100 treffene returneres, sortert etter den interne database‑identifikatoren (den naturlige rad‑rekkefølgen). Ingen ekstra sorteringsalternativer er tilgjengelige.
/search/paged-match-list – Bulk‑søk med paginering
Når du trenger store resultater, returnerer /paged-match-list kun unike Person‑ID‑er sammen med paginerings‑indekser (startIndex og endIndex). Kallet kan justeres ved å endre offset. Person‑ID‑ene er interne referanser som genereres av Persontjenesten.
Paginering
| Parameter | Beskrivelse |
|---|---|
| PageSize | Maksimalt antall ID‑er som returneres i ett kall. Standard er 1 000, maksimalgrense er 10 000. |
| IndexOffset | Null‑basert startposisjon i det totale resultatet. For første kall utelates eller settes til 0. Etter hvert svar settes neste IndexOffset til endIndex + 1. |
| Slutt | Når antallet ID‑er i svaret er mindre enn PageSize, er slutten av settet nådd. |
Sortering
Resultatene sorteres stabilt etter intern DB‑ID. Dette sikrer konsistent paginering selv om poster settes inn, oppdateres eller slettes mens klienten henter data.
Akseptable søkekriterier
Det er ikke påkrevd å bruke søkefelt her – alt kan være tomt. Alle navn‑ og adressefelt som er tilgjengelige i /search kan også brukes, pluss noen ekstra filtre som kun gjelder bulk‑søket:
Parametere
| Felt | Beskrivelse |
|---|---|
| BirthDateFrom / BirthDateTo | Inkluderende intervall for fødselsdato (ISO‑format; år‑kun eller år‑og‑måned er tillatt). |
| DeathDateFrom / DeathDateTo | Inkluderende intervall for dødsdato (samme format som fødselsdato). |
| BasicStatisticalUnit | Fullt grunnstatistisk enhets‑nummer (8 sifre). |
| PersonStatuses | Liste med strenger som beskriver personens relasjon til Norge/Folkeregisteret. |
| PageSize / IndexOffset | Kontroll av paginering (se ovenfor). |
De samme “to‑bokstaver”‑ og “minst ett navnefelt”‑reglene gjelder, men feltene er valgfrie så lenge det samlede minimumskravet (navn + én ekstra filter) er oppfylt.
Resultat
JSON‑payloaden inneholder kun en liste med PersonId‑verdier samt startIndex og endIndex. Ingen personlige detaljer eksponeres. Resultatene kan brukes i et oppslag via /person/bulk-by-id.
/search/match-count – Totalt antall treff
Virker på samme måte som paged-match-list med hensyn til søkekriterier, men returnerer kun det totale antallet treff som ville blitt returnert. Brukes for å anslå hvor mange resultater et søk vil gi uten å hente hele datasettet.
/event/filtered – Filtrerte hendelser
Returnerer en filtrert liste med hendelser for personer som matcher avanserte søkekriterier. Opptil 1 000 hendelses‑dokumenter returneres, startende fra angitt sekvens‑nummer, og filtreres på hendelsestype samt person‑attributter som navn, adresse, kommune, fødsels‑/dødsdato, kjønn og personstatus.
| Felt | Beskrivelse |
|---|---|
| SequenceNumber | Minimum sekvens‑nummer som skal inkluderes i resultatet. Starter på 1. |
| EventTypes | Hvilke hendelsestyper som skal inkluderes. Støtter kommaseparerte verdier. |
| IncludeAinResults | IncludeAINResults – inkluder personer med alternativ identifikasjonsnummer. |
| Maxlimit | Maksimalt antall hendelser som skal returneres. Standard er 1 000. |
Full‑tekst‑søk på FullName
Full‑tekst‑søk tokeniserer strengen og matcher et prefiks hvor som helst i et token. Således vil søkeordet “bo” også matche “dagbok” eller “Bodil”.
Spesifikasjonens krav
- Hvert søkeord må kun matche begynnelsen av en navnedel (fornavn, mellomnavn, etternavn eller en komponent i sammensatt navn).
- Ord kan forekomme i vilkårlig rekkefølge.
- Høyst tre ord brukes; hvert ord må inneholde minst én bokstav, og samlet må ordene inneholde minst to bokstaver.
Søk på spesialtegn
Navnene i søketabellene er normalisert. Alle varianter av en bokstav (f.eks. u‑varianter: ù, ú, û, ü, ũ, ū, ŭ, ů, ű, ų, ư, ǔ, ǖ, ǘ, ǚ, ǜ, ȕ, ȗ, ʉ, ᵤ, ᶙ, ṳ, ṵ, ṷ, ṹ, ṻ, ụ, ủ, ứ, ừ, ử, ữ, ự, ｕ) konverteres til den standardiserte formen “u.”
Derfor har diakritiske tegn i søkestrengen ingen innvirkning på oppslaget – de ignoreres under søket.
Eksempel
Når jeg sender søkeordet “ǨĴëĶś” som FamilyName i test‑miljøet, returnerer systemet en treff på “KJEKS.”
Dette viser at søkelogikken fjerner diakritikk og normaliserer tegn før oppslaget utføres.