Oulunliikenteen GraphQL-rajapinnat

Yleiskuvaus julkisista GraphQL-rajapinnoista

Oulunliikenteen julkiset GraphQL-rajapinnat tarjoavat dataa Oulun seudun liikennetilanteesta ja palauttavat JSON-muotoista dataa vastauksena.

GraphQL on hakupohjainen rajapintakieli sekä rajapinnan ajoympäristö, joka pystyy suorittamaan hakuja ja palauttamaan haluttuja tietomalleja. GraphQL on Facebookin aloittama avoimen lähdekoodin projekti.

Rajapintojen sisältöä päivitetään noin kerran minuutissa.

Kaikki aikaleimat ovat UTC ajassa ja ilmoitetaan ISO 8601 standardin mukaisessa formaatissa.

Kaikki koordinaattitiedot ilmoitetaan GeoJSON standardin mukaisessa formaatissa.

Käytössä olevat GraphQL-rajapinnat

Alla on kuvattu kaikki Oulun liikennedatan julkiset GraphQL-rajapinnat.

• Kamerakuvat
• LAM-pisteet
• Pysäköintitalot
• Tiesääasemat
• Tietyöt
• Kunnossapitotiedot
• Häiriötiedotteet
• Liikenteen sujuvuustiedot

Avoimet rajapinnat

Osoite:

https://api.oulunliikenne.fi/proxy/graphql

Käyttö:

GraphQL on suunniteltu käytettävän siihen tarkoitetuilla ohjelmistokehityspaketeilla jotka sisältävät toimintoja kuten kutsujen validointia sekä kutsujen niputtamista. Hakuja voi myös tehdä suoraan HTTP POST kutsuilla, milloin itse haku liitetään kutsun body kenttään.

Yleisesti käytetyt GraphQL-ohjelmistokehityspaketit:

• Apollo
• Relay

Rajapinta tukee myös selaimessa aukeavaa graafista käyttöliittymää, joka on tarkoitettu testikäyttöön hakujen sekä vastauksien tarkasteluun. Käyttöliittymässä pystyy näkemään kaikki tietomallit sekä haut mitä rajapinta mahdollistaa. Alla olevat esimerkkihaut ovat myös suoraan kopioitavissa käyttöliittymään. Avataaksesi käyttöliittymää selaimessasi, klikkaa ylhäällä listattua rajapintaosoitetta.

Kenttäkohtaiset selitteet alla olevista esimerkkikyselyistä löytyvät rajapinnan käyttöliittymästä.

Kamerakuvat

Rajapinnasta on ladattavissa Oulun kaupungin liikennekameroiden sekä Liikenneviraston Oulun alueen kuvat. Oulun kaupungin 12 liikennekameraa näyttävät tuoreita kuvia liikenteestä niin monesta eri suunnasta kuin liikennetolpissa on kameroita.

Yksittäinen kuva päivittyy 5-15 minuutin välein.

Esimerkkikysely:

query GetAllCameras { 
  cameras {
    cameraId
    name
    lat
    lon
    presets {
      presetId
      presentationName
      imageUrl
      measuredTime
    }
  }
}

LAM-pisteiden mittaustiedot

Oulun seudun liikenteen automaattiset mittauspisteet (LAM-pisteet). LAM-pisteet ovat tienpintaan sijoitettuja mittauspisteitä, jotka keräävät seurantatietoja liikenteestä. Oulun alueella pisteitä on 29 kappaletta, ja niistä saadaan tiedot liikenteen keskinopeuksista sekä liikennemääristä. Liikenteen automaattisten mittausasemien tiedot kerää Traffic Management Finland. 

Esimerkkikysely:

query GetAllTmsStations { 
  tmsStations {
    tmsStationId
    name
    lat
    lon
    collectionStatus
    measuredTime
    sensorValues {
      roadStationId
      name
      sensorValue
      sensorUnit
    }
  }
}

Pysäköintitalojen tilatiedot

