Detta är en sökdriven tjänst för att offentliggöra tillgänglighetsinformation om olika anläggningar runt om i Sverige. Tjänsten är menad att underlätta för personer som vill använda den öppna tillgänglighetsdatan i applikationer. Datan tillhandahålls på två olika sätt:

  • Ett lättanvänt REST API med stöd för grundläggande sökfunktionalitet
  • Ett Solr-index med fullt stöd för Solrs språk för sökfrågor

Som underliggande plattform för att göra den öppna datan sökbar används open source-sökmotorn Solr, som är utvecklad i Apache Lucene-projektet. Mer information om plattformen finns på Solrs hemsida.

Registrering av användare

För att använda tjänsten krävs det att man registrerar sig på TDs hemsida. Man får då en api-nyckel som sedan skall skickas med vid alla anrop mot tjänsten.

Datamodellen består av två olika sorters objekt anläggningar med typen Site och inventariedokument med typen InventoryDocument. Dessa ingår i en godtyckligt djup hierarkisk trädstruktur där roten alltid är av typen Site, och där barnen alltid är av typen InventoryDocument.

Antag t.ex. att en biograf har en av- och påstigningsplats, som i sin tur har en trottoarkant. Då kommer av- och påstigningsplatsen och trottoarkanten representeras av var sitt InventoryDocument-objekt (medan biografen representeras av ett Site-objekt), där av- och påstigningsplatsen har biografen som förälder och trottoarkanten har av- och påstigningsplatsen som förälder.

  • Figur 1: Modelldiagram

Site

Objekt med typen Site representerar anläggningar eller platser som till exempel en biograf.

Intressanta Fält

Fält Fälttyp Beskrivning Exempel
sitename text Namnet på Site-objektet Bergakungen
siteurl string URL associerad med Site-objektet www.sf.se
sitephone string Telefonnummer associerat med Site-objektet 08-562 600 00
sitephoneprefix string Landskod associerat med phone-fältet sv
siteid string Ett unikt id associerat med Site-objektet 3289
siteaddresses text Ett flervärdesfält innehållandes adress(er) associerade med Site-objektet, varje adress innehåller även information om vilken typ av adress det är Besöksadress : Skånegatan 16 B 402 22 Göteborg Sverige
sitepostcodes string Ett flervärdesfält innehållandes postkod(er) associerade med Site-objektet 402 22
sitedescription text Ett fält som innehåller en fritext-beskrivning av Site-objektet Biograf
Utöver dessa fält finns även fälten changeddate, createddate och parentsiteid.

InventoryDocument

Objekt med typen InventoryDokument representerar representer ett inventerat objekt på en Site, till exempel en av- och påstigningsplats.

Intressanta Fält

Fält Fälttyp Beskrivning Exempel
name text Namnet på InventoryDocument-objektet Av- och påstigningsplats
path string Den, från ett Site-objekt, nedgående väg genom den hierarkiska datastrukturen man behöver ta för att komma till InventoryDocument-objektet. Då denna väg är unik för objektet fungerar detta även som ett unikt id för InventoryDocument-objektet. Stegen genom datastrukturen är /-separerade. 3289/486732
canonicalpath string En annan version av path där stegen genom datastrukturen representeras av namn istället för id:n. Stegen genom datastrukturen är här |-separerade. Bergakungen|Av- och påstigningsplats
parent string Den path genom datastrukturen som leder till InventoryDocument-objektets förälder 3289
ancestors string Ett flervärdesfält där varje element motsvarar en path till en av InventoryDocument-objektets förfäder 3289
properties text Ett flervärdesfält där varje element motsvarar en egenskap hos InventoryDocument-objektet Längd : 9m;Kortaste avstånd till entré : 10m

Utöver dessa fält kopierar ett InventoryDocument-objekt även ner följande fält från det Site-objekt det tillhör: sitename, siteurl, sitephone, sitephoneprefix, siteid, sitepostcodes och sitedescription.

Gemensamma fält

Utöver de dokumenttypsspecifika fält som beskrivs ovan finns det även vissa fält som förkommer i både Site- och InventoryDocument-objekt.

Intressanta Fält

Fält Fälttyp Beskrivning Exempel
documenttype string Namnet på den dokumenttyp ett solr-dokument representerar Site
children string Ett flervärdesfält där elementen representerar objektets direkta barn i den hierarkiska datastrukturen. 3289/486732;3289/486733;3289/486734
position location Latitud- och longitud-koordinater associerade med objekt, detta fält är användbart för att utföra sökning filtrerad på geografisk position. 57.702172,11.985862

Fälttyper

Fält av olika typer har olika egenskaper i Solr. För att förstå vad man kan vänta sig för svar av en sökfråga mot ett fält måste man även förstå dess typ. Det som följer är en förklaring av de olika fälttyper som ovanstående fält använder.

Fälttyp Beskrivning Exempel
string För att få en träff i ett fält av denna typ krävs en exakt sträng-match siteid
text Fält av denna typ ger träff vid sökning på vilket ord som helst i fältet, samt alla dess böjningsformer properties
location Denna fälttyp är till för fält som ska användas vid geografisk filtrering av sökresultatet. Formatet för fälttypen är WGS 84. position
date Denna fälttyp är till för fält som ska användas vid tidsbaserad filtrering av sökresultatet createddate
 

