search

🖥️Rajapintakuvaus

hashtag
Versio 2 (current)

Pörssärin rajapinta on HTTP GET osoitteeseen https://api.porssari.fi/getcontrols.php, neljällä pakollisella parametrillä:

  • device_mac: laitteen MAC-osoite isoilla kirjaimilla ja ilman muita merkkejä, esim A1B2C3D4E5F6

  • last_request: edellisen JSON-ohjaustiedon aikaleima (UNIX-timestamp -muodossa, 0 mikäli ohjaustietoa ei ole tallennettu laitteeseen)

  • client: käyttäjön skriptin nimi ja versio

  • json_version=2 : käytä API versio 2:ta

Eli esimerkiksi: https://api.porssari.fi/getcontrols.php?device_mac=A1B2C3D4E5F6&last_request=1702815000&client=documentation-example-1&json_version=2

  • Mikäli last_request -parametri on alle tunti nykyhetkestä taaksepäin, palvelin vastaa http-koodilla 304

  • Mikäli device_mac -parametrin mukaista laitetta ei löydy tietokannasta, palvelin vastaa http-koodilla 400

  • Mikäli samalla device_mac -parametrilla kysytään alle 10 sekunnin kuluessa edellisestä kyselystä, palvelin vastaa http-koodilla 425

  • Mikäli samalla device_mac -parametrilla kysytään yli 60 kertaa tunnin kuluessa, palvelin vastaa http-koodilla 429

Muussa tapauksessa palvelin vastaa JSON-objektilla:

{
"metadata": {
    "mac": "A1B2C3D4E5F6",
    "channels": "1",
    "fetch_url": "https://api.porssari.fi/getcontrols.php",
    "timestamp": "1702821684",
    "timestamp_offset": "7200",
    "valid_until": "1702940100"
  },
  "controls": [
    {
      "id": "1",
      "name": "examplename",
      "updated": "1702708849",
      "state": "0",
      "schedules": [
        { "timestamp": "1702850368", "state": "1" },
        { "timestamp": "1702853976", "state": "0" },
        { "timestamp": "1702857522", "state": "1" },
        { "timestamp": "1702875674", "state": "0" },
        { "timestamp": "1702936868", "state": "1" }
      ]
    }
  ]
}

hashtag

hashtag
Versio 1 (legacy)

Legacy-rajapinta vastaa ohjaustilan tuntitasolla. Mikäli käytössä on ohjaustila mikä annetaan 15min resoluutiolla (esimerkiksi lämmitysohjaus), rajapinta palauttaa tunnin arvoksi kyseisen tunnint ensimmäisen 15 minuutin ajanjakson ohjaustilan.

Lähtökohtaisesti Pörssärin rajapinta on HTTP GET osoitteeseen https://api.porssari.fi/getcontrols.php, kolmella pakollisella parametrillä:

  • device_mac: laitteen MAC-osoite isoilla kirjaimilla ja ilman muita merkkejä, esim A1B2C3D4E5F6

  • last_request: edellisen JSON-ohjaustiedon aikaleima (UNIX-timestamp -muodossa, 0 mikäli ohjaustietoa ei ole tallennettuna laitteeseen)

  • client: käyttäjön skriptin nimi ja versio

Eli esimerkiksi: https://api.porssari.fi/getcontrols.php?device_mac=A1B2C3D4E5F6&last_request=1702815000&client=documentation-example-1

  • Mikäli last_request -parametri on alle tunti nykyhetkestä taaksepäin, palvelin vastaa http-koodilla 304

  • Mikäli device_mac -parametrin mukaista laitetta ei löydy tietokannasta, palvelin vastaa http-koodilla 400

  • Mikäli samalla device_mac -parametrilla kysytään alle 10 sekunnin kuluessa edellisestä kyselystä, palvelin vastaa http-koodilla 425

  • Mikäli samalla device_mac -parametrilla kysytään yli 60 kertaa tunnin kuluessa, palvelin vastaa http-koodilla 429

Palvelin vastaa tavallisesti JSON objektilla:

Tässä esimerkissä kanavien lukumäärä on yksi.

Kellonajat ovan suomen aikaa paitsi Timestamp joka UTC ja johon voi lisätä Timestamp_offset että on suomen ajassa.

Last updated