GeoEdit API
API umožňuje zobrazení mapy v samostatném rámci a to včetně vrstvy souřadnic. Souřadnice jsou přenášeny primárně ve formátu WKT, případně WKB. API je navrženo tak, aby byla možná jen frontendová integrace bez vzniku samostatného serveru.
Služba se inicializuje otevření rámce (IFRAME) a předáním parametrů (požadavek typu GET). Dále se zasílají zprávy mezi rodičovským oknem a vnořeným rámcem, které umožňují řídit zobrazení a případnou editaci souřadnic.
API umožňuje implementovat aplikace určené pro zobrazení souřadnic, pro editaci souřadnic, či aplikace umožňující oba režimy. Tyto aplikace se nazívají GeoEdit Server.
Typická interakce pomocí API mezi externí aplikací (klient) a implementací GeoEdit API (server):
(Klient → Server) Inicializace rámce (GET s parametry)
(Server → Klient) Potvrzení o dokončení incializace, případně předání informace o chybě (oprávnění apod.)
(Klient → Server) Výchozích souřadnic pro zobrazení či editaci
(Server → Klient) V případě editoru: zaslání upravených souřadnic po dokončení editace
Technika výměny souřadnic: WKT (základní implementace) a WKB(Base64, pokročilá implementace)
Inicializace rámce
Klient otevře URL GeoEdit serveru v elementu IFRAME. Jako parametry URL se předává:
(volitelně) API key, slouží pro přístup vyžadující licenci, parametr:
API_KEY=...
(povinně) zdrojové URL odkud je server volán, je nutné pro řešení CORS, parametr:
SOURCE_ORIGIN=...
(volitelně) volitelný výčet možných typů souřadnice, pokud se neuvede je možné vše, možné hodnoty: SINGLE_POINT - limit na jeden bod, do budoucna lze dle potřeby přidat další, parametr:
ALLOWED_GEOMETRY_TYPES=SINGLE_POINT
požadovaný režim (zobrazení či editace), parametr:
mode
, možné hodnoty:
VIEW
- zobrazení souřadnic bez možnosti změny
EDIT
- editace souřadnic
Společné vlastnosti zpráv
Zprávy jsou zasílány jako JSON objekty. Každá zpráva je určena svým typem v atributu type
.
Zpráva může být rozšířena o volitelný atribut messageId
umožňující její
identifikace na straně příjemce a zapsání do logu. Hodnota by měla být typu string.
Dokončení inicializace
Směr: Server → Klient
Zaslání zprávy z mapové aplikace (server) do rodičovského rámce (klient) o dokončení inicializace.
Typ zprávy:
type: MapViewInit
Pole podporovaných formátů souřadnic, povinný parametr, uvádí se alespoň jeden:
supportedGeometryFormat: ["WKT", "WKB"]
Příklad:
{
"type":"MapViewInit",
"supportedGeometryFormat":["WKT"]
}
Odeslání souřadnic do editoru
Směr: Klienta → Server
Odeslání souřadnic z klientské aplikace do GeoEdit aplikace pro zobrazení či editaci. Zprávu klient může zaslat až po obdržení zprávy o dokončení inicializace.
Parametry zprávy jsou:
Typ zprávy:
type: MapGeometry
Volitelná identifikace požadavku, vrací se zpět po dokončení editace:
requestId: string
Formát předaných souřadnic:
geometryFormat: "WKT" | "WKB"
Předané souřadnice:
geometry: ....
Volitelný parametr pro určení počáteční oblasti zobrazení, region není zobrazen, ale je použit pro výpočet středu a zvětšení počátečního zobrazení mapy. Počátečním regionem je i jeden bod. Parametr:
initialRegion: ...
Příklad:
{
"type":"MapGeometry",
"requestId":"itemId=423456",
"geometryFormat":"WKT",
"geometry":"POINT(40.1213313 59.32323232)"
}
Zaslání upravených souřadnic do klienta
Směr: Server → Klient
V případě editoru je zaslána zpět zpráva s výslednými souřadnicemi po dokončení editace.
Parametry zprávy jsou:
Typ zprávy:
type: MapGeometry
Volitelná identifikace požadavku, vrací se zpět pokud byla předána se souřadnicemi:
requestId: string
Formát předaných souřadnic:
geometryFormat: "WKT" | "WKB"
Výsledné souřadnice:
geometry: ....
Příklad:
{
"type":"MapGeometry",
"requestId":"itemId=423456",
"geometryFormat":"WKT",
"geometry":"POINT(40.1213313 59.32323232)"
}
Zaslání zprávy o chybě
Směr: Server → Klient
Zpráva umožňuje předat informaci o chybě ze strany serveru do klienta. Scénáře pro použití: chybně předaná data z klienta/aplikace do editoru, případně chybný API klíč a další.
Parametry zprávy jsou:
Typ zprávy:
type: MapError
Chybová zpráva:
message: string
Volitelné upřesnění chyby:
description: string
Příklad:
{
"type":"MapError",
"message":"Chyba",
"description":"Popis chyby"
}