Fotograf: Oskar Scheller / Stockholm Business Region.

Ett öppet API för STHLM C verksamhetsinformation

STHLM C API, CAPI (City API by STHLM C), gör STHLM C strukturerade verksamhetsinformation tillgänglig för andra digitala tjänster.

Genom CAPI kan webbplatser, appar, kartor, digitala guider, AI-tjänster och andra system läsa och återanvända offentlig information om verksamheter i Stockholms innerstad, med utgångspunkt i de 64 historiska huvudgatorna inom innerstadens sju centrala stadsdelar: Norrmalm, Gamla stan, Djurgården, Östermalm, Södermalm, Kungsholmen och Vasastan.

CAPI är ett offentligt, maskinläsbart och read-only API. Det innebär att information kan läsas av externa tjänster, men att verksamhetsdata inte kan skapas, ändras eller raderas genom API.

Varför finns CAPI?

STHLM C samlar redan strukturerad information om verksamheter, bland annat namn, verksamhetstyp, adress, gatukoppling, kontaktuppgifter, öppettider, prisnivå, status, geografiska koordinater och bilder.

CAPI gör denna information tillgänglig genom ett gemensamt tekniskt gränssnitt.

På så sätt behöver varje extern tjänst inte bygga en egen kopia av verksamhetsregistret.

Samma centrala information kan i stället användas i flera olika digitala sammanhang.

En datakälla.
Ett verksamhetsregister.
Flera sätt att använda informationen.

STHLM C:s informationsmodell

STHLM C:s informationsmodell utgår från Stockholms innerstads 64 historiska huvudgator. Dessa utgör den geografiska och redaktionella strukturen som verksamheterna kopplas till.

De 64 historiska huvudgatorna

STHLM C:s verksamhetsinformation är geografiskt strukturerad kring 64 historiska huvudgator i Stockholms innerstad. Huvudgatorna är fördelade över innerstadens sju centrala stadsdelar: Norrmalm, Gamla stan, Djurgården, Östermalm, Södermalm, Kungsholmen och Vasastan. Varje verksamhet kopplas till den huvudgata där den hör hemma.

STHLM C:s huvudgator är numrerade i den ordning som används i informationsmodellen.

Norrmalm — 16 huvudgator

Biblioteksgatan
Drottninggatan
Gamla Brogatan
Hamngatan
Jakobsbergsgatan
Klarabergsgatan
Kungsgatan
Mäster Samuelsgatan
Norrlandsgatan
Olof Palmes gata
Regeringsgatan
Sergelgatan
Smålandsgatan
Sveavägen
Tegnérgatan
Vasagatan

Gamla stan — 7 huvudgator

Lilla Nygatan
Riksgatan
Stora Nygatan
Storkyrkobrinken
Tyska Brinken
Västerlånggatan
Österlånggatan

Djurgården — 3 huvudgator

Allmänna Gränd
Djurgårdsvägen
Rosendalvägen

Östermalm — 12 huvudgator

Birger Jarlsgatan
Grev Turegatan
Humlegårdsgatan
Karlavägen
Linnégatan
Nybrogatan
Riddargatan
Sibyllegatan
Strandvägen
Storgatan
Sturegatan
Valhallavägen

Södermalm — 11 huvudgator

Folkungagatan
Götgatan
Hornsgatan
Långholmsgatan
Nytorgsgatan
Renstiernas gata
Ringvägen
Rosenlundsgatan
Sankt Paulsgatan
Skånegatan
Swedenborgsgatan

Kungsholmen — 5 huvudgator

Fleminggatan
Hantverkargatan
Kungsholmsgatan
Sankt Eriksgatan
Scheelegatan

Vasastaden — 10 huvudgator

Birkagatan
Dalagatan
Karlbergsvägen
Norrtullsgatan
Odengatan
Roslagsgatan
Rådmansgatan
Rörstrandsgatan
Torsgatan
Upplandsgatan

Totalt: 64 historiska huvudgator.

CAPI är ett gränssnitt – inte ett nytt verksamhetsregister

CAPI skapar inte ett separat register över verksamheter.

Det publika API läser den verksamhetsinformation som redan finns i STHLM C informationsmodell. Endast publicerade verksamheter exponeras genom CAPI V1.

Det betyder att CAPI fungerar som ett maskinläsbart lager mellan STHLM C information och externa tjänster.

Den tekniska implementationen bakom API kan utvecklas över tid utan att externa användare behöver känna till hur STHLM C administrerar sin interna information.

Vad kan man hämta?

CAPI V1 kan bland annat returnera:

verksamhetens namn
verksamhetens unika ID
verksamhetens digitala identifierare
verksamhetstyp
stadsdel
gata och gatukoppling
adressinformation
telefon
offentlig e-postadress
webbplats
beskrivning
tagline
öppettider
prisnivå
verksamhetens status
geografiska koordinater
publik bildreferens.

Informationen är organiserad i en strukturerad JSON-modell med bland annat business, location, contact, content, opening_hours och geo.

CAPI V1 är read-only

CAPI V1 är byggt för att läsa offentlig information.

Det finns därför endast läsoperationer i V1:

