GeoMap

ESRI integration

No additional installation steps are needed to use the GeoMap with ESRI once FastTrack is installed. However, developers will need to acquire their own ArcGIS developer API Key (see Introduction to API key authentication ) and add it to the GeoMap configuration. This can be accomplished by setting the esriApiKey prop on GeoMap to the developer's ESRI API Key.

Markers configuration

Data on the GeoMap can be visualized with markers using the "markers" and "transformMarkers" props.

The "markers" property should be set to the collection of results data to visualize on the map. The results format should be an array of objects with latitude and longitude properties.

The "transformMarkers" property should be set to a function that transforms the data into the proper GeoMap format with latitude and longitude properties. This transform function should iterate over the results and return each data object in this format:

{
	point: {
    	latitude: yourLatitude
        longitude: yourLongitude
        uri: yourURI
    }
}

To style each respective data point, add a symbol object inside the returned object in the transform. The symbol object can contain type, color, text, and font customizations as shown in the code.

Note

Text values should correspond to ESRI standardized icon font text See Esri Icon Font (Calcite theme).

{
	point: {
    	latitude: yourLatitude
        longitude: yourLongitude
        uri: yourURI
    },
	symbol: {
	type: "text",
    color: "Tomato"
    text: "\ue61d", // esri-icon-map-pin
    font: {
    	size: 24
	}
}

Shapes configuration

Static shapes can be placed on the GeoMap in a similar fashion using the "shapes" and "transformShapes" props.

These static shape renderings should not be confused with the "sketch" functionality that enables polygon drawing on the map to narrow down search results.

The "shapes" property should be set to an array of objects with each object containing a geometry object and a styling object for each respective shape. The geometry object should consist of the shape type and "rings" array of vertices making up that shape, or the "paths" array for lines. For example:

geometry: {
      type: "polygon",
      // Bermuda Triangle
      rings: [
        [
          [-64.78, 32.3],
          [-66.07, 18.45],
          [-80.21, 25.78],
          [-64.78, 32.3]
        ]
      ]
    },
    symbol: {
      type: "simple-fill",
      color: [227, 139, 79, 0.4],
      outline: {
        type: "simple-line",
        color: [0, 128, 0],
        width: 1
      }
    }

geometry: {
      type: "polyline",
      paths: [
        [
          [-123.1207, 49.2827], // Vancouver
          [-114.0719, 51.0447], // Calgary
          [-113.4937, 53.5461]  // Edmonton
        ]
      ]
    },
    symbol: {
      type: 'simple-line',
      color: "blue",
      width: 3
    }

Geospatial search using polygons

This section contains database requirements and widget specifications.

Database requirements

For MarkLogic to identify geospatial properties in your data, geospatial indexes must be configured in the MarkLogic database. This can be done through the Admin UI (http://localhost:8001) or through MarkLogic's various programmatic APIs. See GeoMap API.

Admin UI

To configure a geospatial index using the Admin UI:

Access the content database that contains your data in the GUI.
The subsection Geospatial Point Indexes lets you configure various types of geospatial indexes. Which one you use will depend on how the latitude and longitude coordinates in the documents are structured.
For coordinates nested under a parent element, create a geospatial element pair index. Specify the following fields at a minimum:
1. "Parent Localname": parent property that has the latitude and longitude values as children.
2. "latitude": child property with the latitude coordinate.
3. "longitude": child property with the longitude coordinate.

For more about MarkLogic geospatial indexes, see: Understanding Geospatial Query and Index Types.

Example configuration in the Admin UI

Screenshot of the Geospatial Point Indexes section.

Rest API

Indexes can also be setup with a PUT call to MarkLogic's REST API /manage/v2/databases/{id|name}/properties.

Note

Substitute the databases ID or name for id|name.

To setup a Geospatial Element Pair Index on a database using a JSON payload, pass this code in the HTTP body:

{
  "geospatial-element-pair-index": [
    {
      "parent-namespace-uri": "",
      "parent-localname": "PARENT-ELEMENT-NAME",
      "latitude-localname": "LATITUDE-ELEMENT-NAME",
      "latitude-namespace-uri": "",
      "longitude-localname": "LONGITUDE-ELEMENT-NAME",
      "longitude-namespace-uri": "",
      "coordinate-system": "wgs84",
      "range-value-positions": false,
      "invalid-values": "reject"
    }
  ]
}

For more about using the REST API for configuring databases, see: PUT /manage/v2/databases/{id|name}/properties.

Widget specifications

To use geospatial search with polygons, configure the sketch, sketchPosition, selectionTools, and onGeoSearch properties.

sketch

Set this property to true to enable polygon drawing capabilities on the map. This opens a sketch toolbar providing a selection of shapes to be drawn.

sketchPosition

Repositions the toolbar as desired. Possible values are "top-right", "top-left", "bottom-left", and "bottom-right".

selectionTools

Configures the shapes offered as selection options to sketch on the map. These will be displayed on the sketch toolbar. By default, all options are displayed. To disable an option, pass in an object that sets the "polygon", "circle", "rectangle", "rectangle-selection", or "lasso-selection" object to false. For example:

selectionTools={
    {
        'lasso-selection': false,
        'rectangle-selection': false
    }
}

onGeoSearch

This property takes in a callback function that should build and add a geo-constraint to the search query in MarkLogicContext based on coordinates of the polygon(s) drawn on the GeoMap. These respective polygon coordinates are provided by ESRI and automatically propagated from the GeoMap widget to the argument belonging in the specified callback function. Within this callback function, all specifications pertaining to the geospatial query being made should be defined respective to your data. The required parameters to set are:

type : string value describing the type of geospatial query. See Syntax Reference.
lat : string value matching the property in your data where "latitude" coordinates are defined.
lon : string value matching the property in your data where "longitude" coordinates are defined.
parent : string value matching the property of the object in your data where both latitude/longitude coordinates lie under.
polygon : Array values containing a transformation of all "point" objects that form the search polygon's vertices (see example transform below).

Once these parameters are defined in a query object, the final step is to add the geo-constraint to the MarkLogicContext which will automatically trigger a geo-spatial search:

const handleGeoSearch = (polygonsCoordsArr) => {
    const query = 
        {
          "type": "geo-elem-pair-query",
          "lat": "Latitude",
          "lon": "Longitude",
          "parent": "Location",
          "polygon": polygonsCoordsArr.map((coords) => {
              const pointObj = {
                "point": coords[0]?.map((ele) => {
                  return {
                    "latitude": parseFloat(ele[1]),
                    "longitude": parseFloat(ele[0])
                  }
                })
              }
              return pointObj
          })
        }
    context.addGeoConstraint(query);
  }

2D and 3D maps

This section includes information on 2D and 3D maps.

2D map

To initialize the GeoMap as a 2D map, set the GeoMap props "viewType", and "useWeb".
(Optional) provide values for "center" and "zoom" to preset the default display.
1. "center" takes in an array of latitude and longitude coordinates representing the center where the display will start.
2. "zoom" takes in any integer from 0 to 23 in order of least greatest magnitude of zoom.
Set "viewType" to "2D" and "useWeb" to false.

Center and zoom example

"center" =  [-98.556, 39.810]
"zoom" = 4

Example 2D map display of geospatial search results with markers

3D map

To initialize the GeoMap as a 3D map, the GeoMap props "viewType" ,"useWeb", and "camera" should be set.
Set "viewType" = "3D" and "useWeb" = true.

The "camera" property is used to determine the observation point from which the visible portion (or perspective) of the SceneView is determined. Options such as elevation, heading, tilt, etc. can be configured. A value in this property will override any "center" or "zoom" properties defined. For in-depth examples, see camera).

Example 3D map display of geospatial search results represented with markers

GeoMap API

Prop	Type	Description
basemap	string	ESRI basemap name. Default: `“streets-relief-vector”`.
center	[number, number]	Map center as a tuple of latitude and longitude values.
zoom	number	ESRI map zoom value. Usually ranges from 0 (global view) to 23 (detailed view).
markers	object[]	Array of marker definitions. `markers[].geometry` takes an object of Point properties, an mgrs property for MGRS values, or a utm property for UTM values. `markers[].symbol` takes an object of Symbol properties.
shapes	object[]	Array of shape definitions. `shapes[].geometry` takes an object of Polygon properties or Polyline properties with a type of `"polygon"` or `"polyline"`, respectively. `shapes[].symbol` takes an object of SimpleLineSymbol properties or SimpleFillSymbol properties with a type of `"simple-line"` or `"simple-fill"` respectively.
ground	string	ESRI ground property for displaying a 3D map. Default: `“world-elevation”`.
viewType	string	Map view type (`"2D"` or `"3D"`). Default :`"2D"`.
showToggle	boolean	Show the basemap toggle widget. Default: `false`.
toggleBasemap	string	Basemap to toggle (in addition to the default basemap). Default: `“gray-vector”`.
togglePosition	string	Toggle position. `Default: “bottom-right”`.
addMarkerOnClick	boolean	Add points by clicking on the map. Default: `true`.
esriApiKey	string	ESRI Developer API Key value.
transformMarkers	function	Callback function for transforming the markers payload. Accepts the markers property payload and returns a transformed payload (array of marker definitions) to be used by the widget.
transformShapes	function	Callback function for transforming the shapes payload. Accepts the shapes property payload and returns a transformed payload (array of shape definitions) to be used by the widget.
sketch	boolean	Enable sketching tool interface on the map.
createTools	object	Enable/disable various geometry creation options in the sketching tool interface.
selectionTools	object	Enable/disable various selection options in the sketching tool interface.
sketchPosition	string	Placement of sketching tool interface on the map. Default: `“top-right”`.
symbol	object	Default ESRI symbol to use for map markers.
width	string	Width of widget container as a CSS width string (e.g., `"500px"`).
height	string	Height of widget container as a CSS height string (e.g., `"300px"`).
useWeb	boolean	Use a 2D WebMap or 3D WebScene, which are maps where configuration information is retrieved from an ArcGIS server. If `true`, must also supply `portalItemID`. Default: `false`.
portalItemID	string	ESRI portalItem ID for displaying a WebMap or WebScene.
camera	object	ESRI camera object for initializing the observation point in a 3D map.
showGallery	boolean	Show the basemap gallery widget.
galleryQuery	string	Gallery query for determining available basemaps. Default: `"World Basemaps for Developers" AND owner:esri`.
galleryPosition	string	Gallery position. Default: `“top-right”`.
activeSelection	string	ID of currently selected marker.
activeSelectionColor	string	Color to apply to selected marker.
activeSelectionZoom	number	Zoom to apply when marker is selected.
onClickMap	((attributes: any, event: any) => void)	Callback function triggered when the map area is clicked. Receives an object of attributes of the clicked area or element and an event object.
onGeoSearch	((arr: []) => void)	Callback function for submitting a geospatial search query. Based on polygon coordinates that are passed in as an array.
popupTemplate	object	Template to set generic properties of the popovers in the map.
popupFeatureLayer	object	Array of FeatureLayers for creating complex scenarios with popovers.

Develop with FastTrack

GeoMap

ESRI integration

Markers configuration

Note

Shapes configuration

Geospatial search using polygons

Database requirements

Admin UI

Example configuration in the Admin UI

Rest API

Note

Widget specifications

2D and 3D maps

2D map

Center and zoom example

Example 2D map display of geospatial search results with markers

3D map

Example 3D map display of geospatial search results represented with markers

GeoMap API

Search results