Configure Geo Charts in GoodData.CN
Geo charts (pushpins) and Geo area charts require a basemap provider and storage, configured via your Helm values.
This article explains how to configure the basemap provider and storage required for geo charts. The basemap provider is configured on the apiGw service (server side), so credentials are not exposed in the browser.
Steps:
- Basemap Provider
- Geo Collections Storage
- Ingestion Job
- Deploy or upgrade the Helm release.
Basemap Provider
Geo charts use a basemap served by the apiGw service. You must configure exactly one basemap provider.
Supported providers:
- AWS Location
- Mapbox
- Custom provider
AWS Location
Set:
apiGw:
locationService:
plugin: "AwsLocation"You can also optionally set:
apiGw:
awsLocationRegion: "us-east-1"When set, awsLocationRegion takes precedence over the service account region.
Use apiGw.awsLocationRegion when the service account is already configured, but AwsLocation must use a different AWS region. This avoids changing AWS_REGION globally, which could affect other integrations.
We recommend using IRSA via cloudIdentity. No client-side tokens are used. For example:
apiGw:
cloudIdentity:
enabled: true
aws:
roleArn: "arn:aws:iam::<account-id>:role/<role-name>"AWS Location permissions (IRSA/role policies)
When using AWS Location as the basemap provider, ensure the IAM role used by GoodData.CN (for example via IRSA) has the following permissions:
geo-maps:GetTilegeo-maps:GetStyleDescriptorgeo-maps:GetSpritesgeo-maps:GetGlyphs
Mapbox
Set:
apiGw:
locationService:
plugin: "MapboxLocation"
mapbox:
token: "your-mapbox-token"Custom provider
Set plugin: "CustomLocation" and define one or more custom basemaps in locationService.custom.styles. For example:
apiGw:
locationService:
plugin: "CustomLocation"
custom:
styles:
- id: "arcgis"
url: "https://<your-arcgis-host>/styles/root.json"
title: "ArcGIS Light"
# Example: adds header `Authorization: Bearer <your-token>`
auth:
type: "header"
name: "Authorization"
value: "Bearer <your-token>"
- id: "maptiler"
url: "https://api.maptiler.com/maps/streets/style.json"
title: "MapTiler Streets"
# Example: adds query parameter `?key=<your-api-key>`
auth:
type: "query"
name: "key"
value: "<your-api-key>"Each basemap must be provided as a MapLibre style document. For each entry:
idis the unique identifierurlis the URL to the MapLibrestyle.jsondocument, or afile://path for a mounted filetitleis optionalauthis optional
The first style in the list is used as the default basemap.
Most map providers that support this setup expose their basemaps as MapLibre style documents. For example, ArcGIS and MapTiler provide MapLibre-compatible styles. Google Maps uses its own styling model instead of MapLibre style documents, so it cannot be configured this way.
Geo Collections Storage
Geo charts rely on static geo collections, such as country or region boundaries. These collections must be stored in shared storage.
The configuration is similar to CSV storage, but it is configured independently and does not reuse the same secrets or authentication settings.
Amazon S3
quiver:
geoCollections:
storageType: "S3"
s3GeoCollectionsStorage:
s3Bucket: "your-bucket-name"
s3BucketPrefix: "prefix/path" # Optional
s3Region: "us-east-1" # Optional
authType: "aws_default" # Or "aws_tokens"
s3AccessKey: "" # Optional when using aws_default
s3SecretKey: "" # Optional when using aws_defaultCredentials for accessing the storage are configured in the same way as for CSV uploads. On AWS, we recommend IRSA with cloudIdentity enabled. Alternatively, you can provide static credentials via secrets.
For details, see Configure Quiver - AWS S3.
Azure
quiver:
geoCollections:
storageType: "ABS"
absGeoCollectionsStorage:
absAccountName: ${AZURE_STORAGE_ACCOUNT_NAME}
absContainer: ${AZURE_STORAGE_CONTAINER_NAME}
absContainerPrefix: ${CONTAINER_PREFIX}
authType: "azure_default"
absClientId: ${AZURE_CLIENT_ID}Ingestion Job
The ingestion job uploads static geo collections into the configured storage so they can be used by geo charts.
It uses the same storage credentials that you configured for geo collections storage in the previous step.
mapIngestionJob:
enabled: true
deployQuiverGeoCollections: trueService Account Configuration
If you use a service account for accessing the geo collections storage, the same service account must also be used by the map-ingestion-job.
The ingestion job does not automatically reuse credentials from other components, so ensure the authentication method is configured consistently.
Maximum Zoom Level
By default, the maximum zoom level in GoodData.CN is unlimited. You can set a maximum map zoom level (maximum is 22) using the following setting:
platform_limits:
max_zoom_level: 12