Oulun alueen pysäköintitalot ja ajantasaiset tilatiedot. Oulun kaupungin 16 pysäköintitalosta on saatavilla tiedot pysäköintipaikkojen määristä sekä vapaina olevista paikoista. Tämän lisäksi osasta pysäköintitaloista löytyy tiedot pysäköintihinnoista.

Tilatietoja päivitetään 5-20 minuutin välein pysäköintitalosta riippuen.

Esimerkkikysely:

query GetAllCarParks {
  carParks {
    carParkId
    name
    lat
    lon
    maxCapacity
    spacesAvailable
  }
}

Tiesääasemat

Oulun seudun tiesääasemat. Pääliikenneväylillä olevien tiesääasemien tiedoista on saatavilla erilaisia kelitietoja, kuten esimerkiksi ilman ja tien lämpötilat sekä sadetilanne. Tiesääasemien tiedot kerää Traffic Management Finland.

Anturitietojen (sensorValues) tietueet:

• roadStationId = tiesääaseman id
• name = mitattavan suureen nimi
• sensorValue = mittausarvo
• sensorUnit = mittayksikkö

Kuvaus mitattavista anturitiedoista Traffic Management Finlandin Digitraffic-rajapinnan dokumentaatiossa: https://tie.digitraffic.fi/api/v3/metadata/weather-sensors

Esimerkkikysely:

query GetAllWeatherStations { 
  weatherStations {
    weatherStationId
    name
    lat
    lon
    collectionStatus
    measuredTime
    sensorValues {
      roadStationId
      name
      sensorValue
      sensorUnit
    }
  }
}

Tietyöt

Oulun seudun tietyöt.

Esimerkkikysely:

query GetAllRoadworks { 
  roadworks {
    id
    roadworkId
    severity
    status
    startTime
    endTime
    description {
      fi
    }
    geojson
  } 
}

Kunnossapitotiedot

Oulunliikenne.fi-palvelu tarjoaa reaaliaikaiset kunnossapitotiedot autoväylille seuraaville työtehtäville:

• Auraus
• Liukkauden torjunta
• Tasaus
• Harjaus
• Muu

Palvelun rajapinnasta voi hakea kaikki suoritetut työtehtävät halutulle ajanjaksolle joka voi olla maksimissaan 7 vuorokauden pituinen. Suoritetut työtehtävät haetaan väylätyypin perusteella:

• MOTORISED (autoväylät)
• NON_MOTORISED (kevyenliikenteen väylät)

Toteutuneet kunnossapitotyöt:

query GetMaintenanceVehicleRouteEvents {
     maintenanceVehicleRouteEvents(routeType:MOTORISED) {
       id
       routeEventId
       routeType
       measuredTime
       contractId
       jobIds
       geometryId
       geojson
     }
 }

Rajapinta tarjoaa myös mahdollisuuden hakea kunnossapitoajoneuvojen sijaintitietoja halutulle ajanjaksolle joka voi myös olla maksimissaan 7 vuorokauden pituinen. Sijaintitiedot haetaan työsopimus ID-arvon perusteella:

• 1250 (ELYn verkko)
• 1255 (Oulun pääpyörätieverkko)

Kunnossapitoajoneuvojen sijaintitiedot:

query GetMaintenanceVehicleObservations {
   maintenanceVehicleObservations(contractId:1250) {
     vehicleNumber
     vehicleType
     timestamp
     contractId
     direction
     jobIds
     lat
     lon
   }
 }

Häiriötiedotteet

Oulun kaupungin häiriötiedotteet:

query GetAllTrafficAnnouncements { 
   trafficAnnouncements {
     id
     announcementId
     version
     publishedVersion
     title {
       fi
       sv
       en
     }
     description {
       fi
       sv
       en
     }
     severity
     status
     startTime
     endTime
     geojson
     modesOfTransport
     class {
       class
       subclass
     }
     trafficDirectionFreeText {
       fi
       sv
       en
     }
     temporarySpeedLimit
     duration
     additionalInfo
     detour
     oversizeLoad
     vehicleSizeLimit
     url
     imageUrls
   }
}

