APIt - Sökning

Sökning sker genom anrop till url:en /place med query-parametrar:

HTTP GET /place?
deleted=
&is=churchandchapel,secretariat
&name=~otkyrk
&q=sjöutsikt
&placedetails_hastoilet=true
&nearby=17.123,59.22&nearbyRadius=2500

Ovanstående query kommer att returnera de icke-borttagna platser som är av undertyperna churchandchapel eller secretariat har ett namn som innehåller 'otkyrk', har ett fält som någonstans innehåller 'sjöutsikt', har en toalett och ligger inom 2,5km från den angivna punkten.

Svarsobjekt

En lyckad sökning returnerar alltid 200 OK med ett svarsobjekt med följande innehåll:

{
    TotalHits:int               // Anger totala antalet träffar som sökningen resulterade i,
                                // Kan användas för att beräkna antalet sidor som en sökning kan delas upp i
    Results:Place[]             // En lista innehållande efterfrågad sida med platser som matchade sökningen
}

Testdata

För att få hårdkodat testdata för att kunna inspektera hela datamodellen, lägg till queryparameter test=true samt en valfri limit för att ange antal platser som ska ges i svaret. Om limit saknas så returneras 10 stycken platser.

HTTP GET https://api.svenskakyrkan.se/platser/v4/place?test=true

Observera att du även vid testdata måste ange en giltig apinyckel.

Svaret som ges är flera platser som har alla fält ifyllda, inklusive Depublished, Deleted samt alla platstyper. Det är alltså inte domänkorrekta platser, men alla fält har värden så man kan se hur dom ser ut.

Paginering

Paginering stödjs med hjälp av två parametrar: offset samt limit

offset anger hur många platser som skall 'hoppas över'.

limit anger hur många platser som skall returneras. Standardvärdet är 100, och maxvärdet är 500.

Om man anger varken offset eller limit så returneras alltså de 100 första platserna.

Sortering

Sortering stödjs med hjälp utav parametern: orderby

orderby tar emot en kommaseparerad lista med fältnamn som skall användas för sortering. Exempel:

    HTTP GET /place?
    is=churchandchapel,secretariat
    &orderby=owner_type,name

Fältnamnens ordning i listan indikerar i vilken ordning som fälten sorteras. Som standard sorteras resultaten stigande, om du önskar fallande sortering för ett fält kan du ange ett '-' efter ditt fältnamn.

    HTTP GET /place?
    is=churchandchapel,secretariat
    &orderby=name-

Fulltextsök

Alla fält är inte tillgängliga för explicit sökning, däremot finns alla fält representerade i fulltextsök. En fulltextsökning görs med queryparametern q och kan kombineras med explicita sökningar:

HTTP GET /place?
is=churchandchapel,secretariat
&deleted=
&q=sjöutsikt gräs
&placedetails_hastoilet=true
&nearby=17.123,59.22&nearbyRadius=2500

Sökning på null / inte null

För att utföra en sökning där man kontrollerar om ett fält är null eller inte null så kan man ange tomt värde för att ange null, och ! för att ange inte null:

HTTP GET /place?depublished=

Ovanstående kommer att returnera alla platser där depublished saknar ett värde.

HTTP GET /place?depublished=!

Ovanstående kommer att returnera alla platser där depublished inte saknar ett värde.

Om man vill söka på strängvärdet "!" så måste tecknet ! escape:as: \!

Sökning på booleska fält

Sökning på booleska fält görs genom att ange true eller false i söksträngen:

HTTP GET /place?placedetails_hastoilet=true

Sökning på typ

För att söka platser av en viss typ kan den speciella query-parametern is användas.

Den tar en kommaseparerad lista av platstyper där en eller flera måste matcha för att ett objekt ska returneras.

../places?is=churchandchapel,secretariat

Ovanstående kommer att returnera alla platser som antingen är av typen Kyrkor och kapell eller Kansli.

Observera att om man anger en sökning utan is så kommer alla typer förutom Partial att returneras. Detta eftersom man oftast inte vill se del-platser i en normal sökning, endast när man explicit ber om dom.

För att enkelt se precis alla platser av alla typer kan man ange '*':

../places?is=*

Sökning på position

För att söka upp platser som finns i närheten av en viss geografisk punkt använder man de speciella query-parametrarna nearby och nearbyRadius.

nearby är longitud och latitud och nearbyRadius är avståndet i meter.

// Notera att koordinaterna är doubles med punkt som kommatecken och komma som separator mellan värdena
../places?nearby=17.65844,59.833279&nearbyRadius=3000

Ovanstående sökning returnerar då de platser som ligger inom 3 km av Ulleråker i Uppsala

Observera att ordningen är longitud, latitud. En sökning på google ger koordinater i nordliga och östliga koordinater, alltså latitud och longitud: Google maps: Ulleråker Uppsala

Underobjekt och listor

Matchning på ett underobjekts properties samt listor görs genom separatorn _.

// Alla platser som hör till enheter med ett enhetsid som är 1203 eller 1939
owner_id=1203,1939

