Uživatelská příručka

Klientské API

• Účelem klientského API je poskytnout vybraným externím subjektům (aplikacím, službám, ...) přístup k základním údajům o stromech, které jsou zaneseny v databázi portálu Stromy pod kontrolou.
• API používá protokol HTTPS.

Omezení

• API není veřejné ve smyslu, že by umožňovalo přístup komukoliv a k jakýmkoliv datům. Tvůrci externí aplikací a služeb, kteří mají o použití klientského API zájem, by měli kontaktovat správce portálu (webmaster@stromypodkontrolou.cz) a dohodnout se na zřízení přístupu. Tým portálu si vyhrazuje právo přistup neposkytnout. Zároveň API zpřístupňuje údaje jen o takových stromech, u kterých s tím majitel dat (Partner) souhlasil.
• Každý externí subjekt má k dispozici 10000 volání mesíčně. Pokud potřebujete větší množství, kontaktujte správce portálu. Při překročení limitu vrátí požadavky stavový kód 429. Rozestup mezi jednotlivými voláními by měl být alespoň 2 sekundy, jinak bude vrácen stavový kód 429.

Nastavení souhlasu k poskytování údajů o stromech

Následující postup popisuje, jakým způsobem může Partner povolit nebo zakázat poskytování údajů o svých stromech pro externí aplikace.

1. Přihlašte se na portál.
2. V levém sloupci rozklikněte sekci Partner a klikněte na odkaz Sdílení dat.
3. Na stránce Sdílení dat v sekci Sdílení s externími subjekty nastavte, jestli souhlasíte se sdílením základních údajů o stromech pomocí tlačítka Změnit.

Poskytované údaje o solitérních stromech

O stromech jsou poskytovány následující údaje:

• jméno plochy,
• číslo stromu v ploše,
• číslo štítku (RFID),
• průměr koruny (v metrech),
• latinské jméno druhu,
• české jméno druhu,
• souřadnice v souřadném systému WGS-84,
• příznak existence záznamu o bezpečnostní vazbě,
• příznak existence záznamu o detailním hodnocení (např. přístrojové testy, speciální zákroky, ...),
• příznak existence záznamu o pozorování doprovodného organismu,
• odkaz na portál Stromy pod kontrolou, který otevře kartu stromu v mapě.

Popis volání

Doména

Všechna volání by měla směřovat na doménu https://www.stromypodkontrolou.cz.

Autentizace

Správce portálu poskytne tvůrcům aplikace řetezec, který aplikace pošle v HTTP hlavičce User-Agent.

Získání informací o stromech v zadaném výřezu

Požadavek

GET /client_api/v1/trees?lat_min=<float>&lat_max=<float>&lon_min=<float>&lon_max=<float>

Hlavičky požadavku

User-Agent: <identifikační řetězec partnera>
Accept-Language: cs_CZ

Parametry požadavku

• lat_min - zeměpisná šířka levého spodního rohu výřezu
• lat_max - zeměpisná šířka pravého horního rohu výřezu
• lon_min - zeměpisná délka levého spodního rohu výřezu
• lon_max - zeměpisná délka pravého horního rohu výřezu

Tělo odpovědi

[
    {
        "id": "identifikátor stromu",
        "site": "jméno plochy",
        "number": číslo_stromu_v_ploše,
        "rfid": "číslo štítku",
        "species_scientific_name": "latinské jméno druhu",
        "species_common_name": "české jméno druhu",
        "coordinates": {"lat": zeměpisná_šířka, "lon": zeměpisná_délka},
        "has_cable_bracing": příznak_zaznamenané_bezpečnostní_vazby,
        "has_device_test": příznak_zaznamenaného_detailního_hodnocení,
        "has_associate": příznak_zaznamenaného_doprovodného_organismu,
        "spread": průměr_koruny_v_metrech,
        "url": "odkaz na portál Stromy pod kontrolou"
    },
    ...
]

Omezení

Diagonála dotazovaného výřezu by neměla překročit 1 km. Pokud bude větší, vrátí požadavek prázdné pole.

Získání informací o konkrétním stromu

Požadavek

GET /client_api/v1/tree?tree_id=<string>
GET /client_api/v1/tree/<tree_id:string>

Hlavičky požadavku

User-Agent: <identifikační řetězec partnera>
Accept-Language: cs_CZ

Parametry požadavku

• tree_id - ID stromu, jehož údaje se požadují

Tělo odpovědi

{
    "id": "identifikátor stromu",
    "site": "jméno plochy",
    "number": číslo_stromu_v_ploše,
    "rfid": "číslo štítku",
    "species_scientific_name": "latinské jméno druhu",
    "species_common_name": "české jméno druhu",
    "coordinates": {"lat": zeměpisná_šířka, "lon": zeměpisná_délka},
    "has_cable_bracing": příznak_zaznamenané_bezpečnostní_vazby,
    "has_device_test": příznak_zaznamenaného_detailního_hodnocení,
    "has_associate": příznak_zaznamenaného_doprovodného_organismu,
    "spread": průměr_koruny_v_metrech,
    "url": "odkaz na portál Stromy pod kontrolou"
}

Omezení

Vlastník dat (Partner) musí povolit poskytování údajů o stromu, jinak bude volání vracet kód 404.

Příklad použití

Následující skript v jazyce Python by měl být plně funkční (vyžaduje modul python-requests) po doplnění Vašeho autentizačního řetězce.

import time
import requests

params = {}
params["lat_max"] = 49.27769699366917
params["lat_min"] = 49.27646333001661
params["lon_max"] = 17.549203099269562
params["lon_min"] = 17.5457698717305

headers = {
    'User-Agent': 'přidělený identifikátor',
    'Accept-Language': 'cs_CZ'
}

r = requests.get("https://www.stromypodkontrolou.cz/client_api/v1/trees", params=params, headers=headers)
if r.status_code == 200:
    trees = r.json()
    print "Ve vyrezu je %d stromu." % len(trees)
else:
    trees = []

if trees:
    time.sleep(3)
    r = requests.get("https://www.stromypodkontrolou.cz/client_api/v1/tree/%s" % trees[0]["id"], headers=headers)
    if r.status_code == 200:
        tree = r.json()
        print "Jeden ze stromu:"
        print repr(tree)