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.

• Kaupunkipyöräasemat
• Pyöräilijä ja kävelijä määrät
• Kunnossapitotiedot
• Häiriötiedotteet
• Kaupunkisääasemat

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ä.

Kaupunkipyöräasemat

Oulun kaupunkipyöräasemat.

Esimerkkikysely:

query GetAllBikeRentalStations {
  bikeRentalStations {
    id
    stationId
    name
    bikesAvailable
    spacesAvailable
    state
    allowDropoff
    lat
    lon
  }
}

Pyöräilijä ja kävelijä määrät

Oulun seudun pyöräilijä ja kävelijä laskurit.

Esimerkkikysely:

query GetAllEcoCounterSites {
  ecoCounterSites {
    id
    siteId
    name
    domain
    userType
    timezone
    interval
    sens
    channels {
      id
      siteId
      name
      domain
      userType
      timezone
      interval
      sens
      lat
      lon
    }
  }
}

Yksittäisen laskurin tiedot.

id = laskurin tunniste (yksittäisen kanavan ”siteId” arvo)
domain = laskurin ryhmä
step = ryhmitys (_15m|hour|day|week|month|year)
begin = aloituspäivämäärä
end = loppumispäivämäärä

Esimerkkikysely:

query GetEcoCounterSiteData {
  ecoCounterSiteData(
    id: "100000647",
    domain: Oulu_kaupunki,
    step: month,
    begin: "2019-01-01T00:00:00"
  ) {
    date
    counts
  }
}

Kunnossapitotiedot

Oulunliikenne.fi-palvelu tarjoaa reaaliaikaiset kunnossapitotiedot kevyeenliikenteen vä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:

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

Toteutuneet kunnossapitotyöt:

query GetMaintenanceVehicleRouteEvents {
     maintenanceVehicleRouteEvents(routeType:NON_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:1255) {
     vehicleNumber
     vehicleType
     timestamp
     contractId
     direction
     jobIds
     lat
     lon
   }
 }

Häiriötiedotteet

Oulun kaupungin häiriötiedotteet:

query GetAllTrafficAnnouncements { 
   trafficAnnouncements {
     id
     announcementId
     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 ”PEDESTRIAN” tai ”BICYCLE” niin tiedote liittyy kävelyyn ja pyöräilyyn.

Kaupunkisääasemat

Oulun kaupungin sääasemat. Kevytliikenneväylillä olevien sääasemien tiedoista on saatavilla erilaisia kelitietoja, kuten esimerkiksi ilman ja tien lämpötilat sekä sadetilanne. Sääasemista löytyy myös kelikamerat mistä voi tarkastella kevytliikenneväylien tilannetta.

Tiedot päivittyvät 5 minuutin välein.

Mittausarvojen selitteet:

nimi	yksikkö	selite
AIR_TEMPERATURE	°C	Ilman lämpötila
AIR_RELATIVE_HUMIDITY	RH%	Ilman suhteellinen kosteus
DEW_POINT_TEMPERATURE	°C	Kastepistelämpötila
WIND_SPEED	m/s	Tuulen nopeus 10min keskiarvo
WIND_DIRECTION	Degrees	Tuulen suunta 10min keskiarvo
RAINFALL_DEPTH	mm	Laskennallinen sadesumma
RAINFALL_INTENSITY	mm/h	Laskennallinen sateen intensiteetti
SNOW_DEPTH_A	mm	Lumen kerrospaksuus mittaus A
SNOW_DEPTH_B	mm	Lumen kerrospaksuus mittaus B
SNOW_DEPTH_C	mm	Lumen kerrospaksuus mittaus C
SNOW_DEPTH	mm	Lumen kerrospaksuus keskiarvo
RAIN_CLASSIFICATION		Sateen luokittelu
ROAD_SURFACE_TEMPERATURE	°C	Tienpinnan lämpötila

Esimerkkikysely:

query GetAllCityWeatherStations { 
  cityWeatherStations {
    weatherStationId
    name
    lat
    lon
    sensorValues {
      name
      sensorId
      sensorValue
      sensorUnit
      measuredTime
    }
    cameras {
      cameraId
      imageUrl
    }
  }
}