: Hem
Resursen PlaceType |
Resursen Place |
Datum |
Geolocation |
Föräldrar och barn |
Felhantering |
Hämta plats |
Uppdatera plats |
Skapa / ersätta plats |
Ta bort plats |
Tvingande fält |
API:t exponerar två entiteter: PlaceType och Place.
Entiteten PlaceType är endast en sträng som motsvarar namnet på platstypen.
Resursen anropas på /placetype och returnerar ett svar enligt:
HTTP GET /placetype
["ChurchAndChapel", "ParishHome", "Secretariat", ... ]
Denna kan användas för att undersöka vilka olika platstyper som kan beskrivas av API:t, till exempel för att fylla en dropdownlista i ett redigeringsgränssnitt.
Resursen anropas på /place och returnerar en dynamiskt uppbyggd entitet som kan innehålla all typ av data som kan kopplas till en plats.
En plats kan vara en av flera olika typer, och detta representeras som en property på entiteten Place som har en egen uppsättning properties.
Entiteten place har alltid följande properties (dom är aldrig null eller tom sträng):
{
id**:string
parent: {
id*:string // Id för platsens föräldraplats, om den har en sådan.
name:string // Namn för platsens föräldraplats, om den har en sådan.
}
name*:string // Platsens namn.
slug*:string // En unik sträng som lämpar sig för länkning etc.
// Baseras dock på ägarens namn samt platsens namn, så den är unik, men inte
// permanent. Ändras platsens namn ändras slug:en, osv.
shortDescription:string // Kort beskrivning om platsen. Innehåller endast text, ingen formattering.
created*:datetimeoffset // När platsen skapades.
createdBy***:string // Vem som skapade platsen.
updated*:datetimeoffset // När platsen senast ändrades/skapades.
updatedBy***:string // Vem som ändrade platsen.
geolocation: { // GeoJSON (2016) feature, innehållande en punkt https://geojson.org/
type: "Feature"
geometry: {
type: "Point",
coordinates: [17.123, 59.22] // Koordinater enligt GeoJSON (WGS84, i ordning longitud, latitud)
}
}
owner: { // Enheten som platsen ägs av eller hör till.
id*:string // Anger id för ägaren
name*:string // Anger namnet för ägaren
type*:string // Anger typen som ägaren är. Kan vara en enhetstyp inom Svenska kyrkans
// organisation, eller 'Projekt' när platsen hör till ett sådant.
}
placeTypes: { ... } // Finns alltid och har alltid ett underobjekt. Se längre ned för
// beskrivning om typer.
...
}
Nedanstående properties finns på entiteten i de fall de har ett värde. Det gäller även de properties som hör till en under-entitet - de properties som har värdet null tas ej med i svaret. Tomma strängar eller strängar med bara blanktecken får värdet null.
{
...
longDescription:string // Längre, eventuellt formatterad beskrivning om platsen. Formattering TDB, eventuellt markdown.
published*:datetimeoffset // Om en plats är publicerad så har detta fält ett värde, och värdet bestämmer
// från när platsen kan dyka upp i sökningar
publishedBy***:string // Vem som publicerade platsen.
depublished*:datetimeoffset // Om platsen avpubliceras automatiskt så har detta fält ett värde, och värdet
// bestämmer när platsen inte längre dyker upp i sökningar
depublishedBy***:string // Vem som avpublicerade platsen.
deleted*:datetimeoffset // Borttagningsdatum. Indikerar att platsen är borttagen. Borttagna platser
// visas som standard inte i sökresultat utan att man explicit ber om dom.
deletedBy***:string // Vem som tog bort platsen.
geolocationInfo: { // Information om vart platsen ligger rent geografiskt, utifrån fältet `geolocation`.
// Uppdateras automatiskt varje gång platsen uppdateras. Det innebär att informationen
// ibland kan vara gammal. Se fältet `updated` för att se hur gammal den är.
lkf*:string, // LKF:en (kod för län-kommun-församling)
county*:string, // Län
municipality*:string, // Kommun
city*:string, // Stad, är i princip alltid tom
localArea*:string, // Stadsdel, är i princip alltid tom
country*:string // Land
}
contactInfo: {
address:string // OBSOLETE Gatuadress. Använd visitingInfo
postalCode:string // OBSOLETE Postkod. Använd visitingInfo
city:string // OBSOLETE Stad. Använd visitingInfo
visitingAddress:string // OBSOLETE Besöksadress. Använd visitingInfo
phone: PhoneNumber{
CountryCode:int // Landskod.
AreaCode:int // Riktnummer.
Number:int // Lokalt telefonummer.
}
email:string // Kontaktepost.
url:string // URL till kontaktsida.
fetchAutomatically:bool // Hämtar kontaktinfo för den ägande enheten automatiskt om true.
// Notera att kontaktinfo då inte sparas i databasen utan hämtas då det efterfrågas.
// Finns det innehåll i ett fält i contactInfo så överrider det datat som hämtats för det fältet.
}
visitingInfo: {
address:string // Gatuadress.
postalCode:string // Postkod.
city:string // Stad.
description:string // Vägbeskrivning eller annan beskrivning.
}
openHours: [ // Platsens öppettider, om den har sådana.
// Innehåller en lista med öppettider som gäller för olika perioder.
// Alla datum och tider är implicit angivna i platsens lokala tidszon.
// Löst baserat på https://schema.org/OpeningHoursSpecification
{
validFrom:date-string, // En datumsträng i ISO-format (YYYY-MM-DD) som anger när öppettiderna börjar gälla.
// Kan vara tom sträng eller null om det är den första i listan
validTo:date-string, // En datumsträng i ISO-format (YYYY-MM-DD) som anger när öppettiderna slutar gälla (inklusive)
// Kan vara tom sträng eller null om det är den sista i listan
days: {
mo: [{
from:time-string // Tidpunkt för öppning i timmar och minuter, i 24-timmarsformat (tex "08:00")
to:time-string // Tidpunkt för stängning i timmar och minuter, i 24-timmarsformat (tex "17:00")
}]
tu: [ ... ]
we: [ ... ]
th: [ ... ]
fr: [ ... ]
sa: [ ... ]
su: [ ... ]
}
}
],
placeDetails: {
info:string // Fritextbeskrivning om platsen. Kan tex vara information om wifi, caféet,
// parkeringen eller annat.
hasToilet*:bool
hasWifi*:bool
hasCafe*:bool
hasChargingStation:bool
hasParking:bool
accessibility: {
info:string // Fritextbeskrivning om tillgänglighet på platsen
toiletAccessible:bool
toiletSoapNonAllergenic:bool
hasHearingLoop:bool
hasRamp:bool
}
}
categories: [{ // Platsens kategorier (gemensamma ämnesområden)
id*:string // Id på kategorin. (UUID från källan med kategorier)
name:string
}]
tags: [{ // Platsens taggar (lokala ämnesområden)
id*:string // Id på taggen. (UUID från källan med taggar)
name:string
}]
placeTypes: { // Platsens typ. Endast en är angiven, alltid. Övriga är då null/finns inte med i datat.
churchAndChapel: { } // Kyrkor och kapell
parishHome: { } // Församlingshem
secretariat: { } // Kansli
cemetery: { } // Begravningsplats
external: { } // Extern, om ingen platstyp anges används denna.
pollingStation: { } // Röstningslokal
mainPollingStation: { } // Vallokal
}
media: { // Eventuellt media och länkar kopplade till platsen
audio***: [{ // Någon typ av ljudspår
tags: string[] // Rekommenderat, men ej tvingande, fält för att ange nyckelord
// till ljudspåret, till exempel kan nyckelordet
// 'audioguidning' användas för att särskilja sådana typer av
// ljudspår från andra typer, typ som 'intromusik', 'klockringning'
// eller annat kul.
url: string // Eventuellt obligatoriskt*1. Url till ljudfilen om den enkelt kan länkas till
providerRef: string // Eventuellt obligatoriskt*1. Ljudfilens referens/id hos den provider som den ligger på
provider: string // Eventuellt obligatoriskt*1. Provider som ljudfilen ligger lagrad hos. Valfritt namn som
// behöver vara känt för producenter och konsumenter av platser
title: string // Obligatoriskt. Namn/titel på ljudfilen
description: string // Valfritt. Beskrivning på ljudfilen
}]
video***: [{ // Någon typ av video
tags: string[] // Rekommenderat, men ej tvingande, fält för att ange nyckelord
// till videon.
url: string // Eventuellt obligatoriskt*1. Url till videofilen om den enkelt kan länkas till
providerRef: string // Eventuellt obligatoriskt*1. Videons referens/id hos den provider som den ligger på
provider: string // Eventuellt obligatoriskt*1. Provider som videon ligger lagrad hos. Valfritt namn som
// behöver vara känt för producenter och konsumenter av platser
title: string // Obligatoriskt. Namn/titel på videon
description: string // Valfritt. Beskrivning på videon
descriptionType: string // Valfritt. Beskrivning av extern videotyp
}]
images***: [{ // Någon typ av bild
tags: string[] // Rekommenderat, men ej tvingande, fält för att ange nyckelord till
// bilden, till exempel kan nyckelordet '360image' användas för att
// enkelt hitta åt 360-bilder bland övriga bilder.
url: string // Eventuellt obligatoriskt*2. Url till bilden om den enkelt kan länkas till
providerRef: string // Eventuellt obligatoriskt*2. Bildens referens/id hos den provider som den ligger på
provider: string // Eventuellt obligatoriskt*2. Provider som bilden ligger lagrad hos. Valfritt namn som
// behöver vara känt för producenter och konsumenter av platser
title: string // Obligatoriskt. Namn/titel på bilden
description: string // Valfritt. Beskrivning på bilden
alternateDescription:string // Valfritt men rekommenderat: Bildbeskrivning tex för tillgänglighet. Lämplig tex
// för en img-taggs alt-attribut.
}]
links: [{ // Relevanta länkar kring platsen
tags: string[] // Nyckelord till länken. Kan vara praktiskt om man behöver särskilja olika typer
// av länkar.
url:string // Länkens måladress
title:string // Länkens titel/namn
qr:string // Adress till QR-representation för länken. Om angiven så går adressen rendera direkt
// tex i en img-tagg
}]
}
}
Eventuellt obligatoriskt*1: Antingen så måste url anges, eller så måste ref och provider anges. Alla 3 får anges och då skall url anses vara backup-värde för en enklare visning av objektet
Eventuellt obligatoriskt*2: Antingen så måste url anges, eller så måste ref och provider anges. Alla 3 får anges och då skall url anses vara backup-värde för en enklare visning av objektet
***: Fälten är endast synliga för anropare med speciell rättighet.
**: Fältet Id är sökbart med speciella restriktioner. Se Sökning för mer information.
*: Fältet är sökbart. Se Sökning för mer information.
En kommentar ang Media.Audio.Tags/Media.Images.Tags: Det är helt upp till producenten/konsumenten av objekten att ange och tolka nyckelorden, Det är dock högst rekommenderat att endast använda små bokstäver och endast siffror och bokstäver, inga mellanslag, bindestreck eller annat.
För att få hårdkodat testdata för att kunna inspektera hela datamodellen, lägg till queryparameter test=true
HTTP GET https://api.svenskakyrkan.se/platser/v4/place/some-id-whatever?test=true
Observera att du även vid testdata måste ange en giltig apinyckel.
Svaret som ges är en plats som har alla fält ifyllda, inklusive Depublished, Deleted samt alla platstyper. Det är
alltså inte en domänkorrekt plats, men alla fält har värden så man kan se hur dom ser ut.
Alla datum som används vid filtrering, sökning och uppdatering skall vara formaterade i ett subset av ISO 8601:
| Format | Exempel | Betyder |
|---|---|---|
| YYYYMMDD | 20141224 | den 24 december 2014 |
| YYYY-MM-DD | 2014-12-24 | den 24 december 2014 |
| YYYYMMDDTHHmmZ | 20141224T1200+01:00 | kl 12:00 UTC+1, den 24 december 2014 |
| YYYY-MM-DDTHH:mmZ | 2014-12-24T12:00+01:00 | kl 12:00 UTC+1, den 24 december 2014 |
| YYYYMMDDTHHmmssZ | 20141224T120005-06:00 | kl 12:00:05 UTC-6, den 24 december 2014 |
| YYYY-MM-DD-THH:mm:ssZ | 2014-12-24T12:00:05-06:00 | kl 12:00:05 UTC-6, den 24 december 2014 |
| YYYYMMDDTHHmmss.fffZ | 20141224T120005.123-06:00 | kl 12:00:05.123 UTC-6, den 24 december 2014 |
| YYYY-MM-DDTHH:mm:ss.fffZ | 2014-12-24T12:00:05.123-06:00 | kl 12:00:05.123 UTC-6, den 24 december 2014 |
Z i formaten ovan kan även vara strängen Z (stort z) vilket då betyder UTC+0.
Observera: Endast formatet YYYY-MM-DDTHH:mm:ss.fffffZ exponeras utåt från API:t. Det vill säga, alla properties på alla objekt som håller ett datum följer det formatet, oavsett vilket format som användes när propertyn fick sitt värde.
Koordinaten för en plats anges i GeoJSON-format (2016), närmare bestämt som en punkt.
Koordinater anges i WGS84. Observera att ordningen på koordinaterna är longitud, latitud, enligt specen.
En plats kan höra ihop med en annan plats. Detta styrs genom fältet 'Parent', där man anger vilken plats som är platsens förälder eller huvudplats. En plats kan bara ha en förälder, men en förälder kan ha flera barn som är kopplade till den platsen.
Det går inte att ha en relation i fler än två nivåer. En förälder kan inte ha en egen förälder och ett barn kan inte ha egna barn.
Barnplatser returneras som standard inte vid en sökning. Se Sökning
Vad som ska hända med barn när man uppdaterar eller tar bort en förälder går att styra genom att ange childAction som en queryparameter. Denna parameter tar emot en kommaseparerad lista med värden.
Se Uppdatera föräldraplatser och Ta bort föräldraplatser för information om vilka värden man kan ange i de olika fallen.
API:t är ett REST API som därmed följer HTTP-standarden för de olika metoderna som går att utföra.
Generellt gäller att om något är felaktigt angivet i anropet så svarar API:t med 400 Bad Request, tillsammans med en textuell beskrivning av vad som gått fel.
Om något internt fel sker returnerar API:t 500 Internal Server Error tillsammans med en textuell beskrivning av felet, om möjligt.
Alla funktioner som utför ändringar på en plats kräver att man har behörighet till det som skall utföras. Om behörighet saknas returneras 403 Forbidden.
HTTP GET /place/<id>
APIt svarar med 200 OK om platsen fanns, och 404 Not Found om den inte fanns.
Om platsen fanns returneras den i sin helhet som en JSON-payload till svaret:
{
id: "<id>",
name: "Botkyrka kyrka",
...
}
För att hämta flera platser utifrån en lista med id:n, se Sökning
Nedanstående anrop kommer att sätta platstypen till secretariat och därmed eventuellt ändra platstypen om den tidigare
var angiven som något annat.
Samtidigt sätts ett nytt namn på platsen, vilket i sin tur kommer att uppdatera fältet slug automatiskt.
Dessutom tas alla eventuella öppettider bort.
HTTP PATCH /place/<id>
{
updatedBy: "en-användare",
name: "Botkyrka nya församlingshem",
openHours: null,
placeTypes: {
secretariat: {}
}
}
Observera: Vid uppdatering av listor ersätts alltid hela listans innehåll.
För att ta bort en property så anger man den i anropet med värdet null, som i exemplet ovan. Notera dock att visa properties inte kan ha värdet null. Se Tvingande fält nedan för mer information.
Om platsen inte fanns returneras 404 Not Found, om den fanns och uppdateringen var lyckas returneras 204 No Content samt en http header Location som pekar på platsens unika adress som då är place/<id>.
Om man uppdaterar publiseringsdatum på en plats med barn så uppdateras som standard inte publiseringsdatumet för de barnen. Detta kan ändras genom att lägga till värdet set-published i queryparametern childAction (Se Föräldrar och barn).
Om man uppdaterar avpubliseringsdatum på en plats med barn så kommer alla dess barn också att uppdateras så att de får samma avpubliseringsdatum. Detta kan ändras genom att lägga till värdet skip-depublished i queryparametern childAction.
Nedanstående anrop kan antingen köras till url:en /place för att skapa en ny plats, eller till url:en /place/<id> för att fullständigt ersätta en befintlig plats:
HTTP PUT /place
{
updatedBy: "en-användare",
name: "",
...
placeTypes: { church: {} }
...
}
Om anropet körs till /place och korrekta värden är angivna så kommer platsen att skapas och tillbaka returneras 201 Created
med hela platsen som content, samt header Location som är angiven till den kompletta adressen till den nya platsen.
Om anropet körs till /place/<id> och korrekta värden är angivna så kommer platsen att skrivas över och tillbaka returneras 200 Ok
med hela platsen som content.
Som standard så tillåts inte over-posting, det vill säga att man anger fält som inte går att ändra, såsom id, slug eller
categories[].name. Om man explicit vill tillåta detta kan man ange allowOverposting=true. Då kommer den typen av validering
att skippas.
För att ta bort en plats körs en HTTP DELETE till url:en /place/<id>?deletedby=<deletedby>:
HTTP DELETE /place/00000000-0000-0000-000000000001?deletedby=Bob%20Builder
Om platsen inte fanns så returneras 404 Not Found, om deletedby inte är angiven eller är tom returneras 400 Bad Request. Om allt gick bra så returneras 204 No Content.
Parametern deletedby måste anges för att man ska få spårbarhet över vem som har tagit bort en viss plats, fältet DeletedBy på platsen uppdateras alltså med parameter deletedby.
Fältet Deleted på platsen uppdateras med tidpunkten då platsen togs bort.
Platsens slug ändras till
Om man tar bort en plats med barn så kommer som standard också barnen att tas bort. Detta kan ändras genom att lägga till värdet disconnect i queryparametern childAction (Se Föräldrar och barn).
Om man gör det kommer barnen inte att tas bort, men de kommer inte längre ha någon koppling till deras förälder. De blir alltså helt fristående platser.
Vissa fält är tvingande att ange i vissa fall och vissa fält skall aldrig anges i ett anrop. Nedan följer en beskrivning över de fält som har specialregler som behöver följas:
| Fält | Tvingande i metod | Får ej anges i metod | Beskrivning |
|---|---|---|---|
| Id | Får aldrig anges | ||
| Name | Skapa plats | Får aldrig sättas till null | |
| Slug | Får aldrig anges | Denna beräknas vid skapande av en plats | |
| Created, Updated, Deleted | Får aldrig anges | Sätts automatiskt till aktuell tid när så behövs | |
| CreatedBy, DeletedBy, PublishedBy, DepublishedBy | Får aldrig anges | ||
| UpdatedBy | Skapa/Uppdatera/ersätt plats | Får aldrig sättas till null | |
| Published | 'Published' kan vara en tidpunkt både framåt eller bakåt i tiden. Kan sättas till null om platsen ska anses vara ett utkast. | ||
| Depublished | 'Depublished' kan vara en tidpunkt både framåt eller bakåt i tiden, men om den anges, och Published har ett värde, måste den vara större än Published. Kan sättas till null om platsen aldrig ska avpubliceras | ||
| owner_id, owner_type | Skapa | Får aldrig sättas till null. | |
| geolocation_geometry_coordinates | Skapa plats | Får aldrig sättas till null |
Sökning finns mer detaljerat beskrivet här.