Sökning i en lista med primitiva värden görs på samma sätt:

// Alla platser som hör till en enhet där minst en av enhetens lkf-koder börjar med 0583
geolocationinfo_lkf=^0583

Likaså söking i en lista med objekt:

// Alla platser som hör till en enhet där minst en del av enheten ligger i en kommun vars namn börjar med motala
geolocationinfo_municipality=^motala

Strängar

Strängvärden kan jämföras med tre olika operatorer: exakt jämförelse, börjar med samt innehåller. Samtliga dessa går dessutom invertera.

Alla jämförelser med strängar är icke skifteslägeskänsliga.

Exakt jämförelse

name=uppsala domkyrka

Strängen måste innehålla det exakta värdet.

name=!uppsala domkyrka

Strängen får inte innehålla det exakta värdet.

Om man vill söka på ett strängvärde som börjar med "!" så måste tecknet ! escape:as: \!uppsala domkyrka

Börjar med

name=^upp

Strängen måste börja med det angivna värdet. ^upp för att matcha 'Uppsala'.

name=!^upp

Strängen får inte börja med det angivna värdet.

Innehåller

Innehåller-sökningar utför en sökning i en sträng som innehåller samtliga ord som börjar med de angivna söktermerna. Söktermer separeras med blanksteg. Enbart strängar som innehåller samtliga söktermer resulterar i en träff, oavsett i vilken ordning söktermerna finns i strängen.

Exempel 1:

placedetails_info=~konfirmation kyrka fika

Strängen måste innehålla alla orden konfirmation, kyrka samt fika. De kan dock finnas vart som helst i strängen, de behöver alltså inte ligga i exakt den ordningen. Det räcker med att orden börjar med de angivna söktermerna. Ovanstående exempel kommer även ge träff på strängar som innehåller orden kyrkan och konfirmationer.

Exempel 2:

name=~s:t ky bi

Exempel 2 skulle till exempel ge träff på platser med namn S:ta Birgitta kyrka och S:t Birgits kyrka.

Invertering av sökningen går att utföra antingen på alla alternativen, eller några få:

name=!~s:t ky bi

Ovanstående skulle endast returnera platser som har ett namn som inte innehåller s:t, ky och bi.

name=~s:t !bi ky

Ovanstående skulle endast returnera platser som har ett namn som innehåller s:t och ky, och som inte innehåller bi.

Om man vill söka på en term som börjar med "!" så måste tecknet ! escape:as: \!bi. Observera dock att det ytterst sällan finns nån anledning till att söka med en term som innehåller "!" så sådana tecken i regel inte tas med i sökindexet.

Flera värden

Man kan även söka på flera värden samtidigt genom att separera värdena med kommatecken. Det går bra att blanda Exakt jämförelse, Innehåller och Börjar med:

name=uppsala,^alboga,~back

Ovanstående returnerar platser med det exakta namnet uppsala eller där namnet börjar med alboga eller innehåller ord som börjar med back.

Om man vill söka på ett värde som innehåller , så måste tecknet , escape:as: \,

Datum

Datum kan anges som exakta värden, som områden eller som en uppsättning värden.

Datum skall alltid anges i ett subset av ISO 8601. Se Generellt om APIt#Datum för mer information.

Exakt värde

created=20141125

Områden

För att ange ett område används tecknet -. Ett område kan vara både öppet och stängt åt ett håll men aldrig åt båda hållen.

created=20141120-20141125

Ovanstående skulle matcha objekt skapade mellan 2014-11-20T00:00:00.000 och 2014-11-25T23:59:59.999

Ett öppet område beskrivs genom att endast ta med det ena värdet:

created=20141120-

Ovanstående matchar objekt som har skapats från och med den 2014-11-20 och framåt.

Uppsättning värden

För att ange en uppsättning värden där endast ett behöver matcha kan dessa separeras med ett kommatecken ,. Detta kan kombineras både med exakta värden och områden.

created=20131224, 20141201-

Ovanstående skulle matcha objekt som var skapade den 2013-12-24, eller skapade efter 2014-12-01.

Opublicerat och borttaget

För en vanlig sökning så filtreras borttagna och opublicerade platser bort. En opublicerad plats har antingen inget publiceringsdatum, ett publiceringsdatum i framtiden eller ett avpubliceringsdatum som är före eller lika med idag. Om man vill att även dessa platser ska inkluderas i svaret använder man query-parametern include tillsammans med värdena deleted och/eller non-published.

include=deleted,non-published

Ovanstående returnerar alla platser, även borttagna och opublicerade.

Visa metadata

För att se namn på ägare, kategorier och taggar (där de finns) i sitt svar så använder man query-parametern expand tillsammans med värdena owner, categories och tags.

expand=owner,categories,tags

Ovanstående returnerar alla platser med namn på ägare och de kategorier och taggar som hittats.

Specialfall Id

Id-fältet är ett specialfall som tillåter sökning på en uppsättning värden, men inget annat:

id=00000000-0000-0000-0000-000000000001,00000000-0000-0000-0000-000000000002