Sök via REST API

REST API:t tillhandahåller ett tunnt lager ovanpå Solr som exponerar objekten lagrade i databasen som JSON, med stöd för JSONP. Dokumenten/objekten i REST API:t är precis dom samma som i Solr, fast utökade med navigatorer för att enklare kunna förflytta sig mellan barn och förälderdokument.

Utöver detta ger REST API:t även en enklare "friform" syntax för sökningar genom att i förväg ha valt ut ett antal fält som den söker i.

Exempel på frågor

Alla URL:er nedanför är relativa till http://data.vgregion.se/api/v1
Anrop Beskrivning
/sites/search?q=davidsgården&key=${key} Sök efter anläggningar där ordet "davidsgården" förekommer i något fält
/sites/search?q=sitepostcodes:418*&key=${key} Sök efter anläggningar där postkoden börjar med 418
/sites/search?q=children:*&key=${key} Sök efter anläggningar som har barn-dokument
/sites/search?q=children:*+AND+sitepostcodes:418*&key=${key} Sök efter anläggningar som har barn-dokument och vars postkod börjar med 418
/inventorydocuments/search?q=ancestors:136&key=${key} Sök efter inventariedokument som har objekt med id 136 som förfäder

Tillgängliga anrop

Följande tabell listar alla möjliga anrop som kan göras mot REST API:t. Alla förfrågningar som returnerar listor stödjer paginering med hjälp av query-parametrarna:
rows
Maximal antalet objekt som ska returneras (10)
offset
Vilket dokument i ordningen listan ska börja från (0)
Resurs Beskrivning
/sites Hämta listan av Site-objekt
/sites/search?q={query} Sök efter Site-objekt
/sites/{siteid} Hämta ett Site-objekt med ett visst id
/sites/{siteid}/inventorydocuments Hämta listan av InventoryDocument-objekt som är omedelbara barn till ett visst Site-objekt
/sites/{siteid}/inventorydocuments/search?q={query} Sök efter InventoryDocument-objekt som är ättlingar till ett visst Site-objekt
/sites/{siteid}/inventorydocuments/{invdocid} Hämta ett InventoryDocument-objekt med ett visst id
/inventorydocuments Hämta listan av InventoryDocument-objekt
/inventorydocuments/search?q={query} Sök efter InventoryDocument-objekt

Navigering i REST API:t

Dokumenten som ges tillbaka i REST API:t innehåller förutom de fält som finns i Solr, även fältet _apiurl som innehåller URL:er till dess barn, förälder samt förfäder. Dessa bör användas istället för att konstruera URL:er själv från dokumentens ID:n.

Exempel
$ curl 'http://data.vgregion.se/api/v1/sites/136/inventorydocuments/496505' | jsonpretty
{
  "id": "136/496505",
  "parent": "136",
  "children": [
    "136/496505/496524"
  ]
  "ancestors": [
    "136"
  ],
  ...
  "_apiurls": {
    "this": "http://data.vgregion.se/api/v1/sites/136/inventorydocuments/496505",
    "parent": "http://data.vgregion.se/api/v1/sites/136",
    "children": [
        "http://data.vgregion.se/api/v1/sites/136/inventorydocuments/496505/496524"
    ],
    "ancestors": [
      "http://data.vgregion.se/api/v1/sites/136"
    ]
  }
}

JSONP stöd

Alla ovanstående anrop stödjer JSONP genom att lägga på suffixet .jsonp?callback={callback}.
Exempel
$ curl 'http://data.vgregion.se/api/v1/sites.jsonp?callback=foobar'
foobar([{...}]);

Felhantering

Vid feltillstånd kommer tjänsten svara med ett JSON objekt med nycklarna "enduserMessage" samt "developerMessage". Den tidigare kan användas som meddelande direkt mot en eventuell slutanvändare, emedan "developerMessage" kan vara nyttig för kommunikation mellan utvecklare.

Hämta motsvarande sökfråga i Solr

För felsökning eller vidareutveckling av mer avancerade frågor mot Solr kan du få tillgång till Solr-frågan som API:t ställer genom att inspektera huvudet (Header:n) i HTTP svaret. Länken som en Link-Header med relationen rel="via".
Exempel
$ curl -i 'http://data.vgregion.se/api/v1/sites?rows=0'
HTTP/1.1 200 OK
Link: <http://data.vgregion.se/solr/main/select?fq=documenttype%3ASite&qf=sitename+siteaddresses&defType=edismax&q.alt=*%3A*&start=0&rows=0&wt=json>; rel="via"
...
                    

Söka via Solr

Solr har ett omfattande språk för sökfrågor, det som följer är tre exempelfrågor. För fullständig dokumentation om hur man söker mot plattformen se Solrs wikisida.

Beskrivning Sökfråga
Enkel sökning i fält http://data.vgregion.se/solr/main/select/?q=documenttype:Site
Negativ sökning http://data.vgregion.se/solr/main/select/?q=-children:*
Geografiskt filtrerad sökning http://data.vgregion.se/solr/main/select/?q=documenttype:Site&fq={!geofilt%20pt=61.36,16.36%20sfield=position%20d=5}