GET

CAPI V1 erbjuder inte funktioner för att:

skapa verksamheter
ändra verksamheter
radera verksamheter.

Det innebär att en extern tjänst kan använda informationen utan att kunna förändra STHLM C verksamhetsdata.

API-endpoints

CAPI V1 använder följande versionsstruktur:

https://sthlmc.se/wp-json/sthlmc/v1

Lista verksamheter

GET https://sthlmc.se/wp-json/sthlmc/v1/businesses

Detta returnerar publicerade verksamheter som är tillgängliga via CAPI.

Ett förenklat exempel:

{
  "api_version": "v1",
  "count": 1,
  "businesses": [
    {
      "business_id": 3996,
      "business_name": "Röda Kvarn",
      "business_slug": "roda-kvarn"
    }
  ]
}

Hämta en specifik verksamhet

En enskild verksamhet kan hämtas genom dess business_id.

GET https://sthlmc.se/wp-json/sthlmc/v1/businesses/{id}

Exempel:

GET https://sthlmc.se/wp-json/sthlmc/v1/businesses/3996

Om verksamheten inte finns eller inte är tillgänglig returneras HTTP-status 404.

Business ID och gatukoppling

Varje verksamhet har ett tekniskt unikt business_id.

CAPI V1 använder verksamhetens befintliga identitet och skapar inte ett separat ID-system.

Verksamheter har också en läsbar business_slug.

En viktig del av STHLM C modell är street_slug, som kopplar verksamheten till den gata och den gatublogg som verksamheten tillhör.

Det gör det möjligt för andra system att förstå relationen:

Verksamhet → gata → gatublogg

Offentlig information

CAPI exponerar endast information som är avsedd för offentlig användning.

Exempelvis kan den offentliga kontaktinformationen innehålla:

phone
public_email
website

Privata eller interna uppgifter ingår inte i det publika API-kontraktet.

Detta är en grundläggande princip för CAPI V1.

Strukturerad information

CAPI V1 använder en semantiskt strukturerad datamodell.

STHLM C använder etablerade begrepp och strukturer där det är relevant, med Schema.org som en viktig semantisk referenspunkt.

CAPI V1 är samtidigt utformat så att modellen kan utvecklas mot en mer omfattande JSON-LD-baserad representation och framtida interoperabilitet med andra strukturerade datakällor.

CAPI V1 är inte NAPI. Det är STHLM C eget API.

Interoperabilitet med andra strukturerade datamodeller är däremot en långsiktig riktning för utvecklingen.

För utvecklare

CAPI kan användas av alla tjänster som kan göra HTTP-anrop och läsa JSON.

Det innebär att API exempelvis kan användas från:

JavaScript
PHP
Python
Java
Go
Swift
Kotlin
andra språk och plattformar med stöd för HTTP och JSON.

Ett enkelt anrop till list-endpointen är:

GET https://sthlmc.se/wp-json/sthlmc/v1/businesses

Resultatet kan därefter användas av den egna applikationen eller tjänsten.

Versionering och stabilitet

CAPI använder versionsnummer i API URL.

CAPI V1 använder:

/wp-json/sthlmc/v1/

V1 är avsett att vara ett stabilt tekniskt gränssnitt.

Förändringar som bryter mot befintliga klienters förväntningar ska därför inte införas tyst inom V1. Större strukturella förändringar ska i stället hanteras genom en ny API-version.

Det gör det möjligt för externa tjänster att bygga integrationer mot CAPI utan att behöva bevaka STHLM C interna tekniska implementation.

CAPI och STHLM C övriga information

CAPI är ett av flera informationslager inom STHLM C.

STHLM C strukturerade verksamhetsinformation kan användas genom CAPI, medan gatubloggarna fungerar som redaktionella och visuella miljöer.

CAPI ersätter inte det redaktionella innehållet och ersätter inte verksamheternas egna publicerade inlägg.

I stället tillhandahåller CAPI ett strukturerat gränssnitt för den information som lämpar sig för maskinell återanvändning.

Det gör det möjligt för framtida tjänster, exempelvis kartor, digitala guider och AI-baserade tjänster, att använda strukturerad verksamhetsinformation utan att behöva skapa egna kopior av den.

Teknisk dokumentation

Den här sidan är den publika introduktionen till STHLM C API.

För utvecklare som behöver den fullständiga tekniska specifikationen finns även CAPI V1 Contract, som beskriver API struktur, fält, identifierare, versionsregler, kompatibilitet och övriga tekniska principer.

CAPI V1 Contract →

API-status

API: City API by STHLM C (CAPI)
Version: V1
Format: JSON
Access: Public
Methods: GET
Authentication: Not required for public data
Status: Public API

En offentlig informationsmodell för återanvändning

CAPI är en del av STHLM C arbete med att göra information om Stockholms verksamheter mer tillgänglig, strukturerad och återanvändbar.

Genom ett gemensamt API kan samma centrala information användas i flera digitala sammanhang utan att varje tjänst behöver bygga ett eget verksamhetsregister.

STHLM C information kan publiceras en gång och användas på många sätt.

Om CAPI – STHLM C API