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):

  1. (Klient → Server) Inicializace rámce (GET s parametry)

  2. (Server → Klient) Potvrzení o dokončení incializace, případně předání informace o chybě (oprávnění apod.)

  3. (Klient → Server) Výchozích souřadnic pro zobrazení či editaci

  4. (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"
}