gistda-sphere-react

API coverage

Every part of the GISTDA Sphere JavaScript API and web services, and where to find it in this library

This page maps the Sphere API reference and the web services to this library. Anything not wrapped is still reachable through useMap(), which gives you the raw sphere.Map.

Map

SphereLibrary
new sphere.Map(options)<SphereMap>
MapOptions.layer, zoom, zoomRange, location, ui, input, lastView, languagebaseLayer, zoom, zoomRange, center, ui, input, lastView, language props
MapLibre map optionsoptions prop
map.zoom()zoom prop, setZoom, getZoom, zoomIn, zoomOut, onZoom
map.zoomRange()zoomRange prop, setZoomRange, getZoomRange, onZoomRange
map.location()center prop, setCenter, getCenter, onLocation
map.bound()setBound, getBound
map.move()panBy
map.goTo()goTo (with rotate or bearing)
map.rotate(), map.pitch()rotate/pitch props, setRotate/getRotate, setPitch/getPitch, onRotate/onPitch
map.language()language prop (or SphereProvider's), setLanguage, getLanguage
map.enableFilter(), sphere.Filterfilter prop, setFilter, getFilter
map.resize(), map.repaint()resize, repaint
map.id(), map.placeholder()useMap().map
map.Renderer (MapLibre)useMap().map.Renderer, ref.getMap().Renderer

The methods in the right column are on useMapControls and the SphereMap ref.

Events

SphereLibrary
map.Event.bind(), unbind()on… props on SphereMap, useMapEvent
All 37 sphere.EventName eventsOne prop each, from onReady to onZoomRange. See the events table.
ReadyonReady, useMapReady
Click, OverlayClickonClick, onOverlayClick, useMapClick, useOverlayClick, and onClick on every overlay
BeforeContextmenu (return false to cancel)onBeforeContextMenu, useMapEvent("beforeContextmenu")

Layers

SphereLibrary
new sphere.Layer(name, options), LayerOptions<Layer> props
sphere.LayerType (Vector, XYZ, WMS, WMTS, WMTS_REST, TMS, Tiles3D, I3S)type prop
sphere.Layers (built-in layers)<Layer preset>, baseLayer prop
map.Layers.setBase()baseLayer prop, setBaseLayer
map.Layers.add(), insert(), remove(), clear()<Layer> (with beforeId), addLayer, removeLayer, clearLayers
map.Layers.list(), size()getLayers()
map.Layers.language()language prop
Vector styles, custom MapLibre layers<Layer style>, <Layer layer>
3D tile options (loadOptions, onTilesetLoad, point size)loadOptions, onTilesetLoad, pointSize props

Overlays

SphereLibrary
sphere.Marker, MarkerOptions<Marker>
sphere.Popup, PopupOptions<Popup>
sphere.Polyline, Polygon, Circle, Dot, Rectangle, GeometryOptions<Polyline>, <Polygon>, <Circle>, <Dot>, <Rectangle>
sphere.LineStylelineStyle="Solid" | "Dashed" | "Dot"
GeoJSON inputpositions/position accept GeoJSON, and <GeoJson> shows whole documents
overlay.location()position props, setPosition, getPosition
overlay.visibleRange()visibleRange prop
overlay.shift()ref shift
overlay.distance(), intersects(), contains(), within()ref distanceTo, intersects, contains, within
overlay.toJSON()ref toGeoJSON
overlay.active()ref.getMarker().active() and other get…() objects
marker.popup(), pop() / geometry popup(), pop()ref togglePopup, popupContent prop
marker.element(), popup.element()ref getElement
marker.update()draggable and rotate props, ref setRotation
popup.title(), detail()title/detail props, ref setTitle/setDetail
geometry.update()live style props, ref updateStyle
geometry.pivot(), centroid(), bound(), rotate()ref getPivot, getCentroid, getBound, rotate
polyline.size(), polygon.size(), circle.size(), circle.radius()ref getLength, getArea, getRadius
union(), intersection(), difference(), split()ref methods of the same name
map.Overlays.add(), remove()mounting and unmounting components
map.Overlays.load(), unload()<PredefinedOverlay>, <ObjectOverlay>, loadPredefinedOverlay
map.Overlays.clear(), list(), size(), lastOpenPopup()useMap().map.Overlays
sphere.Overlays.cameras, events, aqi<PredefinedOverlay>
sphere.Overlays.Object, ObjectOptions, sphere.ObjectLabel<ObjectOverlay> (label for ObjectLabel.Title)

Routing

SphereLibrary (useRoute)
add(), insert(), remove(), removeAt(), list(), size()addDestination, insertDestination, removeDestination, removeDestinationAt, listDestinations, size, and destinations as state
clearDestination(), clearPath(), clear(), reverse(), search()clearDestinations, clearPath, clear, reverse, search
distance(), interval()summary, getDistance, getInterval
guide()steps, routes, getSteps, getGuide
exportRouteLine()exportRouteLine
mode(), modeOf(), sphere.RouteModesetMode/getMode, setModeAt/getModeAt
enableRoute(), sphere.RouteTypeenableRouteType, isRouteTypeEnabled
enableRestrict(), sphere.RouteRestrictsetRestrict, isRestrictEnabled
label(), sphere.RouteLabelsetLabel, getLabel
line(), sphere.RouteLinesetLineStyle, getLineStyle
auto()auto option, setAuto, getAuto
enableContextMenu()enableContextMenu
placeholder()<RouteGuide>, setPlaceholder
language()setLanguage, getLanguage
RouteComplete, RouteError eventsstatus, error, onRouteComplete, onRouteError, onError

Search and tags

SphereLibrary
map.Search.search(), suggest(), address(), nearPoi()useSearch methods of the same name, and useSuggest for debounced suggestions
map.Search.placeholder(), SearchUiOptions<SearchResults>, setPlaceholder
map.Search.clear(), enablePopup(), language()clear, enablePopup/isPopupEnabled, setLanguage/getLanguage
map.Tags.add(), set(), remove(), clear(), list(), size()<Tag>, useTags
map.Tags.enablePopup(), language()useTags
sphere.TagType, TagOptions<Tag> props
Tag listuseTagCategories

UI

SphereLibrary
sphere.UiComponentui prop
map.Ui.DPad, Geolocation, Zoombar, Toolbar, LayerSelector, Fullscreen, Crosshair, Scale, ContextMenu (visible())controls prop, useUi setControlVisible/isControlVisible
map.Ui.Geolocation (locate, remove marker)locateUser, clearUserLocation
map.Ui.ContextMenu.enableAddress(), enableNearPoi()setContextMenuOptions, getContextMenuOptions
map.Ui.Keyboard.enable()setKeyboardEnabled, isKeyboardEnabled
map.Ui.Mouse.enable(), enableClick(), enableDrag(), enableWheel()setMouseEnabled, getMouseState
map.Ui.add(), remove()addControl, removeControl, <MapControl>
map.Ui.lockMap()lockMap (with lock, unlock, remove)
map.Ui.language()setLanguage
sphere.CustomControl<MapControl>
sphere.MenuBar, selectIndex(), MenuBarOptions, MenuItem<MenuBar>

Utilities

SphereLibrary (useSphereUtils)
formatDistance, formatArea, formatThaiArea, formatInterval, formatDate, formatTime, formatDateTimeRangeFunctions of the same name
WKTToGeoJSON, KMLToGeoJSON, GPXToGeoJSON, GMLToGeoJSON, EsriJSONToGeoJSON, TopoJSONToGeoJSONwktToGeoJSON, kmlToGeoJSON, gpxToGeoJSON, gmlToGeoJSON, esriJsonToGeoJSON, topoJsonToGeoJSON (they load the library for you)
initLibraryCalled automatically by the converters and project
projectproject
latitudeLength, longitudeLengthFunctions of the same name
formatPoi, poiPopupOptionsSphereProvider props
append, prepend, empty, loadStyle, loadScript, getJson, isHD, validateLocation, sameLocation, isAbsInRange, bounduseSphereUtils().util
sphere.Math (distance, closestPointOnLine, lineIntersectPoint)useSphereUtils().math

Web services

ServiceLibrary (web services client)
search/search, search/suggestsearch.search, search.suggest
poi/search, poi/get, poi/clusterpoi.nearby, poi.get, poi.cluster
category/alltags.categories
route/route, route/matrixroute.route, route.matrix
geo/address, geo/elevationgeo.address, geo.elevation
snippet/static, snippet/embedmaps.staticMapUrl, maps.embedUrl
Raster, vector and WMTS tilesmaps.rasterTileUrl, maps.vectorTileUrl, maps.vectorStyleUrl, maps.wmtsCapabilitiesUrl
info/crop, info/land-suitability, info/crop-suitabilityinfo.crop, info.landSuitability, info.cropSuitability
info/disaster-flood, info/disaster-drought, info/disaster-hotspotinfo.flood, info.drought, info.hotspot
info/disaster-recurring (and /v2)info.disasterRecurring
info/disasters/flood-recurrence, drought-recurrenceinfo.floodRecurrence, info.droughtRecurrence
agri/rice, maize, cassava, sugarcane (bi-weekly), palm, rubber (yearly)agri.rice, agri.maize, agri.cassava, agri.sugarcane, agri.palm, agri.rubber
population/facebookpopulation.get
GET and POST forms of every serviceGET, switching to POST automatically for long requests (method option)

Beyond the Sphere API

The library also adds things the Sphere API doesn't have:

  • Declarative components that clean up after themselves, with props that update the map in place.
  • React content as marker icons, popups and map controls.
  • Clustering for React markers with <MarkerCluster>.
  • The current view as state (onViewChange, useMapView), a loading fallback, and debounced autocomplete (useSuggest).
  • One language setting on SphereProvider for maps, search, routing and web services.
  • Route results as React state: status, summary, turn-by-turn steps with readable instructions, and a timeout for keys without routing.
  • onError for objects that never load, and errors with codes for every web service.
  • Spatial analysis and measurements on every shape ref.
  • A typed web services client that works on servers too, with its own gistda-sphere-react/services entry and a referer option for domain-restricted keys.
  • Components marked "use client", so they render from Next.js Server Components.
  • Workarounds for Sphere quirks: input={false} disabling interaction, labels in Fly mode, removing "a|b" tags, plain-text areas, and more.

On this page