Step-by-Step Guide:

The first step would be to add Mapbox domains to the list of domains. This will allow the Sisense environment to request the coordinates and relevant info to be retrieved from the Mapbox server.

The second important step would be to specify the level of data under the “location” in the widget itself. Available options are “Auto”, “Country”, “State/Province”, and “City”. While the default is set to “Auto”, it is highly recommended to specify the exact level to avoid any potential conflicts. Whenever data is sent to the Mapbox side without specifying the exact level, Mapbox will use the following logic to match the data:

const mapboxTypes = [
   'country',
   'place',
   'region',
   'district',
   'postcode',
   'locality',
   'neighborhood',
   'address',
];

This way, data will be compared to result in the same order - country > place > region, etc., and the first matching result returned will be used to plot the data over a widget map. For example value “Singapore, PE” will return the following result from Mapbox and be plotted on the widget map:

{
    "placetype": [
"address"
    ],
    "lookupKey": "Singapure, PE",
    "name": "Singapure, PE",
    "text": "Rua Singapura",
    "place_name": "Rua Singapura, Agamenon, Igarassu - Pernambuco, 53640-293, Brazil",
    "latLng": {
      "lat": -7.828923,
      "lng": -34.924252
    }

This is likely returned due to partially matching the street name "Rua Singapura" and partially matching the region "BR-PE".

Now, if we change the level for the dimension under locations to Country, Mapbox will return the following result as the first match:

{
    "placetype": [
"country"
    ],
    "lookupKey": "Singapure, PE",
    "name": "Singapure, PE",
    "text": "Peru",
    "place_name": "Peru",
    "latLng": {
"lat": -10.151093,
      "lng": -75.311132
    },
    "properties": {
      "mapbox_id": "dXJuOm1ieHBsYzpJckE",
      "wikidata": "Q419",
      "short_code": "pe"
}

This will be returned due to the country code “PE” for Peru, which is also a partially matching result.

The proper approach with compound would be to split the area/city/state/country values into separate columns. This can also be used within the same Scatter widget to provide a deeper and more accurate data plotting.

For more advanced cases, you can use the in-built API added as part of the release of L2025.1 version - https://docs.sisense.com/main/SisenseLinux/l2025-1-release-notes.htm#:~:text=What%27s%20Improved-,Area%20Map%20and%20Scatter%20Map,-Three%20new%20API

Sisense is now caching the result returned from Mapbox and stores the cache directly in the application database. This means that anytime the same Text value is sent, it will first be compared to the cache, and if the matching cache is found, the request to Mapbox will not be sent.

Let's review the “Singapore, PE” value and see how we can manually assign a proper location to the value, see the results returned from Mapbox, and delete the cached result.

The POST endpoint v1/geo/locations can be used to search for either a new or cached location. The example of the payload is next:

{
  "locations": [
    {
      "lookupKey": "Singapure, PE",
      "name": "Singapure, PE"
    }],
"geoLevel": "country"
}

The result will contain the country Peru:

{
    "placetype": [
      "country"
    ],
"lookupKey": "Singapure, PE",
    "name": "Singapure, PE",
    "text": "Peru",
    "place_name": "Peru",
    "latLng": {
      "lat": -10.151093,
      "lng": -75.311132
    },
    "properties": {
      "mapbox_id": "dXJuOm1ieHBsYzpJckE",
      "wikidata": "Q419",
      "short_code": "pe"
    }

The result above will be cached in the database. It can be confirmed by running a request against a POST endpoint v1/geo/locations/search with a simple payload:

{
  "locations": [
    {
"lookupKey": "Singapure, PE"
    }
  ]
}

Now, since we know this is inaccurate and we want it to return country Singapore, we will proceed with deleting the cache that is now saved using "lookupKey": "Singapore, PE" using a DELETE request to endpoint v1/geo/locations/remove with the same payload:

{
  "locations": [
    {
"lookupKey": "Singapure, PE"
    }
  ]
}

Once done, when we run a request to v1/geo/locations/search, we will receive an empty response.

The easiest way would be to run another POST request to v1/geo/locations without the “PE” part:

{
  "locations": [
    {
      "lookupKey": "Singapore",
      "name": "Singapore"

}],
"geoLevel": "country"
}

We can confirm the result is correct:

{
    "placetype": [
      "country",
"place"
    ],
    "lookupKey": "Singapure",
    "name": "Singapure",
    "text": "Singapore",
    "place_name": "Singapore",
    "latLng": {
      "lat": 1.351616,
      "lng": 103.808053
    },
    "properties": {
      "mapbox_id": "dXJuOm1ieHBsYzpJc2s",
      "wikidata": "Q334",
      "short_code": "sg"
    }

We can now take the result and manually “cache” it for value with “PE” by running a PATCH request to v1/geo/locations with the following payload:

{
  "locations": [
    {
      "name": "Singapure",
"latLng": {
        "lat": 1.351616,
      "lng": 103.808053
      },
      "placetype": [
        "country"
      ],
      "lookupKey": "Singapure, PE",
      "text": "Singapure, PE",
      "place_name": "Singapure, PE"

}
]
}

Once we successfully run it, we can confirm the cache by running the same POST request to v1/geo/locations/search, which no longer returns an empty result but is now returning the result we specified.

This can be used for either deleting inaccurate cached results, updating existing ones, or creating new cached results for complex cases.

Conclusion:

Following the guidelines provided in this article is expected to provide the best experience when using the Scatter map widget type

In case of any questions or issues related to Scatter Map, please contact our technical support team.

References/Related Content

It is required to add Mapbox URLs to the list of allowed domains - https://docs.mapbox.com/help/troubleshooting/firewalls/

General Scatter Map documentation - https://docs.sisense.com/main/SisenseLinux/scatter-map.htm

Disclaimer: This post outlines a potential custom workaround for a specific use case or provides instructions regarding a specific task. The solution may not work in all scenarios or Sisense versions, so we strongly recommend testing it in your environment before deployment. If you need further assistance with this, please let us know.