Jos kentässä ”modesOfTransport” löytyy arvo ”CAR” niin tiedote liittyy autoliikenteeseen.

Liikenteen sujuvuustiedot

Oulunliikenne.fi-palvelu tarjoaa reaaliaikaista liikenteen sujuvuusanalyysiä, ts. Liikenneruuhkia koskevia tietoja Oulun alueen tärkeimmälle tie- ja katuverkolle. Tiedot ovat saatavana oulunliikenne.fi -sivulta värillisinä geometrisina viivoina, jotka on piirretty tieverkkoa seuraavan kartan päälle. Eri värit esittävät liikenteen sujuvuuden tilaa juuri nyt.

Analyysi perustuu sekä liikenteenhallinnan ylläpitämän valtakunnallisen liikenteenvalvontajärjestelmän (TMS) että Oulun kaupungin ja Pohjois-Pohjanmaan ELY-keskuksen ylläpitämään alueelliseen liikenteen suorituskyvyn seurantajärjestelmään (TPM).

Liikenteen sujuvuusanalyysi tehdään keskiarvojen perusteella, jotka on kerätty 5 minuutin välein molemmista tietolähteistä. Analyysin tulos on GeoJSON-tietorakenne, joka sisältää kaikki tieverkkogeometriat.

TMS-pohjainen liikenteen sujuvuuslaskelma perustuu keskimääräiseen nopeuteen, jota TMS-asema mittaa tien osaan, ja nopeusrajoitukseen. Liikenteen sujuvuudessa on 4 tilaa:

• Vihreä – normaalit olosuhteet – keskimääräinen nopeus on vähemmän tai yhtä suuri kuin 9 km / h nopeusrajoituksen alapuolella
• Keltainen – kevyt liikenneruuhka – keskimääräinen nopeus on vähintään 10 km / h ja enintään tai yhtä suuri kuin 24 km / h nopeuden rajan alapuolella
• Punainen – raskas liikenneruuhka – keskimääräinen nopeus on vähintään 25 km / h nopeusrajoituksen alapuolella
• Harmaa – tuntematon olosuhde – keskimääräistä nopeutta ei voitu määrittää

TPM-pohjainen liikenteen sujuvuuden laskenta perustuu kahteen suorituskykyindikaattorin (KPI) arvoon, ohjausviiveen ja maksimimäärän odotusjaksoon, mitattu liikennevalolaitteilla. Liikenteen sujuvuudessa on 4 tilaa, jotka määrittelee heikompi kahdesta tässä määritellystä KPI-arvosta:

• Vihreä – normaalit olosuhteet – ohjausviive on alle 60 sekuntia tai enimmäis odotusjaksot ovat nollat
• Keltainen – kevyt liikenneruuhka – ohjausviive on vähintään 60 sekuntia ja pienempi tai yhtä suuri kuin 120 sekuntia tai enimmäisodotussyklit ovat 1
• Punainen – raskas liikenneruuhka – ohjausviive on yli 120 sekuntia tai enimmäisodotussykli suurempi kuin 1
• Harmaa – tuntematon olosuhde – KPI: tä ei voitu määrittää

Esimerkkikysely:

query GetTrafficFluencyFeatureCollection {
   trafficFluencyFeatureCollection {
     type
     features {
       type
       geometry
       properties {
         id
         type
         measuredTime
         trafficFlow
         name
         trafficDirection
         trafficDirectionName
         speedLimit
         averageSpeed
         detName
         giveWayDelay
         maxWaitCycles
       }
     }
   }
 }

Yksittäinen sujuvuustietue.

Esimerkkikysely:

query GetTrafficFluencyFeature {
   trafficFluencyFeature(id:"24244") {
     type
     geometry
     properties {
       id
       type
       measuredTime
       trafficFlow
       name
       trafficDirection
       trafficDirectionName
       speedLimit
       averageSpeed
       detName
       giveWayDelay
       maxWaitCycles
     }
   }
 }