`, removing it from the DOM. The map ref then points to nothing and the map cannot recover.
### Solution:
Keep the container div always mounted and use an overlay for error messages:
```jsx
// ❌ Wrong — replaces the container div
if (error) return
Something went wrong
;
// ✅ Correct — overlay on top of the container
return (
<>
{error &&
Something went wrong
}
);
```
---
## 🔴 Coordinates Not Displaying Correctly
### Symptoms:
- Marker appears in wrong location
- Map centered on wrong place
### Cause:
Mixing up longitude and latitude order
### Solution:
**MapMetrics uses [longitude, latitude] order:**
```javascript
// ❌ WRONG - [latitude, longitude]
center: [40.7128, -74.0060] // This is backwards!
// ✅ CORRECT - [longitude, latitude]
center: [-74.0060, 40.7128] // Longitude first!
// ✅ For API requests, use object notation:
{
"lat": 40.7128,
"lon": -74.0060
}
```
**Remember:**
- **Map/SDK**: `[longitude, latitude]` (array)
- **REST API**: `{lat: number, lon: number}` (object)
---
## 🔴 Geocoding Returns Empty Results
### Symptoms:
- API returns `[]` or no features
- Can't find addresses
### Common Causes:
**1. Missing Token**
```javascript
// ❌ WRONG
fetch('https://gateway.mapmetrics-atlas.net/forward-geocode/?text=Paris')
// ✅ CORRECT
fetch('https://gateway.mapmetrics-atlas.net/forward-geocode/?token=YOUR_TOKEN&text=Paris')
```
**2. Text Not URL Encoded**
```javascript
// ❌ WRONG - Spaces not encoded
const url = `...?text=New York City`
// ✅ CORRECT - Use encodeURIComponent
const text = encodeURIComponent('New York City');
const url = `...?text=${text}`
```
**3. Too Specific Query**
```javascript
// ❌ Might not find
"1234 Some Random Street That Doesn't Exist"
// ✅ Better - Start broad
"Paris, France"
"New York"
```
---
## 🔴 Geocoding Returns 200 But No Results
This is specifically about the **v2 geocoder** (`/v2/autocomplete/`,
`/v2/retrieve/`, `/v2/retrieve-batch/`, `/v2/forward-geocode/`,
`/v2/reverse-geocode/`). Almost every v2 misuse below answers with
**HTTP 200** and an empty or unexpected result set rather than an error —
if a v2 request "isn't finding anything," check this list before assuming
the data is missing.
### 1. Using `text` instead of `q`
v2 endpoints take **`q`**, not `text` (the v1 parameter name).
```bash
# ❌ WRONG - v1 parameter name on a v2 endpoint
curl "https://gateway.mapmetrics-atlas.net/v2/autocomplete/?text=Nieuwezijds%20Voorburgwal%20147&token=YOUR_API_KEY"
# → HTTP 200, {"results": [], "q": ""}
# ✅ CORRECT
curl "https://gateway.mapmetrics-atlas.net/v2/autocomplete/?q=Nieuwezijds%20Voorburgwal%20147&token=YOUR_API_KEY"
```
### 2. Missing `format=pelias` on forward/reverse geocode
Without `format=pelias`, `/v2/forward-geocode/` and
`/v2/reverse-geocode/` don't error — they silently return a **different,
flat response shape** instead of the documented GeoJSON
`FeatureCollection`. Code written against the `FeatureCollection` shape
then reads `features[0]` as `undefined`.
```bash
# ❌ WRONG - format omitted, returns the flat shape
curl "https://gateway.mapmetrics-atlas.net/v2/forward-geocode/?q=Nieuwezijds%20Voorburgwal%20147&country=nl&token=YOUR_API_KEY"
# ✅ CORRECT
curl "https://gateway.mapmetrics-atlas.net/v2/forward-geocode/?q=Nieuwezijds%20Voorburgwal%20147&country=nl&format=pelias&token=YOUR_API_KEY"
```
### 3. `retrieve-batch` called with repeated params instead of one `items` array
`/v2/retrieve-batch/` takes exactly **one** parameter, `items`, holding a
URL-encoded JSON array. Repeated params (`ord=`, `ords=`, `ids=`) return
HTTP 200 with `count: 0` — no error.
```bash
# ❌ WRONG - repeated params, silently returns count: 0
curl "https://gateway.mapmetrics-atlas.net/v2/retrieve-batch/?ord=128371&ord=128372&token=YOUR_API_KEY"
# ✅ CORRECT - one items param, URL-encoded JSON array
curl "https://gateway.mapmetrics-atlas.net/v2/retrieve-batch/?items=%5B%7B%22country%22%3A%22nl%22%2C%22layer%22%3A%22address%22%2C%22ord%22%3A128371%7D%5D&token=YOUR_API_KEY"
```
### 4. Retrieving by `id` instead of `ord`
`/v2/retrieve/` is keyed on **`ord`**, the handle returned by
autocomplete — not `id`. Passing `id` 404s on every layer.
```bash
# ❌ WRONG - id instead of ord
curl "https://gateway.mapmetrics-atlas.net/v2/retrieve/?country=nl&layer=address&id=osm:ext:7f3a9c1d2e4b5a6f&token=YOUR_API_KEY"
# → 404
# ✅ CORRECT - ord from the autocomplete suggestion
curl "https://gateway.mapmetrics-atlas.net/v2/retrieve/?country=nl&layer=address&ord=128371&token=YOUR_API_KEY"
```
### 5. A `country` filter that excludes the result
A `country` param that doesn't match the actual country of the result
filters it out entirely — this returns 200 with an empty or short result
set, with no indication the filter was the cause.
```bash
# ❌ WRONG - country=de excludes a Dutch address, empty results
curl "https://gateway.mapmetrics-atlas.net/v2/forward-geocode/?q=Nieuwezijds%20Voorburgwal%20147&country=de&format=pelias&token=YOUR_API_KEY"
# ✅ CORRECT - country matches where the address actually is
curl "https://gateway.mapmetrics-atlas.net/v2/forward-geocode/?q=Nieuwezijds%20Voorburgwal%20147&country=nl&format=pelias&token=YOUR_API_KEY"
```
See also [API Keys & Security](./api-keys.md) for auth-related 401/403s,
which look different from these silent-empty-result cases.
---
## 🔴 CORS Errors
### Symptoms:
```
Access to fetch at '...' from origin 'http://localhost' has been blocked by CORS policy
```
### Cause:
Browser security - usually only in development
### Solution:
**For Development:**
Use a local server, not `file://`
```bash
# Use any local server
python -m http.server 8000
# or
npx serve .
# or
npm run dev
```
**For Production:**
Deploy to a proper domain (Vercel, Netlify, etc.)
---
## 🔴 NPM Package Import Errors
### Symptoms:
```
Module not found: Can't resolve '@mapmetrics/mapmetrics-gl'
```
### Solution:
**1. Install the CORRECT package:**
```bash
# ✅ CORRECT - MapMetrics package
npm install @mapmetrics/mapmetrics-gl
# ❌ WRONG - This is MapLibre, NOT MapMetrics!
npm install maplibre-gl
```
**2. Import correctly:**
```javascript
// ✅ CORRECT
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
// ❌ WRONG
import maplibregl from 'maplibre-gl'; // Wrong package!
```
**3. If using TypeScript, you may need:**
```typescript
declare module '@mapmetrics/mapmetrics-gl';
```
---
## 🔴 Using Wrong Package (maplibre-gl vs @mapmetrics/mapmetrics-gl)
### Symptoms:
- Map doesn't load even with valid token
- Authentication errors with MapMetrics style URLs
- Missing MapMetrics-specific features
### Cause:
Using `maplibre-gl` (the base library) instead of `@mapmetrics/mapmetrics-gl` (MapMetrics custom fork)
### Solution:
**Uninstall wrong package and install correct one:**
```bash
# Remove wrong package
npm uninstall maplibre-gl
# Install correct package
npm install @mapmetrics/mapmetrics-gl
```
**Update imports:**
```javascript
// ❌ Before (WRONG)
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
// ✅ After (CORRECT)
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
```
**Update all references:**
```javascript
// ❌ WRONG
const map = new maplibregl.Map({...});
const marker = new maplibregl.Marker();
// ✅ CORRECT
const map = new mapmetricsgl.Map({...});
const marker = new mapmetricsgl.Marker();
```
**Why this matters:**
- MapMetrics GL is a **custom fork** of MapLibre with proprietary features
- MapMetrics style URLs **only work** with the MapMetrics package
- The packages are **NOT interchangeable**
---
## 🔴 Directions API: No Route Found
### Symptoms:
```json
{
"error": "No route found"
}
```
### Common Causes:
**1. Unreachable Locations**
```javascript
// Locations on different continents with no ferry routes
locations: [
{ lat: 40.7128, lon: -74.0060 }, // New York
{ lat: 51.5074, lon: -0.1278 } // London - needs ferry!
]
```
**2. Invalid Costing Model**
```javascript
// ❌ Wrong costing for the route
costing: "bicycle" // But route includes highways
// ✅ Use appropriate costing
costing: "auto"
```
**3. Coordinates Reversed**
```javascript
// ❌ WRONG - lat/lon format in REST API
locations: [
{ lon: -74.0060, lat: 40.7128 } // Backwards!
]
// ✅ CORRECT - lat comes first in objects
locations: [
{ lat: 40.7128, lon: -74.0060 }
]
```
---
## 🆘 Still Having Issues?
### Checklist:
- [ ] **Do you have a valid token?** Get one at [portal.mapmetrics.org](https://portal.mapmetrics.org/)
- [ ] **Is the token in the URL?** Check for `?token=` or `&token=`
- [ ] **Is your map container styled?** Add `height: 500px` to CSS
- [ ] **Are coordinates in correct order?** `[longitude, latitude]` for maps
- [ ] **Check browser console** for error messages
- [ ] **Is JavaScript loading?** Check Network tab in DevTools
- [ ] **Using HTTPS in production?** Some features require secure context
### Get Help:
- 📖 [Documentation](/)
- 💬 [Discord Community](https://discord.com/invite/uRXQRfbb7d)
- 📧 Support: Contact via portal
---
## 🎓 Prevention Tips
### Before You Start:
1. ✅ Sign up at [portal.mapmetrics.org](https://portal.mapmetrics.org/)
2. ✅ Get your style URL (includes token)
3. ✅ Test with simple example first
4. ✅ Check browser console for errors
5. ✅ Read relevant example docs
### While Developing:
1. ✅ Always check token is present
2. ✅ Use browser DevTools to debug
3. ✅ Test API calls with curl first
4. ✅ Verify coordinates are correct
5. ✅ Keep documentation handy
---
**Most issues are solved by:**
1. Getting a valid API token
2. Adding it to your requests
3. Setting proper container height
**99% of "map not loading" issues = missing/invalid token!** 🔑
---
# Directions Api
https://docs.mapatlas.xyz/overview/directions/directions
# Directions Api
Routing Direction Service (a.k.a. turn-by-turn), is an open-source routing service that lets you integrate routing and navigation into a web or mobile application.
The **`/directions`** endpoint calculates a route between two points (origin → destination).
use your token in Query Param:
```http
POST /directions/?token=YOUR_TOKEN
```
## Example Request
```json
{ "locations": [ { "lat": "42.358528", "lon": "-83.271400" }, { "lat": "42.996613", "lon": "-78.749855" } ], "costing": "auto" ,"id":"my_work_route"}
```
There is an option to name your route request. You can do this by appending the following to your request &id=. The id is returned with the response so a user could match to the corresponding request.
| Parameter | Location |Required| Description |
| --------------| ----------- |--------| ------------------------------------------------------------------------------------------ |
| **token** | Query Param |✅ Yes | API authentication token. Required, otherwise request will fail with `401 Token required`. |
| **locations** | bodyjson |✅ Yes | Latitude,Longitude of the starting point to the destination point, "locations":[ { "lat": "42.358528", "lon": "-83.271400" }, { "lat": "42.996613", "lon": "-78.749855" } ], |
| **costing** | bodyjson |✅ Yes | "auto","bicycle","bus","truck","taxi","pedestrian" |
# Costing models
directions routing service uses dynamic, run-time costing to generate the route path. The route request must include the name of the costing model and can include optional parameters available for the chosen costing model.
| Costing model | Description |
|---------------|-------------|
| **auto** | Standard costing for driving routes by car, motorcycle, truck, and so on that obeys automobile driving rules, such as access and turn restrictions. `auto` provides a short time path (though not guaranteed to be shortest time) and uses intersection costing to minimize turns and maneuvers or road name changes. Routes also tend to favor highways and higher classification roads, such as motorways and trunks. |
| **bicycle** | Standard costing for travel by bicycle, with a slight preference for using cycleways or roads with bicycle lanes. Bicycle routes follow regular roads when needed, but avoid roads without bicycle access. |
| **bus** | Standard costing for bus routes. Bus costing inherits the auto costing behaviors, but checks for bus access on the roads. |
| **truck** | Standard costing for trucks. Truck costing inherits the auto costing behaviors, but checks for truck access, width and height restrictions, and weight limits on the roads. |
| **taxi** | Standard costing for taxi routes. Taxi costing inherits the auto costing behaviors, but checks for taxi lane access on the roads and favors those roads. |
| **motor_scooter** | Standard costing for travel by motor scooter or moped. By default, `motor_scooter` costing will avoid higher class roads unless the country overrides allows motor scooters on these roads. Motor scooter routes follow regular roads when needed, but avoid roads without motor_scooter, moped, or mofa access. |
| **pedestrian** | Standard walking route that excludes roads without pedestrian access. In general, pedestrian routes are shortest distance with the following exceptions: walkways and footpaths are slightly favored, while steps or stairs and alleys are slightly avoided. |
## Trip legs and maneuvers
A `trip` contains one or more `legs`. For *n* number of `break` locations, there are *n-1* legs.
`Through` locations do not create separate legs.
Each leg of the trip includes a summary, which is comprised of the same information as a trip summary but applied to the single leg of the trip. It also includes a `shape`, which is an encoded polyline of the route path (with 6 digits decimal precision), and a list of `maneuvers` as a JSON array.
For more about decoding route shapes, see these [code examples](#).
If `elevation_interval` is specified, each leg of the trip will return `elevation` along the route as a JSON array. The `elevation_interval` is also returned.
Units for both `elevation` and `elevation_interval` are either meters or feet based on the input units specified.
---
## Each maneuver includes
| Maneuver item | Description |
|----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **type** | Type of maneuver. See below for a list. |
| **instruction** | Written maneuver instruction. Describes the maneuver, such as `"Turn right onto Main Street"`. |
| **verbal_transition_alert_instruction** | Text suitable for use as a verbal alert in a navigation application. The transition alert instruction will prepare the user for the forthcoming transition.
Example: `"Turn right onto North Prince Street"`. |
| **verbal_pre_transition_instruction** | Text suitable for use as a verbal message immediately prior to the maneuver transition.
Example: `"Turn right onto North Prince Street, U.S. 2 22"`. |
| **verbal_post_transition_instruction** | Text suitable for use as a verbal message immediately after the maneuver transition.
Example: `"Continue on U.S. 2 22 for 3.9 miles"`. |
| **street_names** | List of street names that are consistent along the entire nonobvious maneuver. |
| **begin_street_names** | When present, these are the street names at the beginning (transition point) of the nonobvious maneuver (if they are different than the names that are consistent along the entire nonobvious maneuver). |
| **time** | Estimated time along the maneuver in seconds. |
| **length** | Maneuver length in the units specified. |
| **begin_shape_index** | Index into the list of shape points for the start of the maneuver. |
| **end_shape_index** | Index into the list of shape points for the end of the maneuver. |
| **toll** | `true` if the maneuver has any toll, or portions of the maneuver are subject to a toll. |
| **highway** | `true` if a highway is encountered on this maneuver. |
| **rough** | `true` if the maneuver is unpaved or rough pavement, or has any portions that have rough pavement. |
| **gate** | `true` if a gate is encountered on this maneuver. |
| **ferry** | `true` if a ferry is encountered on this maneuver. |
| **sign** | Contains the interchange guide information at a road junction associated with this maneuver. See below for details. |
| **roundabout_exit_count** | The spoke to exit roundabout after entering. |
| **depart_instruction** | Written depart time instruction. Typically used with a transit maneuver, such as `"Depart: 8:04 AM from 8 St - NYU"`. |
| **verbal_depart_instruction** | Text suitable for use as a verbal depart time instruction. Typically used with a transit maneuver, such as `"Depart at 8:04 AM from 8 St - NYU"`. |
| **arrive_instruction** | Written arrive time instruction. Typically used with a transit maneuver, such as `"Arrive: 8:10 AM at 34 St - Herald Sq"`. |
| **verbal_arrive_instruction** | Text suitable for use as a verbal arrive time instruction. Typically used with a transit maneuver, such as `"Arrive at 8:10 AM at 34 St - Herald Sq"`. |
| **transit_info** | Contains the attributes that describe a specific transit route. See below for details. |
| **verbal_multi_cue** | `true` if the `verbal_pre_transition_instruction` has been appended with the verbal instruction of the next maneuver. |
| **travel_mode** | Travel mode:
• `"drive"`
• `"pedestrian"`
• `"bicycle"`
• `"transit"` |
| **travel_type** | Travel type for drive:
• `"car"`
• `"motorcycle"`
• `"motor_scooter"`
• `"truck"`
• `"bus"`
Travel type for pedestrian:
• `"foot"`
• `"wheelchair"`
Travel type for bicycle:
• `"road"`
• `"hybrid"`
• `"cross"`
• `"mountain"`
Travel type for transit:
• Tram or light rail = `"tram"`
• Metro or subway = `"metro"`
• Rail = `"rail"`
• Bus = `"bus"`
• Ferry = `"ferry"`
• Cable car = `"cable_car"`
• Gondola = `"gondola"`
• Funicular = `"funicular"` |
| **bss_maneuver_type** | Used when `travel_mode` is `bikeshare`. Describes bike share maneuver. The default value is `"NoneAction"`.
Options:
• `"NoneAction"`
• `"RentBikeAtBikeShare"`
• `"ReturnBikeAtBikeShare"` |
| **bearing_before** | The clockwise angle from true north to the direction of travel immediately before the maneuver. |
| **bearing_after** | The clockwise angle from true north to the direction of travel immediately after the maneuver. |
| **lanes** | An array describing lane-level guidance. Used when `turn_lanes` is enabled. See below for details. |
## Directions Options
Directions options should be specified at the top level of the JSON object.
| Options | Description |
|--------------------|-------------|
| **units** | Distance units for output. Allowable unit types are miles (or mi) and kilometers (or km). If no unit type is specified, the units default to kilometers. |
| **language** | The language of the narration instructions based on the [IETF BCP 47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag string. If no language is specified or the specified language is unsupported, United States-based English (en-US) is used. [Currently supported language list](https://valhalla.readthedocs.io/en/latest/api/languages/). |
| **directions_type** | An enum with 3 values:
- `none` indicating no maneuvers or instructions should be returned.
- `maneuvers` indicating that only maneuvers be returned.
- `instructions` indicating that maneuvers with instructions should be returned (this is the default if not specified). |
| **format** | Four options are available:
- `json` is default Valhalla routing directions JSON format.
- `gpx` returns the route as a GPX (GPS exchange format) XML track.
- `osrm` creates an OSRM compatible route directions JSON.
- `pbf` formats the result using protocol buffers. |
| **shape_format** | If `"format": "osrm"` is set: Specifies the optional format for the path shape of each connection. One of `polyline6` (default), `polyline5`, `geojson` or `no_shape`. |
| **banner_instructions** | If the format is `osrm`, this boolean indicates if each step should have the additional `bannerInstructions` attribute, which can be displayed in some navigation system SDKs. |
| **voice_instructions** | If the format is `osrm`, this boolean indicates if each step should have the additional `voiceInstructions` attribute, which can be heard in some navigation system SDKs. |
| **alternates** | A number denoting how many alternate routes should be provided. There may be no alternates or less alternates than the user specifies. Alternates are not yet supported on multipoint routes (that is, routes with more than 2 locations). They are also not supported on time dependent routes. |
---
## Example with language
```json
{"locations":[{"lat":40.730930,"lon":-73.991379},{"lat":40.749706,"lon":-73.991562}],"format":"osrm","costing":"bus","banner_instructions":true,"voice_instructions":true,"language":"es-ES"}
```
---
## Costing Options
You can customize route preferences using `costing_options` for different vehicle types. These options allow you to control route behavior such as avoiding tolls or highways.
### Using Tolls and Highways
For the `auto` costing model, you can specify whether to use or avoid tolls and highways:
- `use_tolls`: `1` (use tolls) or `0` (avoid tolls)
- `use_highways`: `1` (use highways) or `0` (avoid highways)
### Example with Tolls and Highways
```json
{
"locations": [
{"lat": "24.938833", "lon": "67.089141"},
{"lat": "25.385833", "lon": "68.367643"}
],
"costing": "auto",
"units": "km",
"alternates": 3,
"id": "route_request",
"directions_options": {
"alternates": 3
},
"costing_options": {
"auto": {
"use_tolls": 1,
"use_highways": 1
}
}
}
```
In this example:
- `"use_tolls": 1` means the route **will include** toll roads
- `"use_highways": 1` means the route **will include** highways
- Set to `0` to **avoid** tolls or highways respectively
# Supported Language Tags
| Language tag | Language alias | Description |
|---------------|----------------|------------------------|
| **bg-BG** | bg | Bulgarian (Bulgaria) |
| **ca-ES** | ca | Catalan (Spain) |
| **cs-CZ** | cs | Czech (Czech Republic) |
| **da-DK** | da | Danish (Denmark) |
| **de-DE** | de | German (Germany) |
| **el-GR** | el | Greek (Greece) |
| **en-GB** | en | English (United Kingdom) |
| **en-US-x-pirate** | en-x-pirate | English (United States) Pirate |
| **en-US** | en | English (United States) |
| **es-ES** | es | Spanish (Spain) |
| **et-EE** | et | Estonian (Estonia) |
| **fi-FI** | fi | Finnish (Finland) |
| **fr-FR** | fr | French (France) |
| **hi-IN** | hi | Hindi (India) |
| **hu-HU** | hu | Hungarian (Hungary) |
| **it-IT** | it | Italian (Italy) |
| **ja-JP** | ja | Japanese (Japan) |
| **nb-NO** | nb | Bokmål (Norway) |
| **nl-NL** | nl | Dutch (Netherlands) |
| **pl-PL** | pl | Polish (Poland) |
| **pt-BR** | pt | Portuguese (Brazil) |
| **pt-PT** | pt | Portuguese (Portugal) |
| **ro-RO** | ro | Romanian (Romania) |
| **ru-RU** | ru | Russian (Russia) |
| **sk-SK** | sk | Slovak (Slovakia) |
| **sl-SI** | sl | Slovenian (Slovenia) |
| **sv-SE** | sv | Swedish (Sweden) |
| **tr-TR** | tr | Turkish (Turkey) |
| **uk-UA** | uk | Ukrainian (Ukraine) |
## Outputs of a route
The route results are returned as a `trip`. This is a JSON object that contains details about the trip, including locations, a summary with basic information about the entire trip, and a list of `legs`.
| Trip item | Description |
|--------------|-----------------------------------------------------------------------------|
| `status` | Status code. |
| `status_messa` | Status message. |
| `units` | The specified units of length are returned, either kilometers or miles. |
| `language` | The language of the narration instructions. If the user specified a language in the directions options and the specified language was supported - this returned value will be equal to the specified value. Otherwise, this value will be the default (en-US) language. |
| `locations` | Location information is returned in the same form as it is entered with additional fields to indicate the side of the street. |
| `warnings` (optional) | This array may contain warning objects informing about deprecated request parameters, clamped values etc. |
---
## Example Response
```json
{
"trip": {
"locations": [
{
"type": "break",
"lat": 42.358528,
"lon": -83.271400,
"original_index": 0
},
{
"type": "break",
"lat": 42.996613,
"lon": -78.749855,
"original_index": 1
}
],
"legs": [
{
"maneuvers": [
{
"type": 2,
"instruction": "Drive northeast on Appleton Avenue.",
"verbal_pre_transition_instruction": "Drive northeast on Appleton Avenue for 1.2 miles.",
"street_names": ["Appleton Avenue"],
"time": 142.5,
"length": 1.932,
"cost": 142.5,
"begin_shape_index": 0,
"end_shape_index": 23,
"highway": false,
"toll": false,
"rough": false,
"gate": false,
"ferry": false,
"travel_mode": "drive",
"travel_type": "car"
},
{
"type": 15,
"instruction": "Turn right onto Main Street.",
"verbal_pre_transition_instruction": "Turn right onto Main Street.",
"street_names": ["Main Street"],
"time": 45.2,
"length": 0.542,
"cost": 45.2,
"begin_shape_index": 23,
"end_shape_index": 35,
"highway": false,
"toll": false,
"rough": false,
"gate": false,
"ferry": false,
"travel_mode": "drive",
"travel_type": "car"
},
{
"type": 4,
"instruction": "You have arrived at your destination.",
"verbal_pre_transition_instruction": "You have arrived at your destination.",
"time": 0,
"length": 0,
"cost": 0,
"begin_shape_index": 35,
"end_shape_index": 35,
"travel_mode": "drive",
"travel_type": "car"
}
],
"summary": {
"has_time_restrictions": false,
"has_toll": false,
"has_highway": true,
"has_ferry": false,
"min_lat": 42.358421,
"min_lon": -83.271523,
"max_lat": 42.997234,
"max_lon": -78.749234,
"time": 18734.567,
"length": 453.211,
"cost": 18734.567
},
"shape": "gysalAlg~j}ClFhBnHdCrKrDfKjDdK~CjGtB|@b@n@TdG`Cd@VzEnBb@l@\\Vh@d@b@n@f@d@nRzQpCvCNPPRNNFHHJFDDDJLVTFJTVFDx@z@d@j@\\^r@r@`@`@NPNPJLJJLJHHHJDFJHb@b@j@h@nBnBlBnBvBvBpBpBxBxBvBvBjBjB^`@Z\\TTNR^\\~@z@hDfDbArATVrBnBlAfAbEhEXXt@v@dCdCZ\\vBvB`@`@RPLJJJ~ArAXVlEjEdDfDVVHHJHRRPPNNrFrFbBbBfLjLhBlBp@n@~D`EtCxCv@t@~@`AxIbJzD~DnLrLbDdDTVFHn@l@bBfBdDdDdAhAfC~BrBnBXV^l@d@\\l@dArBv@rBnA|Bd@x@PZHJp@rAnAtB`BjCjBxChCbEfApB|GjLxBtDl@pA^v@`BdDlBfDrBvDHNvExH\\n@z@bBrBhDxBzDNTjAtBpC~EbBvCdAnBjAjBbDbFpA`C^r@hAnBnB~Cl@dA|@xAlFbJfAnBtBhDvFlJv@tAfCxDpD~FZj@dApB|E|HfBzC^p@tDhGtAnClBpDvA~BhAlBx@~A`AjBlBnDx@|AnCfFzGjMf@bAfChFp@tAZ~@h@v@pB|D|@bBzBbEjHzMfBxCz@zAvDbHNTpCtF`BfCfCdE~C|FpBnDn@~@|BfE`D`HdAxBlAnC"
}
],
"summary": {
"has_time_restrictions": false,
"has_toll": false,
"has_highway": true,
"has_ferry": false,
"min_lat": 42.358421,
"min_lon": -83.271523,
"max_lat": 42.997234,
"max_lon": -78.749234,
"time": 18734.567,
"length": 453.211,
"cost": 18734.567
},
"status_message": "Found route between points",
"status": 0,
"units": "kilometers",
"language": "en-US"
}
}
```
---
# Elevation API
https://docs.mapatlas.xyz/overview/directions/elevation
# Elevation API
Elevation lookup service provides digital elevation model (DEM) data as the result of a query. The elevation service data has many applications when combined with other routing and navigation data, including computing the steepness of roads and paths or generating an elevation profile chart along a route.
## Inputs of the elevation service
An elevation service request takes the form of json={}, where the JSON inputs inside the {} includes location information.
# Use Shape list for input location
The elevation request run locally takes the form of json={}, where the JSON inputs inside the {} are described below.
A shape request must include a latitude and longitude in decimal degrees, and the locations are visited in the order specified. The input coordinates can come from many input sources, such as a GPS location, a point or a click on a map, a geocoding service, and so on.
These parameters are available for shape.
# Shape Parameters
| Parameter | Description |
|-----------|------------------------------------|
| `lat` | Latitude of the location in degrees |
| `lon` | Longitude of the location in degrees |
| `token` | token parameter is required /elevation/?token=YOUR TOKEN
---
## Example 1: Request with `range` and `shape`
```json
{"range":true,"shape":[{"lat":40.712431,"lon":-76.504916},{"lat":40.712275,"lon":-76.605259},{"lat":40.712122,"lon":-76.805694},{"lat":40.722431,"lon":-76.884916},{"lat":40.812275,"lon":-76.905259},{"lat":40.912122,"lon":-76.965694}]}
```
## Example 2:
```json
{"shape":[{"lat":40.712433,"lon":-76.504913},{"lat":40.712276,"lon":-76.605263},{"lat":40.712124,"lon":-76.805695},{"lat":40.722431,"lon":-76.884918},{"lat":40.812275,"lon":-76.905258},{"lat":40.912121,"lon":-76.965691}],"range_height":[[0,307],[8467,272],[25380,204],[32162,204],[42309,180],[54533,198]]}
```
## Example 3:
```json
{"range":true,"shape":[{"lat":40.712431,"lon":-76.504916},{"lat":40.712275,"lon":-76.605259},{"lat":40.712122,"lon":-76.805694},{"lat":40.722431,"lon":-76.884916},{"lat":40.812275,"lon":-76.905259},{"lat":40.912122,"lon":-76.965694}]}
```
---
## Example Response
```json
{
"shape": [
{"lat": 40.712431, "lon": -76.504916},
{"lat": 40.712275, "lon": -76.605259},
{"lat": 40.712122, "lon": -76.805694},
{"lat": 40.722431, "lon": -76.884916},
{"lat": 40.812275, "lon": -76.905259},
{"lat": 40.912122, "lon": -76.965694}
],
"range_height": [
[0, 307],
[8467, 272],
[25380, 204],
[32162, 204],
[42309, 180],
[54533, 198]
],
"height": [307, 272, 204, 204, 180, 198]
}
```
**Response Fields:**
- `shape`: Array of lat/lon coordinates that were queried
- `range_height`: Array of `[distance, elevation]` pairs where distance is in meters from the start point
- `height`: Simple array of elevation values in meters corresponding to each coordinate in the shape
---
# Isochrones Maps
https://docs.mapatlas.xyz/overview/directions/isochrone
# Isochrones Maps
The ability to return these amazing structures called isochrones. What's an isochrone? The word is a combination of two greek roots iso meaning equal and chrono meaning time. So indeed, an isochrone is a structure representing equal time. In our case it's a line that represents constant travel time about a given location. One can think of isochrone maps as somewhat similar to the familiar topographic maps except that instead of lines of constant height, lines are of constant travel time are depicted. For this reason other terms common in topography apply such as contours or isolines.
This is an example of 15, 30, 45 and 60 minute bicycle isochrones centered in Lancaster, PA.
# Inputs of the Isochrone Service
An isochrone request run locally takes the form of json={}, where the JSON inputs inside the {} includes an array of at least one location
For example, you can use the isochrone service to find out where you can travel within a 15-minute walk from your office building. The API request for this uses isochrone? as the request action, pedestrian costing, and a single contour for a 15-minute time interval. The response is GeoJSON, which you can display on a map to visualize where you might be able to walk.
```json
{"locations":[{"lat":40.744014,"lon":-73.990508}],"costing":"pedestrian","contours":[{"time":15.0,"color":"ff0000"}]}
```
# Parameters & bodyjson
| Parameter | Description |
|-----------|------------------------------------|
| `lat` | Latitude of the location in degrees |
| `lon` | Longitude of the location in degrees |
| `token` | token parameter is required /elevation/?token=YOUR TOKEN
---
# Output of Isochrone Service
In the service response, the isochrone contours are returned as GeoJSON, which can be integrated into mapping applications.
The isochrone service returns contours as GeoJSON line or polygon features for the requested intervals (depending on the value of the polygons request parameter). These contours are calculated using a two dimensional grid. If the format request parameter is set to geotiff, the underlying grid data is returned directly instead of the contours derived from it. It will return one band for each requested metric (i.e. one for time and one for distance). If an isochrone request has been named using the optional &id= input, then the id is returned as a name property for the feature collection within the GeoJSON response. A metric attribute lets you know whether it's a distance or time contour. A warnings array may also be included. This array may contain warning objects informing about deprecated request parameters, clamped values etc.
# Other request bodyjson content
| Parameter | Description |
|--------------|-----------------------------------------------------------------------------|
| `date_time` | The local date and time at the location.
- `type`
- `0` - Current departure time.
- `1` - Specified departure time.
- `2` - Specified arrival time. Note: This is not yet implemented for `multimodal`.
- `value` - the date and time specified in ISO 8601 format (YYYY-MM-DDThh:mm) in the local time zone of departure or arrival. For example, "2016-07-03T08:06". |
| `contours` | A JSON array of contour objects with the time in minutes or distance in kilometers and color to use for each isochrone contour. You can specify up to four contours (by default).
- `time` - A floating point value specifying the time in minutes for the contour.
- `distance` - A floating point value specifying the distance in kilometers for the contour.
- `color` - The color for the output of the contour. Specify it as a Hex value, but without the `#`, such as `"ff0000"` for red. If no color is specified, the isochrone service will assign a default color to the output.
You can only specify one metric per contour, i.e. time or distance. |
| `polygons` | A Boolean value to determine whether to return geojson polygons or linestrings as the contours. The default is `false`, which returns lines; when `true`, polygons are returned. Note: When polygons is `true`, a feature's geometry type can be either `Polygon` or `MultiPolygon`, depending on the number of exterior rings formed for a given interval. |
| `denoise` | A floating point value from 0 to 1 (default of 1) which can be used to remove smaller contours. A value of 1 will only return the largest contour for a given time value. A value of 0.5 drops any contours that are less than half the area of the largest contour in the set of contours for that same time value. |
| `generalize` | A floating point value in meters used as the tolerance for Douglas-Peucker generalization. Note: Generalization of contours can lead to self-intersections, as well as intersections of adjacent contours. |
| `show_locations` | A boolean indicating whether the input locations should be returned as MultiPoint features; one feature for the exact input coordinates and one feature for the coordinates of the network node it snapped to. Default false. |
---
## Example Response (GeoJSON Polygon)
```json
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[-73.990508, 40.744014],
[-73.989234, 40.745123],
[-73.987654, 40.746234],
[-73.986123, 40.747345],
[-73.985432, 40.748456],
[-73.984321, 40.749567],
[-73.983210, 40.750678],
[-73.990508, 40.744014]
]
]
},
"properties": {
"fill": "#ff0000",
"fillOpacity": 0.33,
"fill-opacity": 0.33,
"fillColor": "#ff0000",
"color": "#ff0000",
"contour": 0,
"opacity": 0.33,
"metric": "time",
"value": 15
}
}
],
"bbox": [-73.995234, 40.738765, -73.983210, 40.750678]
}
```
## Example Response (GeoJSON LineString - polygons: false)
```json
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[-73.990508, 40.744014],
[-73.989234, 40.745123],
[-73.987654, 40.746234],
[-73.986123, 40.747345],
[-73.985432, 40.748456],
[-73.984321, 40.749567],
[-73.983210, 40.750678],
[-73.990508, 40.744014]
]
},
"properties": {
"fill": "#ff0000",
"fillOpacity": 0.33,
"fill-opacity": 0.33,
"fillColor": "#ff0000",
"color": "#ff0000",
"contour": 0,
"opacity": 0.33,
"metric": "time",
"value": 15
}
}
],
"bbox": [-73.995234, 40.738765, -73.983210, 40.750678]
}
```
---
# Map Matching
https://docs.mapatlas.xyz/overview/directions/mapMatch
# Map Matching
Map Matching service, you can match coordinates, such as GPS locations, to roads and paths that have been mapped in OpenStreetMap. By doing this, you can turn a path into a route with narrative instructions and also get the attribute values from that matched line.
# Map Matching API (`/map-matching/`)
The **`/map-matching`** API is used to match noisy GPS traces onto the road network, reconstructing the most probable route.
---
## Example Request
```http
GET /map-matching/?token=YOUR_API_TOKEN
```
```json
{
"shape": [
{ "lat": 39.983841, "lon": -76.735741, "type": "break" },
{ "lat": 39.983704, "lon": -76.735298, "type": "via" },
{ "lat": 39.983578, "lon": -76.734848, "type": "via" },
{ "lat": 39.983551, "lon": -76.734253, "type": "break" },
{ "lat": 39.983555, "lon": -76.734116, "type": "via" },
{ "lat": 39.983589, "lon": -76.733315, "type": "via" },
{ "lat": 39.983719, "lon": -76.732445, "type": "via" },
{ "lat": 39.983818, "lon": -76.731712, "type": "via" },
{ "lat": 39.983776, "lon": -76.731506, "type": "via" },
{ "lat": 39.983696, "lon": -76.731369, "type": "break" }
],
"costing": "auto",
"shape_match": "map_snap"
}
```
| Parameter | Location | Required | Description |
| ---------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| **token** | Query Param | ✅ Yes | API authentication token. Required, otherwise request will fail with `401 Token required`. |
| **shape** | Body JSON | ✅ Yes | Array of GPS coordinates with at least **2 points**. Each point must have `lat`, `lon`, and a `type` (`break` or `via`). |
| **costing** | Body JSON | ✅ Yes | Travel mode. Options: `auto`, `pedestrian`, `bicycle`, `bus`,`motor_scooter`. |
| **shape\_match** | Body JSON | ❌ No | Controls the map matching behavior. Common values: `map_snap` (default) Options: `walk_or_snap`, `map_snap`, `edge_walk`|
## Shape Match Options details
`shape_match` is an optional string input parameter. It allows some control of the matching algorithm based on the type of input.
| shape_match type | Description |
|-------------------|-----------------------------------------------------------------------------|
| edge_walk | Indicates an edge walking algorithm can be used. This algorithm requires nearly exact shape matching, so it should only be used when the shape is from a prior Valhalla route. |
| map_snap | Indicates that a map-matching algorithm should be used because the input shape might not closely match Valhalla edges. This algorithm is more expensive. |
| walk_or_snap | Also the default option. This will try edge walking and if this does not succeed, it will fall back and use map matching. |
## Attribute filters (trace_attributes only)
The trace_attributes action allows you to apply filters to include or exclude specific attribute filter keys in your response. These filters are optional and can be added to the action string inside of the filters object.
```
// Edge filter Keys
edge.names
edge.length # can also set source/target_percent_along
edge.speed
edge.speeds_faded
edge.speeds_non_faded
edge.road_class
edge.begin_heading
edge.end_heading
edge.begin_shape_index
edge.end_shape_index
edge.traversability
edge.use
edge.toll
edge.unpaved
edge.tunnel
edge.bridge
edge.roundabout
edge.internal_intersection
edge.drive_on_right
edge.surface
edge.sign.exit_number
edge.sign.exit_branch
edge.sign.exit_toward
edge.sign.exit_name
edge.travel_mode
edge.vehicle_type
edge.pedestrian_type
edge.bicycle_type
edge.transit_type
edge.id
edge.indoor
edge.way_id
edge.weighted_grade
edge.max_upward_grade
edge.max_downward_grade
edge.mean_elevation
edge.lane_count
edge.cycle_lane
edge.bicycle_network
edge.sac_scale
edge.shoulder
edge.sidewalk
edge.density
edge.speed_limit
edge.truck_speed
edge.truck_route
edge.country_crossing
edge.forward
edge.traffic_signal
// Node filter keys
node.intersecting_edge.begin_heading
node.intersecting_edge.from_edge_name_consistency
node.intersecting_edge.to_edge_name_consistency
node.intersecting_edge.driveability
node.intersecting_edge.cyclability
node.intersecting_edge.walkability
node.intersecting_edge.use
node.intersecting_edge.road_class
node.intersecting_edge.lane_count
node.elapsed_time
node.admin_index
node.type
node.traffic_signal
node.fork
node.time_zone
// Other filter keys
osm_changeset
shape
admin.country_code
admin.country_text
admin.state_code
admin.state_text
matched.point
matched.type
matched.edge_index
matched.begin_route_discontinuity
matched.end_route_discontinuity
matched.distance_along_edge
matched.distance_from_trace_point
```
## Edge items include:
| Item | Description |
|-----------------|-----------------------------------------------------------------------------|
| names | List of names |
| source | The start of an edge's matched percentage of its length (0, range if edge was fully matched; end of an edge's matched percentage of its length (0, range if edge was fully matched); we set value to percentage of its length in units specified (default is kilometers). If percentage is unavailable, we set value to -1. |
| target | The end of an edge's matched percentage of its length (0, range if edge was fully matched); we set value to percentage of its length in units specified (default is kilometers). If percentage is unavailable, we set value to -1. |
| length | The retrieved edge's length in the units specified (default is kilometers). If unavailable, we represent the partially matched length, otherwise full length percent. |
| speed | Edge's specified speed. The default is kilometers per hour. |
| from.type | Describes how the shape was assigned to the edge. Either it’s inferred from road class (default value) or set by the user. |
| speed.faded | Contains all speed values that are faded in the current time (if available). The current value fades with the flow rates when they are available. |
| speed.non_faded | Contains all flow rates when speed is available that the edge is not the units specified (default flow rates are in kilometers per hour). All flows are available when speed is available. |
| road_class | Road class value. |
| begin.heading | The direction at the beginning of the edge. The units are degrees from north in a clockwise direction. |
| end.heading | The direction at the end of the edge. The units are degrees from north in a clockwise direction. |
| begin_shape_index | Index of the list of shape points for the start of the edge. |
| end_shape_index | Index of the list of shape points for the end of the edge. |
| traversability | Traversability value, if available. |
| use | Use value. |
| toll | Toll value. |
| unpaved | Unpaved value. |
| tunnel | Tunnel value. |
| bridge | Bridge value. |
| roundabout | Roundabout value. |
| internal_intersection | Internal intersection value. |
| drive_on_right | Drive on right value. |
| surface | Surface value. |
| sign.exit_number | Sign exit number value. |
| sign.exit_branch | Sign exit branch value. |
| sign.exit_toward | Sign exit toward value. |
| sign.exit_name | Sign exit name value. |
| travel_mode | Travel mode value. |
| vehicle_type | Vehicle type value. |
| pedestrian_type | Pedestrian type value. |
| bicycle_type | Bicycle type value. |
| transit_type | Transit type value. |
| id | ID value. |
| indoor | Indoor value. |
| way_id | Way ID value. |
| weighted_grade | Weighted grade value. |
| max_upward_grade | Maximum upward grade value. |
| max_downward_grade | Maximum downward grade value. |
| mean_elevation | Mean elevation value. |
| lane_count | Lane count value. |
| cycle_lane | Cycle lane value. |
| bicycle_network | Bicycle network value. |
| sac_scale | SAC scale value. |
| shoulder | Shoulder value. |
| sidewalk | Sidewalk value. |
| density | Density value. |
| speed_limit | Speed limit value. |
| truck_speed | Truck speed value. |
| truck_route | Truck route value. |
| country_crossing | Country crossing value. |
| forward | Forward value. |
| traffic_signal | Traffic signal value. |
## Outputs of trace_attributes
The `trace_attributes` results contains a list of edges and, optionally, the following items: `osm_changeset`, list of `admins`, `shape`, `matched_points`, and `units`.
| Result item | Description |
|-----------------|--------------------------------------------------|
| edges | List of edges associated with input shape. See the list of edge items for details. |
| osm_changeset | Identifier of the OpenStreetMap base data version. |
| admins | List of the administrative codes and names. See the list of admin items for details. |
| shape | The encoded polyline of the matched path. |
| matched_points | List of match results when using the `map_snap` shape match algorithm. There is a one-to-one correspondence with the input set of latitude, longitude coordinates and this list of match results. See the list of matched point items for details. |
| units | The specified units with the request, in either kilometers or miles. |
| warnings | A warnings array. This array may contain descriptive text about notices of deprecated request parameters, clamped values etc. |
## trace_attributes with shape parameter
```json
{
"shape": [
{ "lat": 39.983841, "lon": -76.735741, "type": "break" },
{ "lat": 39.983704, "lon": -76.735298, "type": "via" },
{ "lat": 39.983578, "lon": -76.734848, "type": "via" },
{ "lat": 39.983551, "lon": -76.734253, "type": "break" },
{ "lat": 39.983555, "lon": -76.734116, "type": "via" },
{ "lat": 39.983589, "lon": -76.733315, "type": "via" },
{ "lat": 39.983719, "lon": -76.732445, "type": "via" },
{ "lat": 39.983818, "lon": -76.731712, "type": "via" },
{ "lat": 39.983776, "lon": -76.731506, "type": "via" },
{ "lat": 39.983696, "lon": -76.731369, "type": "break" }
],
"costing": "motor_scooter",
"shape_match": "walk_or_snap",
"filters": {
"attributes": [
"edge.names",
"edge.id",
"edge.weighted_grade",
"edge.speed"
],
"action": "include"
}
}
```
## trace_attributes with encoded polyline parameter
```json
{"shape":[{"lat":39.983841,"lon":-76.735741,"type":"break"},{"lat":39.983704,"lon":-76.735298,"type":"via"},{"lat":39.983578,"lon":-76.734848,"type":"via"},{"lat":39.983551,"lon":-76.734253,"type":"break"},{"lat":39.983555,"lon":-76.734116,"type":"via"},{"lat":39.983589,"lon":-76.733315,"type":"via"},{"lat":39.983719,"lon":-76.732445,"type":"via"},{"lat":39.983818,"lon":-76.731712,"type":"via"},{"lat":39.983776,"lon":-76.731506,"type":"via"},{"lat":39.983696,"lon":-76.731369,"type":"break"}],"encoded_polyline":"_grbgAh~{nhF?lBAzBFvBHxBEtBKdB?fB@dBZdBb@hBh@jBb@x@\\|@x@pB\\x@v@hBl@nBPbCXtBn@|@z@ZbAEbAa@~@q@z@QhA]pAUpAVhAPlAWtASpAAdA[dASdAQhAIlARjANnAZhAf@n@`A?lB^nCRbA\\xB`@vBf@tBTbCFbARzBZvBThBRnBNrBP`CHbCF`CNdCb@vBX`ARlAJfADhA@dAFdAP`AR`Ah@hBd@bBl@rBV|B?vB]tBCvBBhAF`CFnBXtAVxAVpAVtAb@|AZ`Bd@~BJfA@fAHdADhADhABjAGzAInAAjAB|BNbCR|BTjBZtB`@lBh@lB\\|Bl@rBXtBN`Al@g@t@?nAA~AKvACvAAlAMdAU`Ac@hAShAI`AJ`AIdAi@bAu@|@k@p@]p@a@bAc@z@g@~@Ot@Bz@f@X`BFtBXdCLbAf@zBh@fBb@xAb@nATjAKjAW`BI|AEpAHjAPdAAfAGdAFjAv@p@XlAVnA?~A?jAInAPtAVxAXnAf@tBDpBJpBXhBJfBDpAZ|Ax@pAz@h@~@lA|@bAnAd@hAj@tAR~AKxAc@xAShA]hAIdAAjA]~A[v@BhB?dBSv@Ct@CvAI~@Oz@Pv@dAz@lAj@~A^`B^|AXvAVpAXdBh@~Ap@fCh@hB\\zBN`Aj@xBFdA@jALbAPbAJdAHdAJbAHbAHfAJhALbA\\lBTvBAdC@bC@jCKjASbC?`CM`CDpB\\xAj@tB\\fA\\bAVfAJdAJbAXz@L|BO`AOdCDdA@~B\\z@l@v@l@v@l@r@j@t@b@x@b@r@z@jBVfCJdAJdANbCPfCF|BRhBS~BS`AYbAe@~BQdA","shape_match":"map_snap","costing":"pedestrian","directions_options":{"units":"miles"}}
```
## trace_attributes with include attribute filter
```json
{
"shape":[{"lat":39.983841,"lon":-76.735741},{"lat":39.983704,"lon":-76.735298},{"lat":39.983578,"lon":-76.734848},{"lat":39.983551,"lon":-76.734253},{"lat":39.983555,"lon":-76.734116},{"lat":39.983589,"lon":-76.733315},{"lat":39.983719,"lon":-76.732445},{"lat":39.983818,"lon":-76.731712},{"lat":39.983776,"lon":-76.731506},{"lat":39.983696,"lon":-76.731369}],"costing":"auto","shape_match":"walk_or_snap","filters":{"attributes":["edge.names","edge.id", "edge.weighted_grade","edge.speed"],"action":"include"}
}
```
## trace_attributes with exclude attribute filter
```json
{"shape":[{"lat":39.983841,"lon":-76.735741},{"lat":39.983704,"lon":-76.735298},{"lat":39.983578,"lon":-76.734848},{"lat":39.983551,"lon":-76.734253},{"lat":39.983555,"lon":-76.734116},{"lat":39.983589,"lon":-76.733315},{"lat":39.983719,"lon":-76.732445},{"lat":39.983818,"lon":-76.731712},{"lat":39.983776,"lon":-76.731506},{"lat":39.983696,"lon":-76.731369}],"costing":"auto","shape_match":"walk_or_snap","filters":{"attributes":["edge.names","edge.begin_shape_index","edge.end_shape_index","shape"],"action":"exclude"}}
```
---
# Matrix Service
https://docs.mapatlas.xyz/overview/directions/matrix
# Matrix Service
The time distance matrix service takes a sources and targets to list locations. This allows you to set the source (origin) locations separately from the target (destination) locations. The set of origins may be disjoint (not overlapping) with the set of destinations. In other words, the target locations do not have to include any locations from source locations. The time-distance matrix can return a row matrix, a column matrix, or a general matrix of computed time and distance, depending on your input for the sources and targets parameters. The general case is a row ordered matrix with the time and distance from each source location to each target location. A row vector is considered a one_to_many time-distance matrix where there is one source location and multiple target locations. The time and distance from the source location to all target locations is returned. A column matrix represents a many_to_one time-distance matrix where there are many sources and one target. Another special case is when the source location list is the same as the target location list. Here, a diagonal (square matrix with [0,0.00] on the diagonal elements) matrix is returned. The is special case is often used as the input to optimized routing problems.
## Required Parameters
- **Query Param**:
- `token` → Required /matrix/?token=YOUR_TOKEN (Authorization, otherwise `401 Token required` error will occur)
- **Body JSON**:
- `sources` → Required (List of source coordinates)
- `targets` → Optional (List of target coordinates, defaults to sources if omitted)
- `costing` → Required (Travel mode, e.g. `pedestrian`, `auto`, `bicycle`)
---
## Examples (Copy & Paste)
## One-to-Many
```json
{ "sources": [ { "lat": 40.744014, "lon": -73.990508 } ], "targets": [ { "lat": 40.744014, "lon": -73.990508 }, { "lat": 40.739735, "lon": -73.979713 }, { "lat": 40.752522, "lon": -73.985015 }, { "lat": 40.750117, "lon": -73.983704 }, { "lat": 40.750552, "lon": -73.993519 } ], "costing": "pedestrian" }
```
## Many-to-One
```json
{ "sources": [ { "lat": 40.744014, "lon": -73.990508 }, { "lat": 40.739735, "lon": -73.979713 }, { "lat": 40.752522, "lon": -73.985015 }, { "lat": 40.750117, "lon": -73.983704 }, { "lat": 40.750552, "lon": -73.993519 } ], "targets": [ { "lat": 40.750552, "lon": -73.993519 } ], "costing": "pedestrian" }
```
## Many-to-Many
```json
{ "sources": [ { "lat": 40.744014, "lon": -73.990508 }, { "lat": 40.739735, "lon": -73.979713 }, { "lat": 40.752522, "lon": -73.985015 }, { "lat": 40.750117, "lon": -73.983704 }, { "lat": 40.750552, "lon": -73.993519 } ], "targets": [ { "lat": 40.744014, "lon": -73.990508 }, { "lat": 40.739735, "lon": -73.979713 }, { "lat": 40.752522, "lon": -73.985015 }, { "lat": 40.750117, "lon": -73.983704 }, { "lat": 40.750552, "lon": -73.993519 } ], "costing": "pedestrian" }
```
# Costing parameter
The Time-Distance Matrix service uses the auto, bicycle, pedestrian and bikeshare and other costing models available in the route service. Exception: multimodal costing is not supported for the time-distance matrix service at this time.
## Other Request Option
| Option | Description |
|-----------------|-------------|
| **verbose** | If `true`, it will output a flat list of objects for `distances` & `durations` explicitly specifying the source & target indices. If `false`, will return more compact, nested row-major `distances` & `durations` arrays and not echo `sources` and `targets`.
**Default:** `true`. |
| **shape_format** | Specifies the optional format for the path shape of each connection. One of `polyline6`, `polyline5`, `geojson`, or `no_shape` (default). |
---
## Outputs of the matrix service
Depending on the `verbose` (default: `true`) request parameter, the result of the Time-Distance Matrix service is different. In both (`"verbose": true` and `"verbose": false`) cases, these parameters are present:
| Item | Description |
|--------------|-----------------------------------------------------------------------------|
| `algorithm` | The algorithm used to compute the results. Can be `"timedistancematrix"`, `"costmatrix"`, or `"timedistancebssmatrix"`. |
| `units` | Distance units for output. Allowable unit types are `"miles"` and `"kilometers"`. If no unit type is specified in the input, the units default to `"kilometers"`. |
| `warnings` (optional) | This array may contain warning objects informing about deprecated request parameters, clamped values etc. |
# Verbose mode ("verbose": true)
The following parameters are only present in "verbose": true mode:
| Item | Description |
|-----------------|--------------------------------------------------|
| sources | The sources passed to the request. |
| targets | The targets passed to the request. |
| sources_to_targets | An array of time and distance between the sources and the targets. The array is row-ordered, meaning the time and distance from the first location to all others forms the first row of the array, followed by the time and distance from the second source location to all target locations, etc. The Object contained in the arrays contains the following fields:
distance: The computed distance between each set of points. Distance will always be 0.00 for the first element of the time-distance array for one_to_many, the last element in a many_to_one, and the first and last elements of a many_to_many.time: The computed time between each set of points. Time will always be 0 for the first element of the time-distance array for one_to_many, the last element in a many_to_one, and the first and last elements of a many_to_many.to_index: The destination index into the locations array.from_index: The origin index into the locations array. When a user will arrive at/depart from this location. See the part above where we explain how time dependent matrices work for further context. Note: If the time is above the setting
max_time_dep_distance_matrix this is skipped. |
## Concise mode ("verbose": false)
| Item | Description |
|-----------------|--------------------------------------------------|
| sources_to_target | Returns an object with durations and distances as row-ordered contents of the values above. |
---
## Example Response (Verbose Mode)
```json
{
"sources": [
{"lat": 40.744014, "lon": -73.990508},
{"lat": 40.739735, "lon": -73.979713}
],
"targets": [
{"lat": 40.752522, "lon": -73.985015},
{"lat": 40.750117, "lon": -73.983704},
{"lat": 40.750552, "lon": -73.993519}
],
"sources_to_targets": [
[
{
"distance": 1.342,
"time": 294,
"to_index": 0,
"from_index": 0
},
{
"distance": 0.987,
"time": 215,
"to_index": 1,
"from_index": 0
},
{
"distance": 0.532,
"time": 142,
"to_index": 2,
"from_index": 0
}
],
[
{
"distance": 2.134,
"time": 412,
"to_index": 0,
"from_index": 1
},
{
"distance": 1.876,
"time": 387,
"to_index": 1,
"from_index": 1
},
{
"distance": 2.245,
"time": 456,
"to_index": 2,
"from_index": 1
}
]
],
"units": "kilometers",
"algorithm": "timedistancematrix"
}
```
## Example Response (Concise Mode - verbose: false)
```json
{
"sources_to_targets": {
"durations": [
[294, 215, 142],
[412, 387, 456]
],
"distances": [
[1.342, 0.987, 0.532],
[2.134, 1.876, 2.245]
]
},
"units": "kilometers",
"algorithm": "timedistancematrix"
}
```
---
# Optimization
https://docs.mapatlas.xyz/overview/directions/optimization
# Optimization
The Optimized Route service provides a quick computation of time and distance between a set of location sources and location targets and returns them in an optimized route order, along with the shape.
# Inputs of the optimized route
The optimized route request run locally takes the form of json={}, where the JSON inputs inside the {} includes location information (at least four locations), as well as the name and options for the costing model
Here is an example of an Optimized Route scenario:
Given a list of cities and the distances and times between each pair, a salesperson wants to visit each city one time by taking the most optimized route and end at a destination (either return to origin or a different destination)
```json
{ "locations": [ { "lat": 40.042072, "lon": -76.306572 }, { "lat": 39.992115, "lon": -76.781559 }, { "lat": 39.984519, "lon": -76.695600 }, { "lat": 39.996586, "lon": -76.769028 }, { "lat": 39.984322, "lon": -76.706672 } ], "costing": "auto", "units": "miles" }
```
| Parameter | Location | Required | Description |
| ------------- | ----------- | -------- | --------------------------------------------------------------------------------------- |
| **token** | Query Param | ✅ Yes | API authentication token. Required, otherwise the API will return `401 Token required`. |
| **locations** | Body JSON | ✅ Yes | Array of coordinates (`lat`, `lon`). **At least 2 locations must be provided**. |
| **costing** | Body JSON | ✅ Yes | Travel mode. Options: `auto`, `pedestrian`, `bicycle`. |
| **units** | Body JSON | ❌ No | Distance units. Options: `miles` (default) or `kilometers`. |
# Outputs of the optimized route service
These are the results of a request to the Optimized Route service.
| Item | Description |
|-----------------|-----------------------------------------------------------------------------|
| optimized_route | Returns an optimized route path from point 'a' to point 'n'. Given a list of locations, an optimized route with stops at each intermediate location exactly one time, always starting at the first location in the list and ending at the last location. |
| locations | The specified array of lat/lngs from the input request. The first and last locations in the array will remain the same as the input request. The intermediate locations may be returned reordered in the response. Due to the reordering of the intermediate locations, an `original_index` is also part of the `locations` object within the response. This is an identifier of the location index that will allow a user to easily correlate input locations with output locations. |
| units | Distance units for output. Allowable unit types are mi (miles) and km (kilometers). If no unit type is specified, the units default to kilometers. |
| warnings (optional) | This array may contain warning objects informing about deprecated request parameters, clamped values etc. |
---
## Example Response
```json
{
"optimized_route": [
{
"trip": {
"locations": [
{
"type": "break",
"lat": 40.042072,
"lon": -76.306572,
"original_index": 0
},
{
"type": "break",
"lat": 39.984519,
"lon": -76.695600,
"original_index": 2
},
{
"type": "break",
"lat": 39.984322,
"lon": -76.706672,
"original_index": 4
},
{
"type": "break",
"lat": 39.996586,
"lon": -76.769028,
"original_index": 3
},
{
"type": "break",
"lat": 39.992115,
"lon": -76.781559,
"original_index": 1
}
],
"legs": [
{
"summary": {
"time": 2156.785,
"length": 41.812,
"cost": 2156.785
},
"shape": "encoded_polyline_string_here"
}
],
"summary": {
"time": 2156.785,
"length": 41.812,
"cost": 2156.785
},
"status_message": "Found route between points",
"status": 0,
"units": "miles",
"language": "en-US"
}
}
],
"units": "miles"
}
```
**Note:** The `locations` array shows the optimized order of stops. Use the `original_index` field to map back to your input locations.
---
# Autocomplete Endpoint
https://docs.mapatlas.xyz/overview/geocoder/autocomplete
# Autocomplete Endpoint
::: danger Deprecated — do not use for new development
This is the **v1** autocomplete endpoint. It is still served and existing
integrations keep working, but it is no longer the recommended API and will
not receive new features.
**For anything new, use [v2](/overview/geocoder/v2/autocomplete).** v2 adds session-based billing
(materially cheaper for as-you-type search), richer results, and a
[suggest → retrieve](/overview/geocoder/v2/retrieve) flow.
The easiest path is one of the
[geocoding SDKs](/overview/sdk/geocoding/), which handle sessions, debouncing
and error typing for you.
:::
The **Autocomplete API** provides instant place and address suggestions
based on partial user input. It is typically used in search boxes where
results update in real time.
## How it Works
- Send a **partial query** (`text`) such as `"YMCA"`.
- The API returns a **list of matching places** (venues, streets, cities, etc.)
with coordinates and metadata.
- You can restrict search by location using **boundary parameters**.
- **Important:** You must include a valid `token` parameter in the request.
If missing or invalid, the API will return `401 Token required`.
## Endpoint
```
GET https://gateway.mapmetrics-atlas.net/autocomplete/
```
## Parameters
# Search API Parameters
| Parameter | Type | Req | Example | Description |
|---------------------------|--------------------------|-----|---------------------|-----------------------------------------------------------------------------|
| `text` | string | ✅ | `Union Square` | The search query text. |
| `token` | string (auth token) | ✅ | `abcd1234` | Required authentication token, otherwise request returns `401 Token required`. |
| `focus.point.lat` | float | ❌ | `48.581755` | Latitude for search focus. |
| `focus.point.lon` | float | ❌ | `7.745843` | Longitude for search focus. |
| `boundary.rect.min_lon` | float | ❌ | `139.2794` | Minimum longitude of bounding box. |
| `boundary.rect.max_lon` | float | ❌ | `140.1471` | Maximum longitude of bounding box. |
| `boundary.rect.min_lat` | float | ❌ | `35.53308` | Minimum latitude of bounding box. |
| `boundary.rect.max_lat` | float | ❌ | `35.81346` | Maximum latitude of bounding box. |
| `boundary.circle.lat` | float | ❌ | `43.818156` | Circle boundary center latitude. |
| `boundary.circle.lon` | float | ❌ | `-79.186484` | Circle boundary center longitude. |
| `boundary.circle.radius` | float | ❌ | `35` | Circle radius (in kilometers). |
| `sources` | string (comma-separated) | ❌ | `openstreetmap,wof` | Data sources to include. |
| `layers` | string (comma-separated) | ❌ | `address,venue` | Feature layers to include. |
| `boundary.country` | string (comma-separated) | ❌ | `GBR,FRA` | ISO country codes to limit search. |
| `boundary.gid` | Pelias `gid` | ❌ | `whosonfirst:locality:101748355` | Restrict results to a specific boundary by gid. |
| `size` | integer | ❌ | `20` | Number of results to return. |
## Example
```bash
GET https://gateway.mapmetrics-atlas.net/autocomplete/?text=YMCA&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35&token=YOUR_API_KEY
```
## Example Response
```json
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-78.861037, 43.900526]
},
"properties": {
"name": "Durham Family YMCA",
"country": "Canada",
"region": "Ontario",
"locality": "Oshawa",
"label": "Durham Family YMCA, Oshawa, ON, Canada"
}
}
]
}
```
---
# Forward Geocode
https://docs.mapatlas.xyz/overview/geocoder/forwardgeocode
# Forward Geocode
::: danger Deprecated — do not use for new development
This is the **v1** forward geocoding endpoint. It is still served and existing
integrations keep working, but it is no longer the recommended API and will
not receive new features.
**For anything new, use [v2](/overview/geocoder/v2/forwardgeocode).** v2 adds session-based billing
(materially cheaper for as-you-type search), richer results, and a
[suggest → retrieve](/overview/geocoder/v2/retrieve) flow.
The easiest path is one of the
[geocoding SDKs](/overview/sdk/geocoding/), which handle sessions, debouncing
and error typing for you.
:::
Geocoding is the process of matching an address or other text to its corresponding geographic coordinates.
## Search the world
In the simplest search, you can provide only one parameter, the text you want to match in any part of the location details. To do this, build a query where the text parameter is set to the item you want to find.
For example, if you want to find a YMCA facility, here's what you'd need to append to the base URL of the service.
# Note the parameter values are set as follows:
| parameter | value |
|-----------|-------|
|`token` |*string|
| text | YMCA |
In the example above, you will find the name of each matched locations in a property named `'label'`. The top 10 labels returned at the time of writing were:
- YMCA, Bargoed Community, United Kingdom
- YMCA, Nunspeet, Gelderland
- YMCA, Belleville, IL
- YMCA, Forest City, IA
- YMCA, Fargo, ND
- YMCA, Taipei, Taipei City
- YMCA, Orpington, Greater London
- YMCA, Frisco, TX
- YMCA, Jefferson, OH
- YMCA, Belleville, IL
Spelling matters, but not capitalization. You can type `ymca`, `YMCA`, or even `yMcA`. See for yourself by comparing the results of the earlier search to the following:
[/forward-geocode/?token=YOUR_TOKEN&text=ymcA](https://gateway.mapmetrics-atlas.net/forward-geocode/?token=YOUR_TOKEN&text=ymcA)
Note that the results are spread out throughout the world because you have not given your current location or provided any other geographic context in which to search.
## Set the number of results returned
By default, returns up to 10 results. If you want a different number, set the size parameter to the desired number. This example shows returning only the first result.
| parameter | value |
|-----------|-------|
|`token` |*string|
| text | YMCA |
| size | 1 |
If you want 25 results, you can build the query where size is 25.
## Narrow your search
If you are looking for places in a particular region, or country, or only want to look in the immediate vicinity of a user with a known location, you can narrow your search to an area. There are different ways of including a region in your query. we supports three types: country, rectangle, and circle.
Sometimes your work might require that all the search results be from a particular country or a list of countries. To do this, you can set the boundary.country parameter value to a comma separated list of alpha-2 or alpha-3 ISO-3166 country code.
Now, you want to search for YMCA again, but this time only in Great Britain. To do this, you will need to know that the alpha-3 code for Great Britain is GBR and set the parameters like this:
[/forward-geocode/?token=YOUR_TOKEN&text=YMCA&boundary.country=GBR](https://gateway.mapmetrics-atlas.net/forward-geocode/?token=YOUR_TOKEN&text=YMCA&boundary.country=GBR)
| parameter | value |
| :--- | :--- |
| `token` |*string|
| `text` | YMCA |
| `boundary.country` | GBR |
Note that all the results are within Great Britain:
* YMCA, Bargoed Community, United Kingdom
* YMCA, Orpington, Greater London
* YMCA, Erdington, West Midlands
* YMCA, Malvern CP, United Kingdom
* YMCA, Ancoats, Greater Manchester
* YMCA, Carmarthen Community, United Kingdom
* YMCA, Halebank, Cheshire
* YMCA, Brightlingsea CP, United Kingdom
* YMCA, Lenton Abbey, Nottinghamshire
* YMCA, Old Clee, Lincolnshire
If you try the same search request with different country codes, the results change to show YMCA locations within this region.
Results in the United States:
* YMCA, Belleville, IL
* YMCA, Forest City, IA
* YMCA, Fargo, ND
* YMCA, Frisco, TX
* YMCA, Jefferson, OH
* YMCA, Belleville, IL
* YMCA, Chapel Hill, NC
* YMCA, West Lampeter, PA
* YMCA, Bremerton, WA
* YMCA, Westerly, RI
## Search within a rectangular region
To specify the boundary using a rectangle, you need latitude, longitude coordinates for two diagonals of the bounding box (the minimum and the maximum latitude, longitude).
For example, to find a YMCA within the state of Texas, you can set the `boundary.rect.*` parameter to values representing the bounding box around Texas: min_lon=-106.65 min_lat=25.84 max_lon=-93.51 max_lat=36.5
[/forward-geocode/?token=YOUR_TOKEN&text=YMCA&boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51]
| parameter | value |
| :--- | :--- |
| `token` |*string|
| `text` | YMCA |
| `boundary.rect.min_lat` | 25.84 |
| `boundary.rect.min_lon` | -106.65 |
| `boundary.rect.max_lat` | 36.5 |
| `boundary.rect.max_lon` | -93.51 |
* YMCA, Austin, TX
* YMCA, Frisco, TX
* Y.M.C.A, Fort Worth, TX
* YMCA, Rockwall, TX
* YMCA, Missouri City, TX
* YMCA, Northshore, TX
* YMCA, Austin, TX
* YMCA, Tulsa, OK
* YMCA, Los Alamos, NM
* YMCA, Tulsa, OK
## Search within a circular region
Sometimes you don't have a rectangle to work with, but rather you have a point on earth—for example, your location coordinates—and a maximum distance within which acceptable results can be located.
In this example, you want to find all YMCA locations within a 35-kilometer radius of a location in Ontario, Canada. This time, you can use the `boundary.circle.*` parameter group, where `boundary.circle.lat` and `boundary.circle.lon` is your location in Ontario and `boundary.circle.radius` is the acceptable distance from that location. Note that the `boundary.circle.radius` parameter is always specified in kilometers.
[/forward-geocode/?token=YOUR_TOKEN&text=YMCA&boundary.circle.lat=43.818156&boundary.circle.lon=-79.186484&boundary.circle.radius=35]
| parameter | value |
| :--- | :--- |
| `token` |*string|
| `text` | YMCA |
| `boundary.circle.lat` | 43.818156 |
| `boundary.circle.lon` | -79.186484 |
| `boundary.circle.radius` | 35 |
You can see the results have fewer than the standard 10 items because there are not that many YMCA locations in the specified radius:
* YMCA, Toronto, Ontario
* YMCA, Markham, Ontario
* YMCA, Toronto, Ontario
* Metro Central YMCA, Toronto, Ontario
* Pinnacle Jr YMCA, Toronto, Ontario
* Cooper Koo Family Cherry Street YMCA Centre, Toronto, Ontario
## Search within a parent administrative area
forward-geocode has a powerful understanding of relationships between places. In particular, it has a concept called the administrative hierarchy: each record in our map is listed as belonging to a parent neighbourhood, city, region, country, and other regions. This has many uses, including filtering. The map global id (gid) of any record can be used with the boundary.gid filter to return only records with a given parent.
For example, finding YMCAs in [Oklahoma](https://en.wikipedia.org/wiki/Oklahoma) with only a bounding box would be challenging: the bounding box would include much of nearby Texas, possibly leading to incorrect results.
With `boundary.gid`, this query can return accurate results.
[/v1/search?text=YMCA&__boundary.gid=whosonfirst:region:85688585__](http://pelias.github.io/compare/#/v1/search%3Fboundary.gid=whosonfirst:region:85688585&text=ymca)
* YMCA, Stillwater, OK, USA
* YMCA, Edmond, OK, USA
* YMCA, Guymon, OK, USA
* YMCA, Grove, OK, USA
* YMCA, Midwest City, OK, USA
* YMCA, Shawnee, OK, USA
* YMCA, Owasso, OK, USA
* YMCA, Tulsa, OK, USA
* YMCA, The Village, OK, USA
* YMCA, Broken Arrow, OK, USA
By specifying a `focus.point`, results will be sorted in part by their proximity to the given coordinate. All else being equal, results closest to the point will show up higher. However, unlike a `boundary.circle` query, important results far from the given coordinate may still be returned. This allows.
To find YMCAs again, but this time near a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia, use `focus.point`.
[/forward-geocode/?token=YOUR_TOKEN&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281]
| parameter | value |
| :--- | :--- |
| `token`| *string |
| `text` | YMCA |
| `focus.point.lat` | -33.856680 |
| `focus.point.lon` | 151.215281 |
Looking at the results, you can see that the few locations closer to this location show up at the top of the list, sorted by distance. You also still get back a significant amount of remote locations, for a well balanced mix. Because you provided a focus point, we can compute distance from that point for each resulting feature.
* YMCA, Redfern, New South Wales [distance: 3.836]
* YMCA, St Ives (NSW), New South Wales [distance: 14.844]
* YMCA, Epping (NSW), New South Wales [distance: 16.583]
* YMCA, Revesby, New South Wales [distance: 21.335]
* YMCA, Kochâang, South Gyeongsang [distance: 8071.436]
* YMCA, Center, IN [distance: 14882.675]
* YMCA, Lake Villa, IL [distance: 14847.667]
* YMCA, Onondaga, NY [distance: 15818.08]
* YMCA, 's-Gravenhage, Zuid-Holland [distance: 16688.292]
* YMCA, Loughborough, United Kingdom [distance: 16978.367]
## Prioritize around a point
| parameter | value |
| :--- | :--- |
| `token`| *string |
| `text` | YMCA |
| `focus.point.lat` | -33.856680 |
| `focus.point.lon` | 151.215281 |
| `boundary.country` | AUS |
The results below look different from the ones you saw before with only a focus point specified. These results are all from within Australia. You'll note the closest results show up at the top of the list, which is helped by the focus parameter.
* YMCA, Redfern, New South Wales [distance: 3.836]
* YMCA, St Ives (NSW), New South Wales [distance: 14.844]
* YMCA, Epping (NSW), New South Wales [distance: 16.583]
* YMCA, Revesby, New South Wales [distance: 21.335]
* YMCA, Larrakeyah, Northern Territory [distance: 3144.296]
* YMCA, Kepnock, Queensland [distance: 1001.657]
* YMCA, Kings Meadows, Tasmania [distance: 917.144]
* YMCA, Katherine East, Northern Territory [distance: 2873.376]
* YMCA, Sadadeen, Northern Territory [distance: 2026.731]
* YMCA, Ararat, Victoria [distance: 841.022]
## Prioritize within a circular region
| parameter | value |
| :--- | :--- |
| `token`| *string |
| `text` | YMCA |
| `focus.point.lat` | -33.856680 |
| `focus.point.lon` | 151.215281 |
| `boundary.circle.lat` | -33.856680 |
| `boundary.circle.lon` | 151.215281 |
| `boundary.circle.radius` | 50 |
Looking at these results, they are all less than 50 kilometers away from the focus point:
* YMCA, Redfern, New South Wales [distance: 3.836]
* YMCA, St Ives (NSW), New South Wales [distance: 14.844]
* YMCA, Epping (NSW), New South Wales [distance: 16.583]
* YMCA, Revesby, New South Wales [distance: 21.335]
* Caringbah YMCA, Caringbah, New South Wales [distance: 22.543]
* YMCA building, Loftus, New South Wales [distance: 25.756]
## Filter by data source
The search examples so far have returned a mix of results from all the data sources available to Pelias. Here are the sources being searched:
| source | name | short name |
|---|---|---|
| [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` |
| [OpenAddresses](http://openaddresses.io/) | `openaddresses` | `oa` |
| [Who's on First](https://whosonfirst.org) | `whosonfirst` | `wof` |
| [GeoNames](http://www.geonames.org/) | `geonames` | `gn` |
| parameter | value |
| :--- | :--- |
| `token`| *string |
| `text` | YMCA |
| `sources` | oa |
Because OpenAddresses is, as the name suggests, only address data, here's what you can expect to find:
* 20 Ymca Drive, Niagara, ON, Canada
* 341 Ymca Rd, New Hope, AL, USA
* 318 Ymca Rd, New Hope, AL, USA
* 138 Ymca Rd, New Hope, AL, USA
* 304 Ymca Rd, New Hope, AL, USA
* 1919 Ymca Lane, Minnetonka, MN, USA
* 101 Ymca Dr, Kannapolis, NC, USA
* 2121 Ymca Camp Road, Stokes County, NC, USA
* 1110 Ymca Camp Road, Stokes County, NC, USA
* 1581 Ymca Camp Road, Stokes County, NC, USA
## Filters by data type
Here's a list of the types of places you could find in the results, sorted by granularity:
|layer|description|
|----|----|
|`venue`|points of interest, businesses, things with walls|
|`address`|places with a street address|
|`street`|streets,roads,highways|
|`neighbourhood`|social communities, neighbourhoods|
|`borough`|a local administrative boundary, currently only used for New York City|
|`localadmin`|local administrative boundaries|
|`locality`|towns, hamlets, cities|
|`county`|official governmental area; usually bigger than a locality, almost always smaller than a region|
|`macrocounty`|a related group of counties. Mostly in Europe.|
|`region`|states and provinces|
|`macroregion`|a related group of regions. Mostly in Europe|
|`country`|places that issue passports, nations, nation-states|
|`coarse`|alias for simultaneously using all administrative layers (everything except `venue` and `address`)|
[/forward-geocode/?token=YOUR_TOKEN&text=YMCA&layers=street,venue]
## Available search parameters
| Parameter | Type | Required | Default | Example |
| --- | --- | --- | --- | --- |
| `token`| *string |yes|---|---|
| `text` | string | yes | none | `Union Square` |
| `focus.point.lat` | floating point number | no | none | `48.581755` |
| `focus.point.lon` | floating point number | no | none | `7.745843` |
| `boundary.rect.min_lon` | floating point number | no | none | `139.2794` |
| `boundary.rect.max_lon` | floating point number | no | none | `140.1471` |
| `boundary.rect.min_lat` | floating point number | no | none | `35.53308` |
| `boundary.rect.max_lat` | floating point number | no | none | `35.81346` |
| `boundary.circle.lat` | floating point number | no | none | `43.818156` |
| `boundary.circle.lon` | floating point number | no | none | `-79.186484` |
| `boundary.circle.radius` | floating point number | no | 50 | `35` |
| `boundary.gid` | Pelias `gid` | no | none | `whosonfirst:locality:101748355` |
| `sources` | string | no | all sources: osm,oa,gn,wof | openstreetmap,wof |
| `layers` | string | no | all layers: address,venue,neighbourhood,locality,borough,localadmin,county,macrocounty,region,macroregion,country,coarse,postalcode | address,venue |
| `boundary.country` | string | no | none | `GBR,FRA` |
| `size` | integer | no | 10 | 20 |
---
# OSM Tier Endpoints
https://docs.mapatlas.xyz/overview/geocoder/osm
---
title: OSM Tier Endpoints
description: The free OpenStreetMap-only geocoding tier — response shapes, why it needs no retrieve step, and the two gotchas its responses hide.
---
# OSM Tier Endpoints
The **OSM tier** is a free, OpenStreetMap-only geocoder reached through the
`osm-geocode` scope. It is a different engine from the [v2
geocoder](./v2/autocomplete.md), with a different response shape and a
different cost model, and the differences are easy to trip over when porting
code between the two.
| | [v2 tier](./v2/autocomplete.md) | OSM tier |
|---|---|---|
| Endpoints | `/v2/autocomplete/`, `/v2/retrieve/`, … | `/osm-autocomplete/`, `/osm-geocode/`, `/osm-reverse/` |
| Sessions | yes — billed per session | **none** |
| Coordinates in suggestions | no — must call `/v2/retrieve/` | **yes, inline** |
| Billing | per session | per request, rate-limited |
Rate limit: 10,000 requests per key per day, plus a global monthly cap.
Exhausting it returns a quota error carrying a self-host URL — the engine is
open source at
[MapMetrics/atlas-osm-geocoder](https://github.com/MapMetrics/atlas-osm-geocoder).
## No retrieve step
The single biggest structural difference: **OSM-tier suggestions already
carry coordinates.** Every row from `/osm-autocomplete/` has a `center` and a
`geometry`, so there is no suggest → retrieve round trip and no session token
to thread through.
```bash
curl "https://gateway.mapmetrics-atlas.net/osm-autocomplete/?q=amsterdam&token=YOUR_API_KEY"
```
```json
{
"type": "FeatureCollection",
"query": "amsterdam",
"query_ms": 12,
"results": [
{
"id": "poi.0",
"type": "Feature",
"place_type": ["poi"],
"relevance": 1.0,
"text": "Amsterdam Museum",
"place_name": "Amsterdam Museum, NL",
"center": [4.891, 52.3704],
"geometry": { "type": "Point", "coordinates": [4.891, 52.3704] },
"context": [{ "id": "country.nl", "text": "NL", "short_code": "nl" }],
"properties": { "layer": "poi", "popularity": 7043 },
"matching_text": "Amsterdam",
"matching_place_name": "Amsterdam"
}
],
"attribution": "© OpenStreetMap contributors, MapMetrics Atlas"
}
```
Porting v2 code here means deleting the retrieve call, not rewriting it. In
the [geocoding SDKs](/overview/sdk/geocoding/) this shows up as
`createSession()` throwing on the OSM tier, with `autocomplete()` available
in its place.
## `results` vs `features` — the key differs by endpoint
::: danger The rows are not always under the same key
`/osm-autocomplete/` returns its rows under **`results`**.
`/osm-geocode/` returns them under **`features`**. Some worker builds emit
both keys with the same content. Reading only one of them yields an empty
list against the other endpoint — with no error, because HTTP 200 and a
well-formed envelope came back either way.
:::
Read defensively:
```js
const rows = body.results ?? body.features ?? [];
```
Both envelopes otherwise agree: `type: "FeatureCollection"`, a `query` echo,
`query_ms`, and an `attribution` string.
## `id` is not unique here either
Exactly as on [v2](./v2/autocomplete.md#id-is-not-unique-within-a-response),
`id` collides within a single response — and on this tier it collides across
genuinely different places. `q=amsterdam` currently returns `"id": "poi.0"`
for both *Amsterdam Museum* and *Amsterdam Oosterpark Inn*.
Do not use `id` as a list key. It is opaque debug metadata, not a
primary key.
## Sub-paths are ignored, not routed
::: warning `/osm-geocode/anything/` returns the same free-text results
The gateway matches on the `/osm-geocode/` **prefix** and ignores whatever
follows. `/osm-geocode/`, `/osm-geocode/category/` and `/osm-geocode/banana/`
all return HTTP 200 with byte-identical free-text results.
There is no sub-path API here. A URL like `/osm-geocode/category/` looks like
a category endpoint and behaves like an ordinary search, so a typo or an
invented path silently returns plausible, wrong data instead of a 404. Only
the paths listed on this page mean anything.
:::
For real category filtering, see [Category Search](./v2/category.md) on the
v2 tier.
## Self-hosting
A self-hosted [atlas-osm-geocoder](https://github.com/MapMetrics/atlas-osm-geocoder)
instance uses **different paths and no token**: `/search`, `/reverse`,
`/autocomplete`, with no `/osm-` prefix and no `token` parameter. Every SDK
exposes this as a distinct `selfHosted()` constructor that never sends a
credential.
## See Also
- [Category Search (v2)](./v2/category.md) — the only endpoint that filters by category.
- [Autocomplete (v2)](./v2/autocomplete.md) — the session-billed tier.
- [Geocoding SDKs](/overview/sdk/geocoding/) — all four wrap both tiers behind one API.
---
# Reverse Geocoding API
https://docs.mapatlas.xyz/overview/geocoder/reversegeocode
# Reverse Geocoding API
::: danger Deprecated — do not use for new development
This is the **v1** reverse geocoding endpoint. It is still served and existing
integrations keep working, but it is no longer the recommended API and will
not receive new features.
**For anything new, use [v2](/overview/geocoder/v2/reversegeocode).** v2 adds session-based billing
(materially cheaper for as-you-type search), richer results, and a
[suggest → retrieve](/overview/geocoder/v2/retrieve) flow.
The easiest path is one of the
[geocoding SDKs](/overview/sdk/geocoding/), which handle sessions, debouncing
and error typing for you.
:::
The Reverse Geocoding API takes a **latitude/longitude point** and returns the closest address or place.
| Parameter | Type | Req | Example | Description |
| ------------------------ | ------------------------ | --- |--------------------------------|---------------------------------------------------------------------------- |
| `point.lat` | float | ✅ | `48.858268` | Latitude of the point to reverse geocode. |
| `point.lon` | float | ✅ | `2.294471` | Longitude of the point to reverse geocode. |
| `token` | string (auth token) | ✅ | `abcd1234` | Required authentication token, otherwise request returns `401 Token required`.|
| `boundary.circle.lat` | float | ❌ | `48.858268` | Circle boundary center latitude. |
| `boundary.circle.lon` | float | ❌ | `2.294471` | Circle boundary center longitude. |
| `boundary.circle.radius` | float | ❌ | `35` | Circle radius (in kilometers). *(Note: ignored for coarse reverse lookups)* |
| `sources` | string (comma-separated) | ❌ | `oa,gn` | Data sources to include (`oa=openaddresses`, `gn=geonames`). |
| `layers` | string (comma-separated) | ❌ | `address,locality` | Feature layers to include. |
| `boundary.country` | string (comma-separated) | ❌ | `FR,GBR` | ISO country codes to limit search. |
| `boundary.gid` | Pelias `gid` | ❌ | `whosonfirst:region:85683497` | Restrict results to a specific boundary by gid. |
| `size` | integer | ❌ | `3` | Number of results to return. |
## Example
```bash
GET https://gateway.mapmetrics-atlas.net/reverse-geocode/?point.lat=48.858268&point.lon=2.294471&boundary.circle.radius=7&size=3&layers=locality,address&sources=oa,gn&boundary.country=FR&boundary.gid=whosonfirst:region:85683497&token=YOUR_API_KEY
```
## Example Response
```json
{
"geocoding": {
"version": "0.2",
"attribution": "http://localhost:4000/attribution",
"query": {
"layers": [
"locality",
"address"
],
"sources": [
"openaddresses",
"geonames"
],
"size": 3,
"private": false,
"point.lat": 48.858268,
"point.lon": 2.294471,
"boundary.circle.radius": 5,
"boundary.circle.lat": 48.858268,
"boundary.circle.lon": 2.294471,
"boundary.country": [
"FRA"
],
"boundary.gid": "85683497",
"lang": {
"name": "English",
"iso6391": "en",
"iso6393": "eng",
"via": "default",
"defaulted": true
},
"querySize": 6
},
"engine": {
"name": "Pelias",
"author": "Mapzen",
"version": "1.0"
},
"timestamp": 1755669190951
},
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
2.294511,
48.857747
]
},
"properties": {
"id": "fr/countrywide:3edd29e1f32d7408",
"gid": "openaddresses:address:fr/countrywide:3edd29e1f32d7408",
"layer": "address",
"source": "openaddresses",
"source_id": "fr/countrywide:3edd29e1f32d7408",
"country_code": "FR",
"name": "12 Avenue Pierre Loti",
"housenumber": "12",
"street": "Avenue Pierre Loti",
"postalcode": "75007",
"confidence": 0.8,
"distance": 0.058,
"accuracy": "point",
"country": "France",
"country_gid": "whosonfirst:country:85633147",
"country_a": "FRA",
"macroregion": "Ile-of-France",
"macroregion_gid": "whosonfirst:macroregion:404227465",
"macroregion_a": "IF",
"region": "Paris",
"region_gid": "whosonfirst:region:85683497",
"region_a": "VP",
"localadmin": "Paris",
"localadmin_gid": "whosonfirst:localadmin:1159322569",
"locality": "Paris",
"locality_gid": "whosonfirst:locality:101751119",
"borough": "7th Arrondissement",
"borough_gid": "whosonfirst:borough:1158894245",
"neighbourhood": "Gros Caillou",
"neighbourhood_gid": "whosonfirst:neighbourhood:85873841",
"continent": "Europe",
"continent_gid": "whosonfirst:continent:102191581",
"label": "12 Avenue Pierre Loti, Paris, France"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
2.293651,
48.858317
]
},
"properties": {
"id": "fr/countrywide:afc231c551e25607",
"gid": "openaddresses:address:fr/countrywide:afc231c551e25607",
"layer": "address",
"source": "openaddresses",
"source_id": "fr/countrywide:afc231c551e25607",
"country_code": "FR",
"name": "2 Avenue Pierre Loti",
"housenumber": "2",
"street": "Avenue Pierre Loti",
"postalcode": "75007",
"confidence": 0.8,
"distance": 0.06,
"accuracy": "point",
"country": "France",
"country_gid": "whosonfirst:country:85633147",
"country_a": "FRA",
"macroregion": "Ile-of-France",
"macroregion_gid": "whosonfirst:macroregion:404227465",
"macroregion_a": "IF",
"region": "Paris",
"region_gid": "whosonfirst:region:85683497",
"region_a": "VP",
"localadmin": "Paris",
"localadmin_gid": "whosonfirst:localadmin:1159322569",
"locality": "Paris",
"locality_gid": "whosonfirst:locality:101751119",
"borough": "7th Arrondissement",
"borough_gid": "whosonfirst:borough:1158894245",
"neighbourhood": "Gros Caillou",
"neighbourhood_gid": "whosonfirst:neighbourhood:85873841",
"continent": "Europe",
"continent_gid": "whosonfirst:continent:102191581",
"label": "2 Avenue Pierre Loti, Paris, France"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
2.294373,
48.858816
]
},
"properties": {
"id": "fr/countrywide:c15503f350dea57a",
"gid": "openaddresses:address:fr/countrywide:c15503f350dea57a",
"layer": "address",
"source": "openaddresses",
"source_id": "fr/countrywide:c15503f350dea57a",
"country_code": "FR",
"name": "3 Avenue Anatole France",
"housenumber": "3",
"street": "Avenue Anatole France",
"postalcode": "75007",
"confidence": 0.8,
"distance": 0.061,
"accuracy": "point",
"country": "France",
"country_gid": "whosonfirst:country:85633147",
"country_a": "FRA",
"macroregion": "Ile-of-France",
"macroregion_gid": "whosonfirst:macroregion:404227465",
"macroregion_a": "IF",
"region": "Paris",
"region_gid": "whosonfirst:region:85683497",
"region_a": "VP",
"localadmin": "Paris",
"localadmin_gid": "whosonfirst:localadmin:1159322569",
"locality": "Paris",
"locality_gid": "whosonfirst:locality:101751119",
"borough": "7th Arrondissement",
"borough_gid": "whosonfirst:borough:1158894245",
"neighbourhood": "Gros Caillou",
"neighbourhood_gid": "whosonfirst:neighbourhood:85873841",
"continent": "Europe",
"continent_gid": "whosonfirst:continent:102191581",
"label": "3 Avenue Anatole France, Paris, France"
}
}
],
"bbox": [
2.293651,
48.857747,
2.294511,
48.858816
]
}
```
# Description
With reverse geocoding with Pelias, you can look up all sorts of information about points on a map,
# Size
A basic parameter for filtering is `size`, which is used to limit the number of results returned. In the earlier request that returned the Eiffel Tower (or 'Tour Eiffel', to be exact), notice that other results were returned including "Bureau de Gustave Eiffel" (a museum) and "Le Jules Verne" (a restaurant). To limit a reverse geocode to only the first result, pass the `size` parameter:
> /reverse?point.lat=48.858268&point.lon=2.294471&___size=1___
---
# Autocomplete Endpoint (v2)
https://docs.mapatlas.xyz/overview/geocoder/v2/autocomplete
# Autocomplete Endpoint (v2)
The **v2 Autocomplete API** provides instant place and address suggestions
based on partial user input. It is typically used in search boxes where
results update in real time as the user types.
> **Base URL:** all v2 examples on this page use `https://gateway.mapmetrics-atlas.net`.
> **Auth:** the `token` parameter is a **query parameter**, not a header.
> **Trailing slash is mandatory** on every v2 path — `/v2/autocomplete` (no
> trailing slash) returns `404`. Always call `/v2/autocomplete/`.
## How it Works
- Send a **partial query** using the `q` parameter, such as `"Nieuwezijds Voorburgwal 147"`.
- The API returns a **list of matching suggestions** (venues, streets,
addresses, localities) with no coordinates attached — see below.
- To resolve a suggestion to actual coordinates, take its `ord` value and
call [`/v2/retrieve/`](./retrieve.md).
- Pass a stable `session_token` across all keystrokes of one search so the
whole typing sequence bills as a single session — see
[Sessions](./sessions.md) for the full billing model.
::: danger Common mistake: `q`, not `text`
The parameter is **`q`**. Sending `text=Nieuwezijds Voorburgwal 147` does **not** error —
it returns HTTP 200 with `"results": []` and `"q": ""`. It silently looks
like "no matches" instead of failing loudly. This is the single most common
integration mistake against this endpoint.
:::
::: warning `proximity` is longitude first
`proximity` takes the form `
,` — **longitude before latitude**.
Reversing the order does not error either; it returns plausible-looking but
wrong results. A query centred on Maastricht with lat/lon swapped returned
hits 22–27 km away, in the wrong town entirely.
:::
## Endpoint
```
GET https://gateway.mapmetrics-atlas.net/v2/autocomplete/
```
## Parameters
| Parameter | Type | Req | Example | Description |
|-----------------|--------|-----|----------------------|----------------------------------------------------------------------|
| `q` | string | ✅ | `Nieuwezijds Voorburgwal 147` | The partial search text. **Not** `text`. |
| `token` | string | ✅ | `YOUR_API_KEY` | Auth token, passed as a query parameter. |
| `country` | string | ❌ | `nl` | ISO-2 lowercase country code to restrict results. |
| `session_token` | string | ❌ | `sess_a1b2c3` | Groups keystrokes into one billable session. See [Sessions](./sessions.md). |
| `proximity` | string | ❌ | `5.7423,50.8514` | `,` bias point. **Longitude first.** |
That is the whole list. Anything else you send is ignored — see
[There is no category filter](#there-is-no-category-filter-on-this-endpoint)
below for the most commonly attempted extra parameter.
## There is no category filter on this endpoint
::: danger `category=` is silently ignored here
`/v2/autocomplete/` has **no** category parameter. `category=`,
`categories=`, `poi_category=` and `layers=` are all accepted with HTTP 200
and then discarded — the response is byte-for-byte identical to the same
query without them (verified by diffing responses with `elapsed_ms`
stripped). Nothing tells you the filter didn't apply.
```bash
# These two return identical results. The second one filters nothing.
curl "…/v2/autocomplete/?q=hotel%20amsterdam&country=nl&token=YOUR_API_KEY"
curl "…/v2/autocomplete/?q=hotel%20amsterdam&country=nl&category=restaurant&token=YOUR_API_KEY"
```
:::
Categories on this endpoint are resolved from the **query text**, not from a
parameter: `q=hotel amsterdam` ranks hotels highly, `q=supermarket utrecht`
ranks supermarkets highly. It is a ranking bias, not a filter — you will
still get non-matching rows mixed in, and how well it works varies by
category. Measured over the top 15 results for a city-scoped query, `hotel`
and `supermarket` land ~13–14 matching rows, `restaurant` ~9–11, `cafe` ~8,
and `fuel` is weakest at ~2. Treat it as "mostly the right kind", never as a
guarantee.
If you need an actual filter — a hard "only supermarkets, ranked by distance"
— use [`/v2/category/`](./category.md) instead. That endpoint really does
filter, is proximity-ranked, carries `distance_m`, and fails honestly
(an unknown category returns zero rows rather than unfiltered ones).
## Example
```bash
curl "https://gateway.mapmetrics-atlas.net/v2/autocomplete/?q=Nieuwezijds%20Voorburgwal%20147&country=nl&session_token=sess_a1b2c3&token=YOUR_API_KEY"
```
## Example Response
```json
{
"count": 2,
"q": "Nieuwezijds Voorburgwal 147",
"mode": "autocomplete",
"country": "nl",
"elapsed_ms": 4,
"results": [
{
"id": "address.36035832929227138",
"ord": 276363,
"layer": "address",
"country": "nl",
"hn": "147",
"housenumber": "147",
"text": "Nieuwezijds Voorburgwal 147",
"place_name": "Nieuwezijds Voorburgwal 147, Amsterdam",
"locality": "Amsterdam",
"category": null,
"brand": null
},
{
"id": "place.0",
"layer": "place",
"country": "nl",
"text": "Amsterdam",
"place_name": "Amsterdam, Netherlands",
"locality": "Amsterdam",
"category": null,
"brand": null
}
]
}
```
Note that no result carries `center`, `geometry`, or `bbox` — coordinates
are deliberately withheld. Suggestions are cheap to serve at every
keystroke; coordinate resolution is the billable step, and it only happens
when you call [`/v2/retrieve/`](./retrieve.md) on the suggestion the user
picked.
## Three traps in the result objects
The second result above is not a typo. Three properties of this response
shape break naive client code, and none of them announce themselves.
### `hn` is a house number string, not a flag
`hn` is typed `string | null` and holds the actual house number — `"147"`,
not `true`. The name reads like a boolean and the field sits next to
`housenumber`, so it is routinely misread as "this row has a house number".
This matters because `hn` is passed straight through to
[`/v2/retrieve/`](./retrieve.md), where the wrong value is silently
discarded and you get the street centroid instead of the building:
```bash
# hn=147 — the house number. Resolves to the building.
…/v2/retrieve/?country=nl&layer=address&ord=276363&hn=147
# → "center": [4.890890, 52.373158], "housenumber": "147"
# hn=true — discarded. Same answer as omitting hn entirely, ~146 m away.
…/v2/retrieve/?country=nl&layer=address&ord=276363&hn=true
# → "center": [4.890498, 52.371864] ← street centroid, no housenumber echoed
```
Copy `hn` from the suggestion verbatim. Never synthesise it.
### Non-retrievable rows omit `ord` entirely
Some rows — injected locality entries, like the bare `"Amsterdam"` above —
cannot be retrieved. On those rows the `ord` key is **absent from the JSON
object**, not present-and-`null`. Code that does `result["ord"]` or
`result.ord!` on a strict/typed decoder throws rather than yielding null.
Test for **presence**, not for null:
```js
const retrievable = results.filter((r) => 'ord' in r); // ✅
const retrievable = results.filter((r) => r.ord !== null); // ❌ crashes on strict decoders
```
`q=amsterdam&country=nl` currently returns 15 rows, two of which have no
`ord`. Every [geocoding SDK](/overview/sdk/geocoding/) exposes this as
`suggestion.isRetrievable` so you don't have to probe the raw object.
### `id` is not unique within a response
::: danger Never use `id` as a list key
`id` is **not** a primary key and is not unique inside a single response.
`q=amsterdam&country=nl` returns `"id": "place.0"` on two different rows.
Feeding that into a keyed list — React `key`, Flutter `ValueKey`, Compose
`items(key = …)`, SwiftUI `id:` — produces duplicate keys. Compose throws
outright (`IllegalArgumentException: Key … was already used`); React and
SwiftUI corrupt row state more quietly.
:::
`id` is also useless for retrieval — see the
[`ord` is the handle](./retrieve.md) note. Treat it as opaque debug metadata.
For a stable key, derive one from content, or use the list index. The
[search UI layers](/overview/sdk/geocoding/search-ui) ship a `uniquifyRowIds`
helper that suffixes repeats (`place.0`, `place.0#2`) so a list can be keyed
safely without discarding rows.
---
# Category Search (v2)
https://docs.mapatlas.xyz/overview/geocoder/v2/category
---
title: Category Search (v2)
description: Find POIs of a given category near a point — proximity-ranked, with distances. The "what's near me" endpoint.
---
# Category Search (v2)
The **v2 Category API** answers *"what is near me, of this kind"* — supermarkets
around a point, cafés near a map centre, pharmacies within 500 m. Results are
ranked by distance and carry the distance in metres.
## Category search vs reverse geocode
These are easy to confuse, and picking the wrong one gets you the wrong answer:
| | Input | Returns | Use when |
|---|---|---|---|
| [Reverse Geocode](/overview/geocoder/v2/reversegeocode) | a point | what **is** at that point | "What address am I standing on?" |
| **Category Search** | a point **+ a category** | the nearest POIs **of that kind** | "Where's the nearest supermarket?" |
Reverse geocoding answers *identity*. Category search answers *discovery*.
::: warning This is the only endpoint that filters by category
Adding `category=` to [`/v2/autocomplete/`](./autocomplete.md) does nothing.
It returns HTTP 200 and results identical to the unfiltered query — the
parameter is silently ignored there. Autocomplete infers categories from the
query *text* as a ranking bias only. If you need a real filter, you are on
the right page.
:::
## Endpoint
```
GET https://gateway.mapmetrics-atlas.net/v2/category/
```
## Parameters
| Parameter | Type | Req | Example | Description |
|---|---|---|---|---|
| `category` | string | ✅ | `supermarket` | Category to search for. Comma-separate for a union — see below. |
| `proximity` | `lon,lat` | ❌ | `4.895,52.370` | Point to search around. **Longitude first.** Omitted, the caller's approximate location is used. |
| `limit` | integer | ❌ | `10` | Max results. Default 10, capped at 50. |
| `radius` | integer | ❌ | `500` | Hard cut-off in **metres**. See the note below on how it interacts with `limit`. |
| `country` | string | ❌ | `NL` | Restrict to one country. Otherwise inferred from `proximity`. |
| `token` | string | ✅ | `YOUR_API_KEY` | Auth token, passed as a query parameter. |
::: warning `proximity` is `lon,lat` — longitude first
This is GeoJSON order, and it is the reverse of the `lat,lon` most mapping
UIs display. Swapping them does not error — you get results near a completely
different place. `4.895,52.370` is Amsterdam; `52.370,4.895` is not.
:::
## Example
```bash
curl "https://gateway.mapmetrics-atlas.net/v2/category/?category=supermarket&proximity=4.895,52.370&limit=3&token=YOUR_API_KEY"
```
```json
{
"type": "FeatureCollection",
"query": "supermarket",
"category": "supermarket",
"features": [
{
"id": "poi.123456",
"type": "Feature",
"place_name": "Albert Heijn, Amsterdam",
"center": [4.8951, 52.3702],
"geometry": { "type": "Point", "coordinates": [4.8951, 52.3702] },
"properties": {
"category": "supermarket",
"layer": "poi",
"distance_m": 83
}
}
],
"attribution": "..."
}
```
## Several categories at once
Comma-separate to search a union of categories. A feature matches if it is in
**any** of them:
```
?category=restaurant,cafe,bar&proximity=4.895,52.370
```
## Filtering by distance
Every feature carries `properties.distance_m` — great-circle metres from your
`proximity` point — so you can render "250 m away" without re-deriving it.
`radius` applies a hard cut-off in metres:
```
?category=restaurant&proximity=4.895,52.370&radius=300
```
::: tip `radius` trims, it does not widen
`radius` is applied **after** ranking. `radius=300&limit=50` returns however
many of the top 50 fall within 300 m — it does not keep searching outward to
find 50 results inside the radius. So a tight radius can return fewer results
than your `limit`, and that is expected rather than an error.
:::
## Subcategories are included
Searching a broad category also returns its more specific children — asking for
`restaurant` also matches `italian_restaurant` and `french_restaurant`. Each
feature reports its own precise `properties.category`, so you can group or
filter client-side.
## Category names
Category matching is on whole tokens, so `bar` will not match `barber`. Common
non-English names are understood too — Dutch `supermarkt`, `apotheek` and
`koffie` all resolve to their canonical categories.
An unknown category is **not** an error: it returns an empty `features` array
with HTTP 200. If you get zero results, check the category name before assuming
the area is empty.
## Billing
Category search is billed **per request**, in the same `geocode` bucket as
forward and reverse geocoding. It is *not* session-billed like
[autocomplete](/overview/geocoder/v2/sessions) — there is no keystroke stream
to amortise, each call is one query.
## Errors
| Status | Meaning |
|---|---|
| `400` | `category` parameter missing. |
| `401` | Token missing or invalid. |
| `403` | Token lacks the `geocode` scope. |
---
# Forward Geocode (v2)
https://docs.mapatlas.xyz/overview/geocoder/v2/forwardgeocode
# Forward Geocode (v2)
The **v2 Forward Geocode API** matches a full free-text query to its
corresponding geographic coordinates and administrative context.
## How it Works
- Send the text you want to match using the `q` parameter, such as
`"Nieuwezijds Voorburgwal 147"`.
- Restrict results to a country with `country`, and cap the number of
results with `size`.
- Pass `format=pelias` to get back a full GeoJSON `FeatureCollection` — see
the trap below.
::: danger `format=pelias` is required for the GeoJSON envelope
Without `format=pelias` — or with any other value — the endpoint silently
returns a **different, flat shape** instead of the documented
`FeatureCollection`. This is not an error; it's a different response
contract. Always pass `format=pelias` explicitly.
:::
## Endpoint
```
GET https://gateway.mapmetrics-atlas.net/v2/forward-geocode/
```
## Parameters
| Parameter | Type | Req | Example | Description |
|-----------|---------|-----|------------------|------------------------------------------------------------------------|
| `q` | string | ✅ | `Nieuwezijds Voorburgwal 147` | The search query text. **Not** `text`. |
| `country` | string | ❌ | `nl` | ISO-2 lowercase country code to restrict search. |
| `size` | integer | ❌ | `10` | Number of results to return. |
| `format` | string | ✅ | `pelias` | Must be `pelias` to get the GeoJSON `FeatureCollection` shape. |
| `token` | string | ✅ | `YOUR_API_KEY` | Auth token, passed as a query parameter. |
## Example
```bash
curl "https://gateway.mapmetrics-atlas.net/v2/forward-geocode/?q=Nieuwezijds%20Voorburgwal%20147&country=nl&size=10&format=pelias&token=YOUR_API_KEY"
```
## Example Response
```json
{
"geocoding": {
"version": "0.2",
"attribution": "http://localhost:4000/attribution",
"query": {
"q": "Nieuwezijds Voorburgwal 147",
"country": "nl",
"size": 10
},
"engine": {
"name": "Pelias",
"author": "Mapzen",
"version": "1.0"
}
},
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [5.7423, 50.8514]
},
"properties": {
"id": "osm:ext:7f3a9c1d2e4b5a6f",
"gid": "osm:address:7f3a9c1d2e4b5a6f",
"layer": "address",
"name": "Nieuwezijds Voorburgwal 147",
"label": "Nieuwezijds Voorburgwal 147, Maastricht, Netherlands",
"housenumber": "25",
"street": "Nieuwezijds Voorburgwal",
"locality": "Maastricht",
"country": "Netherlands",
"country_a": "NLD"
}
}
],
"bbox": [5.7423, 50.8514, 5.7423, 50.8514]
}
```
::: warning `region` and `postalcode` are frequently absent
Unlike the v1 Pelias response, `region` and `postalcode` are frequently
**missing** from v2 `properties` — do not assume either field is always
present.
:::
::: tip Attribution must be surfaced
`geocoding.attribution` is the ODbL licence credit. Any client displaying
results **must** surface this attribution.
:::
---
# Retrieve Endpoint (v2)
https://docs.mapatlas.xyz/overview/geocoder/v2/retrieve
# Retrieve Endpoint (v2)
The **v2 Retrieve API** resolves one [autocomplete](./autocomplete.md)
suggestion into full coordinates. This is the billable step in the v2
autocomplete flow — see [Sessions](./sessions.md) for how retrieve closes a
session.
## How it Works
- Take the `ord` value from an autocomplete suggestion the user picked.
- Call `/v2/retrieve/` with that `ord`, plus the suggestion's `country` and
`layer`, to get back a `center` coordinate pair.
- Pass the same `session_token` used during autocomplete so the session is
closed correctly and billed once.
::: danger `ord` is the handle — `id` 404s
Retrieval is keyed on **`ord`**, not `id`. Retrieving by `id` returns
`404` on every layer, with no exception. Always take `ord` straight from
the autocomplete suggestion you're resolving — never construct or reuse an
`id`.
:::
## Endpoint
```
GET https://gateway.mapmetrics-atlas.net/v2/retrieve/
```
## Parameters
| Parameter | Type | Req | Example | Description |
|-----------------|---------|-----|----------------|----------------------------------------------------------------|
| `country` | string | ✅ | `nl` | ISO-2 lowercase country code, from the suggestion. |
| `layer` | string | ✅ | `address` | Layer of the suggestion, from the suggestion. |
| `ord` | integer | ✅ | `276363` | The suggestion handle from `/v2/autocomplete/`. Not `id`. |
| `hn` | string | ❌ | `147` | The **house number**, copied verbatim from the suggestion's `hn`. Not a flag — see below. |
| `session_token` | string | ❌ | `sess_a1b2c3` | Same token used during autocomplete; closes the session. |
| `token` | string | ✅ | `YOUR_API_KEY` | Auth token, passed as a query parameter. |
::: danger `hn` is a house number, not a boolean
Despite the name, `hn` carries the house number itself (`147`), matching the
`string | null` `hn` field on the [autocomplete](./autocomplete.md)
suggestion. Sending `hn=true` does not error — it is silently discarded, and
you get the **street centroid** instead of the building. On
`Nieuwezijds Voorburgwal 147` that is a ~146 m error, with nothing in the
response to signal it:
| request | `center` | `housenumber` in response |
|---|---|---|
| `…&ord=276363&hn=147` | `[4.890890, 52.373158]` | `"147"` |
| `…&ord=276363&hn=true` | `[4.890498, 52.371864]` | *absent* |
| `…&ord=276363` (omitted) | `[4.890498, 52.371864]` | *absent* |
Always pass through the suggestion's own `hn` value. Never construct one.
:::
## Example
```bash
curl "https://gateway.mapmetrics-atlas.net/v2/retrieve/?country=nl&layer=address&ord=276363&hn=147&session_token=sess_a1b2c3&token=YOUR_API_KEY"
```
## Example Response
```json
{
"center": [4.890890121459961, 52.3731575012207],
"country": "nl",
"housenumber": "147",
"layer": "address",
"locality": "Amsterdam",
"name": "Nieuwezijds Voorburgwal",
"id": ""
}
```
::: warning `center` is `[lon, lat]`
`center` is `[longitude, latitude]`, in that order — easy to swap by
mistake. `id` in the response is currently a placeholder empty string;
don't rely on it for anything.
:::
::: tip Not every suggestion can be retrieved
Rows that carry no `ord` at all (the key is **absent**, not `null`) cannot be
resolved — see
[Non-retrievable rows](./autocomplete.md#non-retrievable-rows-omit-ord-entirely).
Filter them out before you get here.
:::
## Retrieve Batch
`/v2/retrieve-batch/` resolves several suggestions in one call.
### Endpoint
```
GET https://gateway.mapmetrics-atlas.net/v2/retrieve-batch/
```
### Parameters
| Parameter | Type | Req | Example | Description |
|-----------|--------|-----|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `items` | string | ✅ | `[{"country":"nl","layer":"address","ord":276363,"hn":"147"}]` (URL-encoded) | URL-encoded JSON array of `{country, layer, ord, hn?}` objects. `hn` is a **string** house number — see the warning above. |
| `token` | string | ✅ | `YOUR_API_KEY` | Auth token, passed as a query parameter. |
::: danger Only `items` works — no repeated params
`/v2/retrieve-batch/` takes **one** parameter, `items`, holding a
URL-encoded JSON array. It does **not** accept repeated params:
`ord=128371&ord=128372`, `ords=128371,128372`, and `ids=...` all silently
return HTTP 200 with `count: 0` — no error, no results.
:::
### Example
```bash
curl "https://gateway.mapmetrics-atlas.net/v2/retrieve-batch/?items=%5B%7B%22country%22%3A%22nl%22%2C%22layer%22%3A%22address%22%2C%22ord%22%3A276363%2C%22hn%22%3A%22147%22%7D%2C%7B%22country%22%3A%22nl%22%2C%22layer%22%3A%22address%22%2C%22ord%22%3A276362%7D%5D&token=YOUR_API_KEY"
```
The decoded `items` value in the example above is:
```json
[
{ "country": "nl", "layer": "address", "ord": 276363, "hn": "147" },
{ "country": "nl", "layer": "address", "ord": 276362 }
]
```
### Example Response
```json
{
"count": 2,
"results": [
{ "center": [5.7423, 50.8514], "id": "" },
{ "center": [5.7431, 50.8519], "id": "" }
]
}
```
## See Also
- [Autocomplete](./autocomplete.md) — produces the `ord` values retrieve consumes.
- [Sessions](./sessions.md) — retrieve closes the session it belongs to.
---
# Reverse Geocode (v2)
https://docs.mapatlas.xyz/overview/geocoder/v2/reversegeocode
# Reverse Geocode (v2)
The **v2 Reverse Geocode API** takes a latitude/longitude point and returns
the closest address or place.
## How it Works
- Send the point to reverse-geocode using `point.lat` and `point.lon` — note
that these parameter names literally contain dots; that is correct, not a
typo.
- Cap the number of results with `size`.
- Pass `format=pelias` to get back a full GeoJSON `FeatureCollection` — the
same trap as forward geocode applies here.
::: danger `format=pelias` is required for the GeoJSON envelope
Without `format=pelias` — or with any other value — the endpoint silently
returns a **different, flat shape** instead of the documented
`FeatureCollection`. Always pass `format=pelias` explicitly.
:::
## Endpoint
```
GET https://gateway.mapmetrics-atlas.net/v2/reverse-geocode/
```
## Parameters
| Parameter | Type | Req | Example | Description |
|-------------|---------|-----|------------------|--------------------------------------------------------------------|
| `point.lat` | float | ✅ | `50.8514` | Latitude of the point. Parameter name contains a literal dot. |
| `point.lon` | float | ✅ | `5.7423` | Longitude of the point. Parameter name contains a literal dot. |
| `size` | integer | ❌ | `10` | Number of results to return. |
| `format` | string | ✅ | `pelias` | Must be `pelias` to get the GeoJSON `FeatureCollection` shape. |
| `token` | string | ✅ | `YOUR_API_KEY` | Auth token, passed as a query parameter. |
## Example
```bash
curl "https://gateway.mapmetrics-atlas.net/v2/reverse-geocode/?point.lat=50.8514&point.lon=5.7423&size=10&format=pelias&token=YOUR_API_KEY"
```
## Example Response
```json
{
"geocoding": {
"version": "0.2",
"attribution": "http://localhost:4000/attribution",
"query": {
"point.lat": 50.8514,
"point.lon": 5.7423,
"size": 10
},
"engine": {
"name": "Pelias",
"author": "Mapzen",
"version": "1.0"
}
},
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [5.7423, 50.8514]
},
"properties": {
"id": "osm:ext:7f3a9c1d2e4b5a6f",
"gid": "osm:address:7f3a9c1d2e4b5a6f",
"layer": "address",
"name": "Nieuwezijds Voorburgwal 147",
"label": "Nieuwezijds Voorburgwal 147, Maastricht, Netherlands",
"housenumber": "25",
"street": "Nieuwezijds Voorburgwal",
"locality": "Maastricht",
"country": "Netherlands",
"country_a": "NLD"
}
}
],
"bbox": [5.7423, 50.8514, 5.7423, 50.8514]
}
```
::: warning `region` and `postalcode` are frequently absent
As with forward geocode, `region` and `postalcode` are frequently
**missing** from v2 `properties` — do not assume either field is always
present.
:::
::: tip Attribution must be surfaced
`geocoding.attribution` is the ODbL licence credit. Any client displaying
results **must** surface this attribution.
:::
---
# Sessions (v2 Autocomplete Billing)
https://docs.mapatlas.xyz/overview/geocoder/v2/sessions
# Sessions (v2 Autocomplete Billing)
The v2 [autocomplete](./autocomplete.md) API bills by **session**, not by
request. Understanding how a session starts, continues, and ends is
essential to avoid unexpectedly high usage.
## How it Works
- The billable unit is a **session start**, not each individual keystroke.
- Pass one stable `session_token` across every autocomplete request that
belongs to the same user search. A run of keystrokes sharing a token is
**one session**.
- A session ends — and the next request starts a new one — on any of:
- a [`/v2/retrieve/`](./retrieve.md) call, which **closes** the session;
- **50 suggest calls** sharing a token (the roll to a new session happens
on request 51);
- **2 minutes of idle time** with no request on that token.
::: danger Omitting `session_token` costs roughly 5x
If you omit `session_token`, a **fresh session is minted for every
request**. Each keystroke then bills as its own session instead of one
session covering the whole search — in practice this multiplies cost by
roughly 5x for a typical search. Always pass a `session_token`.
:::
::: warning Three retrieves in a row is three sessions
Each [`/v2/retrieve/`](./retrieve.md) call **closes** the session it
belongs to. If you call retrieve three times in a row on the same token —
for example to try resolving several candidates — that is **three separate
sessions**, not one, because each retrieve both starts (if none was already
open) and closes a session.
:::
## Recommendations
- **Debounce input** by roughly 150ms before firing an autocomplete request,
to avoid burning through the 50-request cap on fast typists.
- **Reuse the same `session_token`** for the full lifetime of one search box
interaction, from the first keystroke until the user picks a result or
abandons the search.
- Generate a new `session_token` only when the user starts a genuinely new
search (e.g. clears the box, or 2 minutes have passed).
## Worked Example
A user types `"Nieuwezijds"` into a search box, one character at a time, with a
single `session_token` (`sess_a1b2c3`) attached to every request:
1. `q=v` → autocomplete call, `session_token=sess_a1b2c3`
2. `q=vo` → autocomplete call, same token
3. `q=vog` → autocomplete call, same token
4. `q=voge` → autocomplete call, same token
5. `q=vogel` → autocomplete call, same token
6. `q=Nieuwezijds` → autocomplete call, same token
That's **6 suggest calls sharing one token**. The user then picks
`Nieuwezijds Voorburgwal 147, Maastricht` from the suggestion list, and the client calls:
7. `/v2/retrieve/?ord=128371&country=nl&layer=address&session_token=sess_a1b2c3`
The retrieve call **closes the session**.
**Total: one billable session**, regardless of the 6 keystrokes that led up
to it.
## See Also
- [Autocomplete](./autocomplete.md) — where `session_token` is attached to each suggest request.
- [Retrieve](./retrieve.md) — where a session is closed.
---
# MapMetrics Atlas API Overview
https://docs.mapatlas.xyz/overview/
# MapMetrics Atlas API Overview
Welcome to the MapMetrics Atlas API documentation. Build powerful, location-based applications with our comprehensive suite of mapping, geocoding, and routing services.
## What is MapMetrics Atlas API?
MapMetrics Atlas provides a complete set of location services including interactive maps, geocoding, turn-by-turn directions, and routing optimization. Our platform is built for developers who need reliable, high-performance mapping solutions.
## Quick Start
> **⚠️ Important:** You need an API key to use MapMetrics Atlas API. All API requests require authentication. [Sign up now](https://portal.mapmetrics.org/) to get started!
Get started in three simple steps:
1. **[Create an API Key](https://portal.mapmetrics.org/)** - Sign up at MapMetrics Portal to get your API token and map style URL
2. **[Build Your First Map](/sdk/examples/simple-map-cdn)** - Follow our quick start guide
## API Services
### 🗺️ Maps & Vector Tiles
Access customizable vector map tiles with dynamic styling options. Our maps support both light and dark themes and can be fully customized to match your application's design.
**Features:**
- High-performance vector tiles
- Customizable map styles (dark/light themes)
- Global map coverage
- Support for multiple zoom levels
**Get Started:**
- [Map Styles Documentation](#map-styles)
- [Create Custom Styles](/sdk/examples/style-creation)
### 📍 Geocoding Services
Convert addresses to coordinates (forward geocoding) and coordinates to addresses (reverse geocoding). Includes autocomplete search for building location-aware features.
**Endpoints:**
- [Autocomplete](./geocoder/autocomplete) - Real-time search suggestions
- [Forward Geocoding](./geocoder/forwardgeocode) - Address → Coordinates
- [Reverse Geocoding](./geocoder/reversegeocode) - Coordinates → Address
**Use Cases:**
- Location search in apps
- Address validation
- Store locators
- Location-based forms
### 🧭 Directions & Routing
Calculate optimal routes, analyze reachability, and optimize multi-stop trips with our powerful routing engine.
**Endpoints:**
- [Directions](./directions/directions) - Turn-by-turn navigation
- [Optimization](./directions/optimization) - Multi-stop route optimization
- [Isochrone](./directions/isochrone) - Reachability analysis
- [Matrix](./directions/matrix) - Distance/time matrices
- [Map Matching](./directions/mapMatch) - GPS trace matching
- [Elevation](./directions/elevation) - Elevation profiles
**Supported Transport Modes:**
- 🚗 Auto (car, motorcycle, taxi)
- 🚴 Bicycle
- 🚶 Pedestrian
- 🚌 Bus
- 🚛 Truck
- 🛵 Motor Scooter
**Use Cases:**
- Navigation apps
- Delivery route optimization
- Fleet management
- Travel time analysis
## SDKs & Platforms
Choose the right SDK for your platform:
| Platform | SDK | Status | Documentation |
|----------|-----|--------|---------------|
| **Web** | MapMetrics GL JS | ✅ Stable | [Get Started](./sdk/mapmetrics) |
| **iOS** | MapMetrics Native | ✅ Stable | [Get Started](./sdk/ios-native/GettingStarted) |
| **Android** | MapMetrics Native | ✅ Stable | [Get Started](./sdk/android-native/getting-started) |
| **Flutter** | MapMetrics Flutter | 🟡 Beta | [Get Started](/sdk/examples/flutter-mapmetrics-intro) |
### Web SDK Features
- Interactive vector maps
- Markers, popups, and custom overlays
- 3D buildings and terrain
- Heatmaps and clustering
- Custom styling
**Installation:**
- CDN: [Simple Map (CDN)](/sdk/examples/simple-map-cdn)
- NPM: [Simple Map (NPM)](/sdk/examples/simple-map-npm) - Package: [@mapmetrics/mapmetrics-gl](https://www.npmjs.com/package/@mapmetrics/mapmetrics-gl)
- React: [React Integration](/sdk/examples/react-map-example)
### Mobile SDK Features
- Native performance
- Offline map support
- Location tracking
- Custom annotations
- Gesture controls
## Authentication
> **🔒 API Key Required:** MapMetrics Atlas API requires authentication for all requests. Without a valid API key, maps won't load and API calls will return 401 Unauthorized errors.
All API requests require authentication using your API token. You must create an account on the [MapMetrics Portal](https://portal.mapmetrics.org/) to get your API token and map style URL.
**Get Started:**
1. Visit [MapMetrics Portal](https://portal.mapmetrics.org/)
2. Create your account (free to start)
3. Get your complete map style URL (includes your API token)
4. Copy and use it in your application
**Detailed Guide:** [Create API Key](/sdk/examples/key-creation)
### Don't Have an API Key Yet?
If you try to use MapMetrics without an API key:
- ❌ Maps will fail to load
- ❌ API requests will return authentication errors
- ❌ No access to geocoding or routing services
**Solution:** [Create your free account](https://portal.mapmetrics.org/) in minutes!
## Map Styles
All map styles are created and managed through the [MapMetrics Portal](https://portal.mapmetrics.org/). When you create an account, you'll receive a unique map style URL for your applications.
### Getting Your Map Style URL
1. **Sign up** at [MapMetrics Portal](https://portal.mapmetrics.org/)
2. **Create a new style** or use the default style provided
3. **Copy your complete style URL** from the portal (it includes your API token)
4. **Paste it directly** in your application code
The portal provides you with a ready-to-use URL - just copy and paste it into your application!
**Example URL:**
```text
https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_ACCOUNT_ID/mapstyle.json&token=YOUR_API_KEY
```
### Customize Your Map Style
Through the MapMetrics Portal, you can:
- **Customize colors** - Match your brand's color scheme
- **Choose fonts** - Select typography for map labels
- **Add/remove layers** - Control which map features are displayed
- **Create multiple styles** - Different styles for different use cases
- **Dark/Light themes** - Create styles optimized for different themes
**Learn More:** [Style Creation Guide](/sdk/examples/style-creation)
## Migration Guides
Switching from another mapping provider? We've got you covered:
- [Migrate from Google Maps](/sdk/examples/google-map-to-mapmetrics)
- [Migrate from Mapbox](./sdk/mapbox-migration-guide)
## Support & Resources
### Documentation
- [Code Examples](/sdk/examples/Intro) - Ready-to-use code samples
- [Migration Guides](./migration-guide) - Switch from other providers
### Community
- [Discord Community](https://discord.com/invite/uRXQRfbb7d) - Chat with developers
- [Facebook](https://www.facebook.com/MapMetrics) - Latest updates
- [YouTube](https://www.youtube.com/@mapmetrics3435) - Video tutorials
### Need Help?
- Browse our [examples](/sdk/examples/Intro)
- Join our [Discord community](https://discord.com/invite/uRXQRfbb7d)
- Check out [video tutorials](https://www.youtube.com/@mapmetrics3435)
- Contact support for technical assistance
## What's Next?
Ready to start building? Here are some recommended next steps:
1. **[Create your account](https://portal.mapmetrics.org/)** - Sign up and get your API key
2. **[Display your first map](/sdk/examples/simple-map-cdn)** - Quick start guide
3. **[Add markers](/sdk/examples/add-a-marker)** - Display points of interest
4. **[Implement routing](./directions/directions)** - Add turn-by-turn directions
5. **[Customize your map style](https://portal.mapmetrics.org/)** - Create custom styles in the portal
---
**Let's build something amazing together!** 🚀
---
# Migration Guide
https://docs.mapatlas.xyz/overview/migration-guide
# Migration Guide
Migrate your existing maps from Google Maps or Mapbox to MapMetrics Atlas.
## Available Migration Guides
### [Google Maps to MapMetrics](/sdk/examples/google-map-to-mapmetrics)
Learn how to migrate your application from Google Maps to MapMetrics Atlas.
### [Mapbox to MapMetrics](/overview/sdk/mapbox-migration-guide)
Learn how to migrate your application from Mapbox to MapMetrics Atlas.
---
# Add Markers in Bulk
https://docs.mapatlas.xyz/overview/sdk/android-native/annotations/add-markers
# Add Markers in Bulk
This example demonstrates how you can add markers in bulk.
[//]: # ()
[//]: # (
)
[//]: # ()
[//]: # (
)
[//]: # (
? = null
private var progressDialog: ProgressDialog? = null
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_marker_bulk)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { initMap(it) }
}
private fun initMap(maplibreMap: MapLibreMap) {
this.maplibreMap = maplibreMap
maplibreMap.setStyle(TestStyles.getPredefinedStyleWithFallback("Streets"))
}
override fun onCreateOptionsMenu(menu: Menu): Boolean {
val spinnerAdapter = ArrayAdapter.createFromResource(
this,
R.array.bulk_marker_list,
android.R.layout.simple_spinner_item
)
spinnerAdapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item)
menuInflater.inflate(R.menu.menu_bulk_marker, menu)
val item = menu.findItem(R.id.spinner)
val spinner = item.actionView as Spinner
spinner.adapter = spinnerAdapter
spinner.onItemSelectedListener = this@BulkMarkerActivity
return true
}
override fun onItemSelected(parent: AdapterView<*>?, view: View, position: Int, id: Long) {
val amount = Integer.valueOf(resources.getStringArray(R.array.bulk_marker_list)[position])
if (locations == null) {
progressDialog = ProgressDialog.show(this, "Loading", "Fetching markers", false)
lifecycleScope.launch(Dispatchers.IO) {
locations = loadLocationTask(this@BulkMarkerActivity)
withContext(Dispatchers.Main) {
onLatLngListLoaded(locations, amount)
}
}
} else {
showMarkers(amount)
}
}
private fun onLatLngListLoaded(latLngs: List?, amount: Int) {
progressDialog!!.hide()
locations = latLngs
showMarkers(amount)
}
private fun showMarkers(amount: Int) {
if (!this::maplibreMap.isInitialized || locations == null || mapView.isDestroyed) {
return
}
maplibreMap.clear()
showGlMarkers(min(amount, locations!!.size))
}
private fun showGlMarkers(amount: Int) {
val markerOptionsList: MutableList = ArrayList()
val formatter = DecimalFormat("#.#####")
val random = Random()
var randomIndex: Int
for (i in 0 until amount) {
randomIndex = random.nextInt(locations!!.size)
val latLng = locations!![randomIndex]
markerOptionsList.add(
MarkerOptions()
.position(latLng)
.title(i.toString())
.snippet(formatter.format(latLng.latitude) + "`, " + formatter.format(latLng.longitude))
)
}
maplibreMap.addMarkers(markerOptionsList)
}
override fun onNothingSelected(parent: AdapterView<*>?) {
// nothing selected, nothing to do!
}
override fun onStart() {
super.onStart()
mapView.onStart()
}
override fun onResume() {
super.onResume()
mapView.onResume()
}
override fun onPause() {
super.onPause()
mapView.onPause()
}
override fun onStop() {
super.onStop()
mapView.onStop()
}
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
override fun onDestroy() {
super.onDestroy()
if (progressDialog != null) {
progressDialog!!.dismiss()
}
mapView.onDestroy()
}
override fun onLowMemory() {
super.onLowMemory()
mapView.onLowMemory()
}
private fun loadLocationTask(
activity: BulkMarkerActivity,
) : List? {
try {
val json = GeoParseUtil.loadStringFromAssets(
activity.applicationContext,
"points.geojson"
)
return GeoParseUtil.parseGeoJsonCoordinates(json)
} catch (exception: IOException) {
Timber.e(exception, "Could not add markers")
}
return null
}
}
```
---
# Annotation: Marker
https://docs.mapatlas.xyz/overview/sdk/android-native/annotations/marker-annotations
# Annotation: Marker
This guide will show you how to add Markers in the map.
`Annotation` is an overlay on top of a Map.
1. [Marker]
2. [Polyline]
3. [Polygon]
A Marker shows an icon image at a geographical location. By default, marker uses
a [provided image] as its icon.
![marker image]
Or, the icon can be customized using [IconFactory] to generate an
[Icon] using a provided image.
For more customization, please read the documentation about [MarkerOptions].
In this showcase, we continue the code from the [Quickstart],
rename Activity into `JsonApiActivity`,
and pull the GeoJSON data from a free and public API.
Then add markers to the map with GeoJSON:
1. In your module Gradle file (usually `//build.gradle`), add `okhttp` to simplify code for making HTTP requests.
```gradle
dependencies {
...
implementation 'com.squareup.okhttp3:okhttp:4.10.0'
...
}
```
2. Sync your Android project the with Gradle files.
3. In `JsonApiActivity` we add a new variable for `MapLibreMap`.
It is used to add annotations to the map instance.
```kotlin
class JsonApiActivity : AppCompatActivity() {
// Declare a variable for MapView
private lateinit var mapView: MapView
// Declare a variable for MapLibreMap
private lateinit var maplibreMap: MapLibreMap}
```
4. Call `mapview.getMapSync()` in order to get a `MapLibreMap` object.
After `maplibreMap` is assigned, call the `getEarthQuakeDataFromUSGS()` method
to make a HTTP request and transform data into the map annotations.
```kotlin
mapView.getMapAsync { map ->
maplibreMap = map
maplibreMap.setStyle(styleName)
// Fetch data from USGS
getEarthQuakeDataFromUSGS()
}
```
5. Define a function `getEarthQuakeDataFromUSGS()` to fetch GeoJSON data from a public API.
If we successfully get the response, call `addMarkersToMap()` on the UI thread.
```kotlin
// Get Earthquake data from usgs.gov, read API doc at:
// https://earthquake.usgs.gov/fdsnws/event/1/
private fun getEarthQuakeDataFromUSGS() {
val url = "https://earthquake.usgs.gov/fdsnws/event/1/query".toHttpUrl().newBuilder()
.addQueryParameter("format", "geojson")
.addQueryParameter("starttime", "2022-01-01")
.addQueryParameter("endtime", "2022-12-31")
.addQueryParameter("minmagnitude", "5.8")
.addQueryParameter("latitude", "24")
.addQueryParameter("longitude", "121")
.addQueryParameter("maxradius", "1.5")
.build()
val request: Request = Request.Builder().url(url).build()
OkHttpClient().newCall(request).enqueue(object : Callback {
override fun onFailure(call: Call, e: IOException) {
Toast.makeText(this@JsonApiActivity, "Fail to fetch data", Toast.LENGTH_SHORT)
.show()
}
override fun onResponse(call: Call, response: Response) {
val featureCollection = response.body?.string()
?.let(FeatureCollection::fromJson)
?: return
// If FeatureCollection in response is not null
// Then add markers to map
runOnUiThread { addMarkersToMap(featureCollection) }
}
})
}
```
6. Now it is time to add markers into the map.
- In the `addMarkersToMap()` method, we define two types of bitmap for the marker icon.
- For each feature in the GeoJSON, add a marker with a snippet about earthquake details.
- If the magnitude of an earthquake is bigger than 6.0, we use the red icon. Otherwise, we use the blue one.
- Finally, move the camera to the bounds of the newly added markers
```kotlin
private fun addMarkersToMap(data: FeatureCollection) {
val bounds = mutableListOf()
// Get bitmaps for marker icon
val infoIconDrawable = ResourcesCompat.getDrawable(
this.resources,
// Intentionally specify package name
// This makes copy from another project easier
org.maplibre.android.R.drawable.maplibre_info_icon_default,
theme
)!!
val bitmapBlue = infoIconDrawable.toBitmap()
val bitmapRed = infoIconDrawable
.mutate()
.apply { setTint(Color.RED) }
.toBitmap()
// Add symbol for each point feature
data.features()?.forEach { feature ->
val geometry = feature.geometry()?.toJson() ?: return@forEach
val point = Point.fromJson(geometry) ?: return@forEach
val latLng = LatLng(point.latitude(), point.longitude())
bounds.add(latLng)
// Contents in InfoWindow of each marker
val title = feature.getStringProperty("title")
val epochTime = feature.getNumberProperty("time")
val dateString = SimpleDateFormat("yyyy/MM/dd HH:mm", Locale.TAIWAN).format(epochTime)
// If magnitude > 6.0, show marker with red icon. If not, show blue icon instead
val mag = feature.getNumberProperty("mag")
val icon = IconFactory.getInstance(this)
.fromBitmap(if (mag.toFloat() > 6.0) bitmapRed else bitmapBlue)
// Use MarkerOptions and addMarker() to add a new marker in map
val markerOptions = MarkerOptions()
.position(latLng)
.title(dateString)
.snippet(title)
.icon(icon)
maplibreMap.addMarker(markerOptions)
}
// Move camera to newly added annotations
maplibreMap.getCameraForLatLngBounds(LatLngBounds.fromLatLngs(bounds))?.let {
val newCameraPosition = CameraPosition.Builder()
.target(it.target)
.zoom(it.zoom - 0.5)
.build()
maplibreMap.cameraPosition = newCameraPosition
}
}
```
[//]: # (7. Here is the final result. For the full contents of `JsonApiActivity`, please visit source code of our [Test App].)
[//]: # ()
[//]: # ()
[//]: # (
)
[//]: # (
)
[//]: # ( )
[//]: # ( )
[//]: # ( )
### Ease
The `MapLibreMap.moveCamera` eases to the camera position provided (with constant ground speed).
```kotlin
val cameraPosition =
CameraPosition.Builder()
.target(nextLatLng)
.zoom(15.0)
.bearing(180.0)
.tilt(30.0)
.build()
maplibreMap.easeCamera(
CameraUpdateFactory.newCameraPosition(cameraPosition),
7500,
callback
)
```
[//]: # ()
[//]: # ( )
[//]: # ( )
[//]: # ( )
### Animate
The `MapLibreMap.animateCamera` uses a powered flight animation move to the camera position provided[^1].
[^1]: The implementation is based on Van Wijk, Jarke J.; Nuij, Wim A. A. “Smooth and efficient zooming and panning.” INFOVIS ’03. pp. 15–22. [https://www.win.tue.nl/~vanwijk/zoompan.pdf#page=5](https://www.win.tue.nl/~vanwijk/zoompan.pdf#page=5)
```kotlin
val cameraPosition =
CameraPosition.Builder().target(nextLatLng).bearing(270.0).tilt(20.0).build()
maplibreMap.animateCamera(
CameraUpdateFactory.newCameraPosition(cameraPosition),
7500,
callback
)
```
[//]: # ()
[//]: # ( )
[//]: # ( )
[//]: # ( )
## Animation Callbacks
In the previous section a `CancellableCallback` was passed to the last two animation methods. This callback shows a toast message when the animation is cancelled or when it is finished.
```kotlin
private val callback: CancelableCallback =
object : CancelableCallback {
override fun onCancel() {
Timber.i("Duration onCancel Callback called.")
Toast.makeText(
applicationContext,
"Ease onCancel Callback called.",
Toast.LENGTH_LONG
)
.show()
}
override fun onFinish() {
Timber.i("Duration onFinish Callback called.")
Toast.makeText(
applicationContext,
"Ease onFinish Callback called.",
Toast.LENGTH_LONG
)
.show()
}
}
```
---
# Animator Animation
https://docs.mapatlas.xyz/overview/sdk/android-native/camera/animator-animation
# Animator Animation
This example showcases how to use the Animator API to schedule a sequence of map animations.
```kotlin title="CameraAnimatorActivity.kt"
/** Test activity showcasing using Android SDK animators to animate camera position changes. */
class CameraAnimatorActivity : AppCompatActivity(), OnMapReadyCallback {
private val animators = LongSparseArray()
private lateinit var set: Animator
private lateinit var mapView: MapView
private lateinit var maplibreMap: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_camera_animator)
mapView = findViewById(R.id.mapView) as MapView
if (::mapView.isInitialized) {
mapView.onCreate(savedInstanceState)
mapView.getMapAsync(this)
}
}
override fun onMapReady(map: MapLibreMap) {
maplibreMap = map
map.setStyle(TestStyles.getPredefinedStyleWithFallback("Streets"))
initFab()
}
private fun initFab() {
findViewById(R.id.fab).setOnClickListener { view: View ->
view.visibility = View.GONE
val animatedPosition =
CameraPosition.Builder()
.target(LatLng(37.789992, -122.402214))
.tilt(60.0)
.zoom(14.5)
.bearing(135.0)
.build()
set = createExampleAnimator(maplibreMap.cameraPosition, animatedPosition)
set.start()
}
}
//
// Animator API used for the animation on the FAB
//
private fun createExampleAnimator(
currentPosition: CameraPosition,
targetPosition: CameraPosition
): Animator {
val animatorSet = AnimatorSet()
animatorSet.play(createLatLngAnimator(currentPosition.target!!, targetPosition.target!!))
animatorSet.play(createZoomAnimator(currentPosition.zoom, targetPosition.zoom))
animatorSet.play(createBearingAnimator(currentPosition.bearing, targetPosition.bearing))
animatorSet.play(createTiltAnimator(currentPosition.tilt, targetPosition.tilt))
return animatorSet
}
private fun createLatLngAnimator(currentPosition: LatLng, targetPosition: LatLng): Animator {
val latLngAnimator =
ValueAnimator.ofObject(LatLngEvaluator(), currentPosition, targetPosition)
latLngAnimator.duration = (1000 * ANIMATION_DELAY_FACTOR).toLong()
latLngAnimator.interpolator = FastOutSlowInInterpolator()
latLngAnimator.addUpdateListener { animation: ValueAnimator ->
maplibreMap.moveCamera(
CameraUpdateFactory.newLatLng((animation.animatedValue as LatLng))
)
}
return latLngAnimator
}
private fun createZoomAnimator(currentZoom: Double, targetZoom: Double): Animator {
val zoomAnimator = ValueAnimator.ofFloat(currentZoom.toFloat(), targetZoom.toFloat())
zoomAnimator.duration = (2200 * ANIMATION_DELAY_FACTOR).toLong()
zoomAnimator.startDelay = (600 * ANIMATION_DELAY_FACTOR).toLong()
zoomAnimator.interpolator = AnticipateOvershootInterpolator()
zoomAnimator.addUpdateListener { animation: ValueAnimator ->
maplibreMap.moveCamera(
CameraUpdateFactory.zoomTo((animation.animatedValue as Float).toDouble())
)
}
return zoomAnimator
}
private fun createBearingAnimator(currentBearing: Double, targetBearing: Double): Animator {
val bearingAnimator =
ValueAnimator.ofFloat(currentBearing.toFloat(), targetBearing.toFloat())
bearingAnimator.duration = (1000 * ANIMATION_DELAY_FACTOR).toLong()
bearingAnimator.startDelay = (1000 * ANIMATION_DELAY_FACTOR).toLong()
bearingAnimator.interpolator = FastOutLinearInInterpolator()
bearingAnimator.addUpdateListener { animation: ValueAnimator ->
maplibreMap.moveCamera(
CameraUpdateFactory.bearingTo((animation.animatedValue as Float).toDouble())
)
}
return bearingAnimator
}
private fun createTiltAnimator(currentTilt: Double, targetTilt: Double): Animator {
val tiltAnimator = ValueAnimator.ofFloat(currentTilt.toFloat(), targetTilt.toFloat())
tiltAnimator.duration = (1000 * ANIMATION_DELAY_FACTOR).toLong()
tiltAnimator.startDelay = (1500 * ANIMATION_DELAY_FACTOR).toLong()
tiltAnimator.addUpdateListener { animation: ValueAnimator ->
maplibreMap.moveCamera(
CameraUpdateFactory.tiltTo((animation.animatedValue as Float).toDouble())
)
}
return tiltAnimator
}
//
// Interpolator examples
//
private fun obtainExampleInterpolator(menuItemId: Int): Animator? {
return animators[menuItemId.toLong()]
}
override fun onCreateOptionsMenu(menu: Menu): Boolean {
menuInflater.inflate(R.menu.menu_animator, menu)
return true
}
override fun onOptionsItemSelected(item: MenuItem): Boolean {
if (!::maplibreMap.isInitialized) {
return false
}
if (item.itemId != android.R.id.home) {
findViewById(R.id.fab).visibility = View.GONE
resetCameraPosition()
playAnimation(item.itemId)
}
return super.onOptionsItemSelected(item)
}
private fun resetCameraPosition() {
maplibreMap.moveCamera(
CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder()
.target(START_LAT_LNG)
.zoom(11.0)
.bearing(0.0)
.tilt(0.0)
.build()
)
)
}
private fun playAnimation(itemId: Int) {
val animator = obtainExampleInterpolator(itemId)
if (animator != null) {
animator.cancel()
animator.start()
}
}
private fun obtainExampleInterpolator(interpolator: Interpolator, duration: Long): Animator {
val zoomAnimator = ValueAnimator.ofFloat(11.0f, 16.0f)
zoomAnimator.duration = (duration * ANIMATION_DELAY_FACTOR).toLong()
zoomAnimator.interpolator = interpolator
zoomAnimator.addUpdateListener { animation: ValueAnimator ->
maplibreMap.moveCamera(
CameraUpdateFactory.zoomTo((animation.animatedValue as Float).toDouble())
)
}
return zoomAnimator
}
//
// MapView lifecycle
//
override fun onStart() {
super.onStart()
mapView.onStart()
}
override fun onResume() {
super.onResume()
mapView.onResume()
}
override fun onPause() {
super.onPause()
mapView.onPause()
}
override fun onStop() {
super.onStop()
mapView.onStop()
for (i in 0 until animators.size()) {
animators[animators.keyAt(i)]!!.cancel()
}
if (this::set.isInitialized) {
set.cancel()
}
}
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
override fun onDestroy() {
super.onDestroy()
if (::mapView.isInitialized) {
mapView.onDestroy()
}
}
override fun onLowMemory() {
super.onLowMemory()
if (::mapView.isInitialized) {
mapView.onLowMemory()
}
}
/** Helper class to evaluate LatLng objects with a ValueAnimator */
private class LatLngEvaluator : TypeEvaluator {
private val latLng = LatLng()
override fun evaluate(fraction: Float, startValue: LatLng, endValue: LatLng): LatLng {
latLng.latitude = startValue.latitude + (endValue.latitude - startValue.latitude) * fraction
latLng.longitude = startValue.longitude + (endValue.longitude - startValue.longitude) * fraction
return latLng
}
}
companion object {
private const val ANIMATION_DELAY_FACTOR = 1.5
private val START_LAT_LNG = LatLng(37.787947, -122.407432)
}
init {
val accelerateDecelerateAnimatorSet = AnimatorSet()
accelerateDecelerateAnimatorSet.playTogether(
createLatLngAnimator(START_LAT_LNG, LatLng(37.826715, -122.422795)),
obtainExampleInterpolator(FastOutSlowInInterpolator(), 2500)
)
animators.put(
R.id.menu_action_accelerate_decelerate_interpolator.toLong(),
accelerateDecelerateAnimatorSet
)
val bounceAnimatorSet = AnimatorSet()
bounceAnimatorSet.playTogether(
createLatLngAnimator(START_LAT_LNG, LatLng(37.787947, -122.407432)),
obtainExampleInterpolator(BounceInterpolator(), 3750)
)
animators.put(R.id.menu_action_bounce_interpolator.toLong(), bounceAnimatorSet)
animators.put(
R.id.menu_action_anticipate_overshoot_interpolator.toLong(),
obtainExampleInterpolator(AnticipateOvershootInterpolator(), 2500)
)
animators.put(
R.id.menu_action_path_interpolator.toLong(),
obtainExampleInterpolator(
PathInterpolatorCompat.create(.22f, .68f, 0f, 1.71f),
2500
)
)
}
}
```
---
# CameraPosition Capabilities
https://docs.mapatlas.xyz/overview/sdk/android-native/camera/cameraposition
# CameraPosition Capabilities
[//]: # ({{ activity_source_note("CameraPositionActivity.kt") }})
[//]: # (This example showcases how to listen to camera change events.)
[//]: # ()
[//]: # ()
[//]: # ( )
[//]: # ( )
[//]: # ( )
The camera animation is kicked off with this code:
```kotlin
val cameraPosition = CameraPosition.Builder().target(LatLng(latitude, longitude)).zoom(zoom).bearing(bearing).tilt(tilt).build()
maplibreMap?.animateCamera(
CameraUpdateFactory.newCameraPosition(cameraPosition),
5000,
object : CancelableCallback {
override fun onCancel() {
Timber.v("OnCancel called")
}
override fun onFinish() {
Timber.v("OnFinish called")
}
}
)
```
Notice how the color of the button in the bottom right changes color. Depending on the state of the camera.
We can listen for changes to the state of the camera by registering a `OnCameraMoveListener`, `OnCameraIdleListener`, `OnCameraMoveCanceledListener` or `OnCameraMoveStartedListener` with the `MapLibreMap`. For example, the `OnCameraMoveListener` is defined with:
```kotlin
private val moveListener = OnCameraMoveListener {
Timber.e("OnCameraMove")
fab.setColorFilter(
ContextCompat.getColor(this@CameraPositionActivity, android.R.color.holo_orange_dark)
)
}
```
And registered with:
```kotlin
maplibreMap.addOnCameraMoveListener(moveListener)
```
Refer to the full example to learn the methods to register the other types of camera change events.
---
# Gesture Detector
https://docs.mapatlas.xyz/overview/sdk/android-native/camera/gesture-detector
# Gesture Detector
The gesture detector of MapMetrics Android is encapsulated in the [`mapmetrics-gestures-android`](https://github.com/MapMetrics/MapMetrics-gestures-android) package.
#### Gesture Listeners
You can add listeners for move, rotate, scale and shove gestures. For example, adding a move gesture listener with `MapLibreMap.addOnRotateListener`:
```kotlin
maplibreMap.addOnMoveListener(
object : OnMoveListener {
override fun onMoveBegin(detector: MoveGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_START, "MOVE START")
)
}
override fun onMove(detector: MoveGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_PROGRESS, "MOVE PROGRESS")
)
}
override fun onMoveEnd(detector: MoveGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_END, "MOVE END")
)
recalculateFocalPoint()
}
}
)
```
Refer to the full example below for examples of listeners for the other gesture types.
#### Settings
You can access an `UISettings` object via `MapLibreMap.uiSettings`. Available settings include:
- **Toggle Quick Zoom**. You can double tap on the map to use quick zoom. You can toggle this behavior on and off (`UiSettings.isQuickZoomGesturesEnabled`).
- **Toggle Velocity Animations**. By default flicking causes the map to continue panning (while decelerating). You can turn this off with `UiSettings.isScaleVelocityAnimationEnabled`.
- **Toggle Rotate Enabled**. Use `uiSettings.isRotateGesturesEnabled`.
- **Toggle Zoom Enabled**. Use `uiSettings.isZoomGesturesEnabled`.
## Full Example Activity
```kotlin title="GestureDetectorActivity.kt"
/** Test activity showcasing APIs around gestures implementation. */
class GestureDetectorActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var maplibreMap: MapLibreMap
private lateinit var recyclerView: RecyclerView
private var gestureAlertsAdapter: GestureAlertsAdapter? = null
private var gesturesManager: AndroidGesturesManager? = null
private var marker: Marker? = null
private var focalPointLatLng: LatLng? = null
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_gesture_detector)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { map: MapLibreMap ->
maplibreMap = map
maplibreMap.setStyle(TestStyles.getPredefinedStyleWithFallback("Streets"))
initializeMap()
}
recyclerView = findViewById(R.id.alerts_recycler)
recyclerView.setLayoutManager(LinearLayoutManager(this))
gestureAlertsAdapter = GestureAlertsAdapter()
recyclerView.setAdapter(gestureAlertsAdapter)
}
override fun onResume() {
super.onResume()
mapView.onResume()
}
override fun onPause() {
super.onPause()
gestureAlertsAdapter!!.cancelUpdates()
mapView.onPause()
}
override fun onStart() {
super.onStart()
mapView.onStart()
}
override fun onStop() {
super.onStop()
mapView.onStop()
}
override fun onLowMemory() {
super.onLowMemory()
mapView.onLowMemory()
}
override fun onDestroy() {
super.onDestroy()
mapView.onDestroy()
}
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
private fun initializeMap() {
gesturesManager = maplibreMap.gesturesManager
val layoutParams = recyclerView.layoutParams as RelativeLayout.LayoutParams
layoutParams.height = (mapView.height / 1.75).toInt()
layoutParams.width = mapView.width / 3
recyclerView.layoutParams = layoutParams
attachListeners()
fixedFocalPointEnabled(maplibreMap.uiSettings.focalPoint != null)
}
fun attachListeners() {
// # --8<-- [start:addOnMoveListener]
maplibreMap.addOnMoveListener(
object : OnMoveListener {
override fun onMoveBegin(detector: MoveGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_START, "MOVE START")
)
}
override fun onMove(detector: MoveGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_PROGRESS, "MOVE PROGRESS")
)
}
override fun onMoveEnd(detector: MoveGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_END, "MOVE END")
)
recalculateFocalPoint()
}
}
)
// # --8<-- [end:addOnMoveListener]
maplibreMap.addOnRotateListener(
object : OnRotateListener {
override fun onRotateBegin(detector: RotateGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_START, "ROTATE START")
)
}
override fun onRotate(detector: RotateGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_PROGRESS, "ROTATE PROGRESS")
)
recalculateFocalPoint()
}
override fun onRotateEnd(detector: RotateGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_END, "ROTATE END")
)
}
}
)
maplibreMap.addOnScaleListener(
object : OnScaleListener {
override fun onScaleBegin(detector: StandardScaleGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_START, "SCALE START")
)
if (focalPointLatLng != null) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(
GestureAlert.TYPE_OTHER,
"INCREASING MOVE THRESHOLD"
)
)
gesturesManager!!.moveGestureDetector.moveThreshold =
ResourceUtils.convertDpToPx(this@GestureDetectorActivity, 175f)
gestureAlertsAdapter!!.addAlert(
GestureAlert(
GestureAlert.TYPE_OTHER,
"MANUALLY INTERRUPTING MOVE"
)
)
gesturesManager!!.moveGestureDetector.interrupt()
}
recalculateFocalPoint()
}
override fun onScale(detector: StandardScaleGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_PROGRESS, "SCALE PROGRESS")
)
}
override fun onScaleEnd(detector: StandardScaleGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_END, "SCALE END")
)
if (focalPointLatLng != null) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(
GestureAlert.TYPE_OTHER,
"REVERTING MOVE THRESHOLD"
)
)
gesturesManager!!.moveGestureDetector.moveThreshold = 0f
}
}
}
)
maplibreMap.addOnShoveListener(
object : OnShoveListener {
override fun onShoveBegin(detector: ShoveGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_START, "SHOVE START")
)
}
override fun onShove(detector: ShoveGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_PROGRESS, "SHOVE PROGRESS")
)
}
override fun onShoveEnd(detector: ShoveGestureDetector) {
gestureAlertsAdapter!!.addAlert(
GestureAlert(GestureAlert.TYPE_END, "SHOVE END")
)
}
}
)
}
override fun onCreateOptionsMenu(menu: Menu): Boolean {
menuInflater.inflate(R.menu.menu_gestures, menu)
return true
}
override fun onOptionsItemSelected(item: MenuItem): Boolean {
val uiSettings = maplibreMap.uiSettings
when (item.itemId) {
R.id.menu_gesture_focus_point -> {
fixedFocalPointEnabled(focalPointLatLng == null)
return true
}
R.id.menu_gesture_animation -> {
uiSettings.isScaleVelocityAnimationEnabled =
!uiSettings.isScaleVelocityAnimationEnabled
uiSettings.isRotateVelocityAnimationEnabled =
!uiSettings.isRotateVelocityAnimationEnabled
uiSettings.isFlingVelocityAnimationEnabled =
!uiSettings.isFlingVelocityAnimationEnabled
return true
}
R.id.menu_gesture_rotate -> {
uiSettings.isRotateGesturesEnabled = !uiSettings.isRotateGesturesEnabled
return true
}
R.id.menu_gesture_tilt -> {
uiSettings.isTiltGesturesEnabled = !uiSettings.isTiltGesturesEnabled
return true
}
R.id.menu_gesture_zoom -> {
uiSettings.isZoomGesturesEnabled = !uiSettings.isZoomGesturesEnabled
return true
}
R.id.menu_gesture_scroll -> {
uiSettings.isScrollGesturesEnabled = !uiSettings.isScrollGesturesEnabled
return true
}
R.id.menu_gesture_double_tap -> {
uiSettings.isDoubleTapGesturesEnabled = !uiSettings.isDoubleTapGesturesEnabled
return true
}
R.id.menu_gesture_quick_zoom -> {
uiSettings.isQuickZoomGesturesEnabled = !uiSettings.isQuickZoomGesturesEnabled
return true
}
R.id.menu_gesture_scroll_horizontal -> {
uiSettings.isHorizontalScrollGesturesEnabled =
!uiSettings.isHorizontalScrollGesturesEnabled
return true
}
}
return super.onOptionsItemSelected(item)
}
private fun fixedFocalPointEnabled(enabled: Boolean) {
if (enabled) {
focalPointLatLng = LatLng(51.50325, -0.12968)
marker = maplibreMap.addMarker(MarkerOptions().position(focalPointLatLng))
maplibreMap.easeCamera(
CameraUpdateFactory.newLatLngZoom(focalPointLatLng!!, 16.0),
object : CancelableCallback {
override fun onCancel() {
recalculateFocalPoint()
}
override fun onFinish() {
recalculateFocalPoint()
}
}
)
} else {
if (marker != null) {
maplibreMap.removeMarker(marker!!)
marker = null
}
focalPointLatLng = null
maplibreMap.uiSettings.focalPoint = null
}
}
private fun recalculateFocalPoint() {
if (focalPointLatLng != null) {
maplibreMap.uiSettings.focalPoint =
maplibreMap.projection.toScreenLocation(focalPointLatLng!!)
}
}
private class GestureAlertsAdapter : RecyclerView.Adapter() {
private var isUpdating = false
private val updateHandler = Handler(Looper.getMainLooper())
private val alerts: MutableList = ArrayList()
class ViewHolder internal constructor(view: View) : RecyclerView.ViewHolder(view) {
var alertMessageTv: TextView
init {
val typeface = FontCache.get("Roboto-Regular.ttf", view.context)
alertMessageTv = view.findViewById(R.id.alert_message)
alertMessageTv.typeface = typeface
}
}
override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): ViewHolder {
val view =
LayoutInflater.from(parent.context)
.inflate(R.layout.item_gesture_alert, parent, false)
return ViewHolder(view)
}
override fun onBindViewHolder(holder: ViewHolder, position: Int) {
val alert = alerts[position]
holder.alertMessageTv.text = alert.message
holder.alertMessageTv.setTextColor(
ContextCompat.getColor(holder.alertMessageTv.context, alert.color)
)
}
override fun getItemCount(): Int {
return alerts.size
}
fun addAlert(alert: GestureAlert) {
for (gestureAlert in alerts) {
if (gestureAlert.alertType != GestureAlert.TYPE_PROGRESS) {
break
}
if (alert.alertType == GestureAlert.TYPE_PROGRESS && gestureAlert == alert) {
return
}
}
if (itemCount >= MAX_NUMBER_OF_ALERTS) {
alerts.removeAt(itemCount - 1)
}
alerts.add(0, alert)
if (!isUpdating) {
isUpdating = true
updateHandler.postDelayed(updateRunnable, 250)
}
}
@SuppressLint("NotifyDataSetChanged")
private val updateRunnable = Runnable {
notifyDataSetChanged()
isUpdating = false
}
fun cancelUpdates() {
updateHandler.removeCallbacksAndMessages(null)
}
}
private class GestureAlert(
@field:Type @param:Type
val alertType: Int,
val message: String?
) {
@Retention(AnnotationRetention.SOURCE)
@IntDef(TYPE_NONE, TYPE_START, TYPE_PROGRESS, TYPE_END, TYPE_OTHER)
annotation class Type
@ColorInt var color = 0
override fun equals(other: Any?): Boolean {
if (this === other) {
return true
}
if (other == null || javaClass != other.javaClass) {
return false
}
val that = other as GestureAlert
if (alertType != that.alertType) {
return false
}
return if (message != null) message == that.message else that.message == null
}
override fun hashCode(): Int {
var result = alertType
result = 31 * result + (message?.hashCode() ?: 0)
return result
}
companion object {
const val TYPE_NONE = 0
const val TYPE_START = 1
const val TYPE_END = 2
const val TYPE_PROGRESS = 3
const val TYPE_OTHER = 4
}
init {
when (alertType) {
TYPE_NONE -> color = android.R.color.black
TYPE_END -> color = android.R.color.holo_red_dark
TYPE_OTHER -> color = android.R.color.holo_purple
TYPE_PROGRESS -> color = android.R.color.holo_orange_dark
TYPE_START -> color = android.R.color.holo_green_dark
}
}
}
companion object {
private const val MAX_NUMBER_OF_ALERTS = 30
}
}
```
---
# LatLngBounds API
https://docs.mapatlas.xyz/overview/sdk/android-native/camera/lat-lng-bounds
# LatLngBounds API
[//]: # ({{ activity_source_note("LatLngBoundsActivity.kt") }})
[//]: # (This example demonstrates setting the camera to some bounds defined by some features. It sets these bounds when the map is initialized and when the [bottom sheet](https://m2.material.io/components/sheets-bottom) is opened or closed.)
[//]: # ()
[//]: # ()
[//]: # ( )
[//]: # ( )
[//]: # ( )
Here you can see how the feature collection is loaded and how `MapLibreMap.getCameraForLatLngBounds` is used to set the bounds during map initialization:
```kotlin
val featureCollection: FeatureCollection =
fromJson(GeoParseUtil.loadStringFromAssets(this, "points-sf.geojson"))
bounds = createBounds(featureCollection)
map.getCameraForLatLngBounds(bounds, createPadding(peekHeight))?.let {
map.cameraPosition = it
}
```
The `createBounds` function uses the `LatLngBounds` API to include all points within the bounds:
```kotlin
private fun createBounds(featureCollection: FeatureCollection): LatLngBounds {
val boundsBuilder = LatLngBounds.Builder()
featureCollection.features()?.let {
for (feature in it) {
val point = feature.geometry() as Point
boundsBuilder.include(LatLng(point.latitude(), point.longitude()))
}
}
return boundsBuilder.build()
}
```
---
# Max/Min Zoom
https://docs.mapatlas.xyz/overview/sdk/android-native/camera/max-min-zoom
# Max/Min Zoom
[//]: # ({{ activity_source_note("MaxMinZoomActivity.kt") }})
This example shows how to configure a maximum and a minimum zoom level.
```kotlin
maplibreMap.setMinZoomPreference(3.0)
maplibreMap.setMaxZoomPreference(5.0)
```
## Bonus: Add Click Listener
As a bonus, this example also shows how you can define a click listener to the map.
```kotlin
maplibreMap.addOnMapClickListener {
if (this::maplibreMap.isInitialized) {
maplibreMap.setStyle(Style.Builder().fromUri(TestStyles.AMERICANA))
}
true
}
```
You can remove a click listener again with `MapLibreMap.removeOnMapClickListener`. To use this API you need to assign the click listener to a variable, since you need to pass the listener to that method.
[//]: # ()
[//]: # ( )
[//]: # ( )
[//]: # ( {{ openmaptiles_caption }})
[//]: # ( )
---
# Scroll by Method
https://docs.mapatlas.xyz/overview/sdk/android-native/camera/move-map-pixels
# Scroll by Method
[//]: # ({{ activity_source_note("ScrollByActivity.kt") }})
This example shows how you can move the map by x/y pixels.
```kotlin
maplibreMap.scrollBy(
(seekBarX.progress * MULTIPLIER_PER_PIXEL).toFloat(),
(seekBarY.progress * MULTIPLIER_PER_PIXEL).toFloat()
)
```
[//]: # ()
[//]: # ( { width="300" })
[//]: # ( )
---
# Animate Camera Orbiting a Point
https://docs.mapatlas.xyz/overview/sdk/android-native/camera/orbit-animation
# Animate Camera Orbiting a Point
This tutorial shows how to create a smooth orbiting camera animation that rotates around a central point — great for showcasing landmarks or creating cinematic map experiences.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Basic Orbit Animation
Rotate the camera 360° around a point:
```kotlin
import android.animation.ValueAnimator
import android.os.Bundle
import android.view.animation.LinearInterpolator
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.camera.CameraUpdateFactory
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class OrbitActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
private var orbitAnimator: ValueAnimator? = null
private val center = LatLng(48.8584, 2.2945) // Eiffel Tower
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_orbit)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
)
// Set initial camera with tilt
map.cameraPosition = CameraPosition.Builder()
.target(center)
.zoom(16.0)
.tilt(55.0)
.bearing(0.0)
.build()
// Start orbit button
findViewById(R.id.btnOrbit).setOnClickListener {
startOrbit()
}
// Stop button
findViewById(R.id.btnStop).setOnClickListener {
stopOrbit()
}
}
}
private fun startOrbit() {
orbitAnimator?.cancel()
val startBearing = map.cameraPosition.bearing
orbitAnimator = ValueAnimator.ofFloat(0f, 360f).apply {
duration = 20000 // 20 seconds for full rotation
interpolator = LinearInterpolator()
repeatCount = ValueAnimator.INFINITE
addUpdateListener { animation ->
val bearing = startBearing + (animation.animatedValue as Float)
map.moveCamera(
CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder()
.target(center)
.zoom(16.0)
.tilt(55.0)
.bearing(bearing.toDouble() % 360)
.build()
)
)
}
start()
}
}
private fun stopOrbit() {
orbitAnimator?.cancel()
orbitAnimator = null
}
override fun onDestroy() {
stopOrbit()
super.onDestroy()
mapView.onDestroy()
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Orbit with Zoom Breathing
Add subtle zoom pulsing while orbiting:
```kotlin
import android.animation.AnimatorSet
private fun startBreathingOrbit() {
// Bearing rotation
val bearingAnimator = ValueAnimator.ofFloat(0f, 360f).apply {
duration = 20000
interpolator = LinearInterpolator()
repeatCount = ValueAnimator.INFINITE
}
// Zoom breathing (zoom in and out gently)
val zoomAnimator = ValueAnimator.ofFloat(15.5f, 16.5f).apply {
duration = 5000
repeatMode = ValueAnimator.REVERSE
repeatCount = ValueAnimator.INFINITE
}
// Combined update
var currentBearing = 0f
var currentZoom = 16f
bearingAnimator.addUpdateListener { currentBearing = it.animatedValue as Float }
zoomAnimator.addUpdateListener { currentZoom = it.animatedValue as Float }
// Frame update on bearing changes
bearingAnimator.addUpdateListener {
map.moveCamera(
CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder()
.target(center)
.zoom(currentZoom.toDouble())
.tilt(55.0)
.bearing(currentBearing.toDouble() % 360)
.build()
)
)
}
val animatorSet = AnimatorSet()
animatorSet.playTogether(bearingAnimator, zoomAnimator)
animatorSet.start()
}
```
## Orbit Then Fly Away
Orbit for one revolution then fly to a new location:
```kotlin
private fun orbitThenFlyAway() {
val startBearing = map.cameraPosition.bearing
ValueAnimator.ofFloat(0f, 360f).apply {
duration = 10000
interpolator = LinearInterpolator()
addUpdateListener { animation ->
val bearing = startBearing + (animation.animatedValue as Float)
map.moveCamera(
CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder()
.target(center)
.zoom(16.0)
.tilt(55.0)
.bearing(bearing.toDouble() % 360)
.build()
)
)
}
addListener(object : android.animation.AnimatorListenerAdapter() {
override fun onAnimationEnd(animation: android.animation.Animator) {
// Fly to next location after orbit completes
map.animateCamera(
CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder()
.target(LatLng(48.8738, 2.2950)) // Arc de Triomphe
.zoom(16.0)
.tilt(55.0)
.bearing(0.0)
.build()
),
3000
)
}
})
start()
}
}
```
## Touch-to-Stop Orbit
Stop orbiting when the user touches the map:
```kotlin
private fun startOrbitWithTouchStop() {
startOrbit()
// Stop orbit on any touch
map.addOnCameraMoveStartedListener { reason ->
if (reason == MapLibreMap.OnCameraMoveStartedListener.REASON_API_GESTURE) {
stopOrbit()
}
}
}
```
## Next Steps
- [Animation Types](./animation-types) — Camera animation comparison
- [Camera Position](./cameraposition) — Camera position fundamentals
- [Fly to a Location](../interactions/fly-to-location) — Point-to-point flights
---
**Tip**: Use `moveCamera` (not `animateCamera`) inside the orbit loop — `animateCamera` adds its own easing which conflicts with the `ValueAnimator`. The `ValueAnimator` handles all timing; the camera just needs instant updates each frame.
---
# Set Pitch and Bearing
https://docs.mapatlas.xyz/overview/sdk/android-native/camera/set-pitch-bearing
# Set Pitch and Bearing
This tutorial shows how to control the 3D perspective (pitch/tilt) and compass direction (bearing/rotation) of your MapMetrics Android map.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Set Pitch and Bearing on Load
Configure the initial 3D view:
```kotlin
import android.os.Bundle
import android.widget.Button
import android.widget.SeekBar
import android.widget.TextView
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.camera.CameraUpdateFactory
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class PitchBearingActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_pitch_bearing)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
)
// Set initial 3D perspective
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8584, 2.2945))
.zoom(16.0)
.tilt(60.0) // Pitch: 0 = top-down, 60 = dramatic 3D
.bearing(45.0) // Bearing: 0 = north up, 45 = northeast
.build()
setupControls()
}
}
private fun setupControls() {
val pitchText = findViewById(R.id.tvPitch)
val bearingText = findViewById(R.id.tvBearing)
// Pitch slider (0-60)
findViewById(R.id.seekPitch).apply {
max = 60
progress = map.cameraPosition.tilt.toInt()
setOnSeekBarChangeListener(object : SeekBar.OnSeekBarChangeListener {
override fun onProgressChanged(seekBar: SeekBar?, value: Int, user: Boolean) {
if (!user) return
pitchText.text = "Pitch: $value°"
map.moveCamera(
CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder(map.cameraPosition)
.tilt(value.toDouble())
.build()
)
)
}
override fun onStartTrackingTouch(seekBar: SeekBar?) {}
override fun onStopTrackingTouch(seekBar: SeekBar?) {}
})
}
// Bearing slider (0-360)
findViewById(R.id.seekBearing).apply {
max = 360
progress = map.cameraPosition.bearing.toInt()
setOnSeekBarChangeListener(object : SeekBar.OnSeekBarChangeListener {
override fun onProgressChanged(seekBar: SeekBar?, value: Int, user: Boolean) {
if (!user) return
bearingText.text = "Bearing: $value°"
map.moveCamera(
CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder(map.cameraPosition)
.bearing(value.toDouble())
.build()
)
)
}
override fun onStartTrackingTouch(seekBar: SeekBar?) {}
override fun onStopTrackingTouch(seekBar: SeekBar?) {}
})
}
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Preset Camera Views
Offer buttons for common perspective angles:
```kotlin
private fun setupPresets() {
// Top-down (2D)
findViewById(R.id.btnTopDown).setOnClickListener {
animateTo(tilt = 0.0, bearing = 0.0, zoom = 14.0)
}
// Gentle 3D
findViewById(R.id.btnGentle3d).setOnClickListener {
animateTo(tilt = 30.0, bearing = 0.0, zoom = 15.0)
}
// Dramatic 3D
findViewById(R.id.btnDramatic3d).setOnClickListener {
animateTo(tilt = 60.0, bearing = -30.0, zoom = 16.0)
}
// Street level
findViewById(R.id.btnStreetLevel).setOnClickListener {
animateTo(tilt = 60.0, bearing = 90.0, zoom = 18.0)
}
// Reset to north
findViewById(R.id.btnResetNorth).setOnClickListener {
animateTo(tilt = 0.0, bearing = 0.0, zoom = map.cameraPosition.zoom)
}
}
private fun animateTo(tilt: Double, bearing: Double, zoom: Double) {
map.animateCamera(
CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder()
.target(map.cameraPosition.target)
.zoom(zoom)
.tilt(tilt)
.bearing(bearing)
.build()
),
1500
)
}
```
## Limit Pitch Range via XML
Set pitch limits in the layout:
```xml
)
[//]: # ( )
[//]: # ( )
[//]: # ( )
Each method uses `MapLibreMap.animateCamera`, but with a different `CameraUpdateFactory`.
#### Zooming In
```kotlin
maplibreMap.animateCamera(CameraUpdateFactory.zoomIn())
```
#### Zooming Out
```kotlin
maplibreMap.animateCamera(CameraUpdateFactory.zoomOut())
```
#### Zoom By Some Amount of Zoom Levels
```kotlin
maplibreMap.animateCamera(CameraUpdateFactory.zoomBy(2.0))
```
#### Zoom to a Zoom Level
```kotlin
maplibreMap.animateCamera(CameraUpdateFactory.zoomTo(2.0))
```
#### Zoom to a Point
```kotlin
val view = window.decorView
maplibreMap.animateCamera(
CameraUpdateFactory.zoomBy(
1.0,
Point(view.measuredWidth / 4, view.measuredHeight / 4)
)
)
```
---
# Configuration
https://docs.mapatlas.xyz/overview/sdk/android-native/configuration
# Configuration
This guide will explain various ways to create a map.
When working with maps, you likely want to configure the `MapView`.
There are several ways to build a `MapView`:
1. Using existing XML namespace tags for`MapView` in the layout.
2. Creating `MapLibreMapOptions` and passing builder function values into the `MapView`.
3. Creating a `SupportMapFragment` with the help of `MapLibreMapOptions`.
Before diving into `MapView` configurations, let's understand the capabilities of both XML namespaces and `MapLibreMapOptions`.
Here are some common configurations you can set:
- Map base URI
- Camera settings
- Zoom level
- Pitch
- Gestures
- Compass
- Logo
- Attribution
- Placement of the above elements on the map and more
We will explore how to achieve these configurations in XML layout and programmatically in Activity code, step by step.
### `MapView` Configuration with an XML layout
To configure `MapView` within an XML layout, you need to use the right namespace and provide the necessary data in the layout file.
```xml
```
This can be found in [`activity_map_options_xml.xml`](https://github.com/MapMetrics/mapmetrics-native-sdk/blob/main/platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_fragment.xml).
You can assign any other existing values to the `mapmetrics...` tags. Then, you only need to create `MapView` and `MapLibreMap` objects with a simple setup in the Activity.
```kotlin title="MapOptionsXmlActivity.kt"
/**
* TestActivity demonstrating configuring MapView with XML
*/
class MapOptionsXmlActivity : AppCompatActivity(), OnMapReadyCallback {
private lateinit var mapView: MapView
private lateinit var maplibreMap: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map_options_xml)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync(this)
}
override fun onMapReady(maplibreMap: MapLibreMap) {
this.maplibreMap = maplibreMap
this.maplibreMap.setStyle(TestStyles.getMapMetricsStyle())
}
override fun onStart() {
super.onStart()
mapView.onStart()
}
override fun onResume() {
super.onResume()
mapView.onResume()
}
override fun onPause() {
super.onPause()
mapView.onPause()
}
override fun onStop() {
super.onStop()
mapView.onStop()
}
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
override fun onDestroy() {
super.onDestroy()
mapView.onDestroy()
}
override fun onLowMemory() {
super.onLowMemory()
mapView.onLowMemory()
}
}
```
This can be found in [`MapOptionsXmlActivity.kt`](https://github.com/MapMetrics/mapmetrics-native-sdk/blob/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsXmlActivity.kt).
### `MapView` configuration with `MapLibreMapOptions`
Here we don't have to create MapView from XML since we want to create it programmatically.
```xml
(R.id.container) as ViewGroup).addView(mapView)
}
override fun onMapReady(maplibreMap: MapLibreMap) {
this.maplibreMap = maplibreMap
this.maplibreMap.setStyle(TestStyles.getMapMetricsStyle())
}
override fun onStart() {
super.onStart()
mapView.onStart()
}
override fun onResume() {
super.onResume()
mapView.onResume()
}
override fun onPause() {
super.onPause()
mapView.onPause()
}
override fun onStop() {
super.onStop()
mapView.onStop()
}
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
override fun onDestroy() {
super.onDestroy()
mapView.onDestroy()
}
override fun onLowMemory() {
super.onLowMemory()
mapView.onLowMemory()
}
}
```
This can be found in [`MapOptionsRuntimeActivity.kt`](https://github.com/MapMetrics/mapmetrics-native-sdk/blob/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsRuntimeActivity.kt).
[//]: # (Finally you will see a result similar to this:)
[//]: # ()
[//]: # ()
[//]: # (
)
[//]: # (
)
[//]: # ( ![Screenshot of road overlay from vector tile source]({{ s3_url("vectortilesource.png") }}){ width="400" })
[//]: # ( {{ openmaptiles_caption() }})
[//]: # ( )
---
# PMTiles
https://docs.mapatlas.xyz/overview/sdk/android-native/data/PMTiles
# PMTiles
Starting MapMetrics Android, using [PMTiles](https://docs.protomaps.com/pmtiles/) as a data source is supported. You can prefix your vector tile source with `pmtiles://` to load a PMTiles file. The rest of the URL continue with be `https://` to load a remote PMTiles file, `asset://` to load an asset or `file://` to load a local PMTiles file.
Oliver Wipfli has made a style available that combines a Protomaps basemap together with Foursquare POI dataset. It is available in the [wipfli/foursquare-os-places-pmtiles](https://github.com/wipfli/foursquare-os-places-pmtiles) repository on GitHub. The style to use is
```
https://raw.githubusercontent.com/wipfli/foursquare-os-places-pmtiles/refs/heads/main/style.json
```
The neat thing about this style is that it only uses PMTiles vector sources. PMTiles can be hosted with a relatively simple file server (or file hosting service) instead of a more complex specialized tile server.
[//]: # ()
[//]: # ( ![Screenshot of PMTiles based style using Protomaps basemap with Foursquare POIs]({{ s3_url("pmtiles-demo.png") }}){ width="300" })
[//]: # ( )
---
# Load GeoJSON from a URL
https://docs.mapatlas.xyz/overview/sdk/android-native/data/geojson-from-url
# Load GeoJSON from a URL
This tutorial shows how to load GeoJSON data from a remote URL and display it on your MapMetrics Android map — useful for loading dynamic datasets, APIs, and external data feeds.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Load GeoJSON from URL
Load and display a remote GeoJSON file:
```kotlin
import android.graphics.Color
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
import org.maplibre.android.style.layers.CircleLayer
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.sources.GeoJsonSource
import java.net.URI
class GeoJsonUrlActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
loadGeoJsonFromUrl(style)
}
}
}
private fun loadGeoJsonFromUrl(style: Style) {
// Load GeoJSON directly from a URL
val geoJsonUrl = "https://gateway.mapmetrics-atlas.net/assets/earthquakes.geojson"
style.addSource(
GeoJsonSource("remote-data", URI(geoJsonUrl))
)
// Visualize as colored circles
style.addLayer(
CircleLayer("data-layer", "remote-data")
.withProperties(
circleRadius(6f),
circleColor(Color.parseColor("#FF6B35")),
circleStrokeColor(Color.WHITE),
circleStrokeWidth(1f)
)
)
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(20.0, 0.0))
.zoom(2.0)
.build()
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Load from an API with Coroutines
Fetch JSON from a REST API, then display:
```kotlin
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import org.maplibre.geojson.FeatureCollection
import java.net.HttpURLConnection
import java.net.URL
private fun loadFromApi(style: Style) {
// Add empty source first
val source = GeoJsonSource("api-data")
style.addSource(source)
// Add layer
style.addLayer(
CircleLayer("api-layer", "api-data")
.withProperties(
circleRadius(5f),
circleColor(Color.parseColor("#4285F4")),
circleStrokeColor(Color.WHITE),
circleStrokeWidth(1f)
)
)
// Fetch data asynchronously
lifecycleScope.launch {
val geoJson = withContext(Dispatchers.IO) {
fetchGeoJson("https://api.example.com/data.geojson")
}
geoJson?.let {
val featureCollection = FeatureCollection.fromJson(it)
source.setGeoJson(featureCollection)
}
}
}
private fun fetchGeoJson(urlString: String): String? {
return try {
val url = URL(urlString)
val connection = url.openConnection() as HttpURLConnection
connection.requestMethod = "GET"
connection.connectTimeout = 10000
connection.readTimeout = 10000
if (connection.responseCode == HttpURLConnection.HTTP_OK) {
connection.inputStream.bufferedReader().readText()
} else null
} catch (e: Exception) {
e.printStackTrace()
null
}
}
```
## Load from Local Assets
Load a GeoJSON file bundled in `assets/`:
```kotlin
private fun loadFromAssets(style: Style) {
// Read from assets/data/places.geojson
val json = assets.open("data/places.geojson")
.bufferedReader()
.readText()
val featureCollection = FeatureCollection.fromJson(json)
style.addSource(GeoJsonSource("local-data", featureCollection))
style.addLayer(
CircleLayer("local-layer", "local-data")
.withProperties(
circleRadius(6f),
circleColor(Color.parseColor("#34A853"))
)
)
}
```
## Refresh Data Periodically
Update GeoJSON data on a timer:
```kotlin
import android.os.Handler
import android.os.Looper
private val refreshHandler = Handler(Looper.getMainLooper())
private val refreshInterval = 30000L // 30 seconds
private fun startAutoRefresh(style: Style) {
val source = style.getSource("remote-data") as? GeoJsonSource ?: return
val refreshRunnable = object : Runnable {
override fun run() {
lifecycleScope.launch {
val json = withContext(Dispatchers.IO) {
fetchGeoJson("https://api.example.com/live-data.geojson")
}
json?.let {
source.setGeoJson(FeatureCollection.fromJson(it))
}
}
refreshHandler.postDelayed(this, refreshInterval)
}
}
refreshHandler.postDelayed(refreshRunnable, refreshInterval)
}
override fun onDestroy() {
refreshHandler.removeCallbacksAndMessages(null)
super.onDestroy()
mapView.onDestroy()
}
```
## GeoJSON Source Options
| Constructor | Description |
|------------|-------------|
| `GeoJsonSource(id, URI)` | Load from URL (auto-fetches) |
| `GeoJsonSource(id, FeatureCollection)` | Load from parsed data |
| `GeoJsonSource(id, String)` | Load from raw JSON string |
| `GeoJsonSource(id, Geometry)` | Load single geometry |
| `GeoJsonSource(id, URI, GeoJsonOptions)` | URL with clustering options |
## Next Steps
- [GeoJSON Guide](../geojson-guide) — GeoJSON fundamentals
- [Multiple Sources](./multiple-sources) — Combining multiple data sources
- [Filter Features](../styling/filter-features) — Filter loaded data
---
**Tip**: `GeoJsonSource(id, URI)` handles network fetching automatically on a background thread. For simple static URLs, this is the easiest approach. Use the coroutine method when you need custom headers, authentication, or error handling.
---
# Combine Multiple Data Sources
https://docs.mapatlas.xyz/overview/sdk/android-native/data/multiple-sources
# Combine Multiple Data Sources
This tutorial shows how to load and display data from multiple GeoJSON sources simultaneously on your MapMetrics Android map — useful for layering different datasets like POIs, routes, and zones.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Multiple Sources with Different Layer Types
Add points, lines, and polygons from separate sources:
```kotlin
import android.graphics.Color
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.google.gson.JsonObject
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
import org.maplibre.android.style.layers.CircleLayer
import org.maplibre.android.style.layers.FillLayer
import org.maplibre.android.style.layers.LineLayer
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.sources.GeoJsonSource
import org.maplibre.geojson.*
class MultiSourceActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
addZones(style) // Polygons
addRoutes(style) // Lines
addPointsOfInterest(style) // Points
setCamera()
}
}
}
private fun addZones(style: Style) {
val zone1 = Feature.fromGeometry(
Polygon.fromLngLats(listOf(listOf(
Point.fromLngLat(2.32, 48.87),
Point.fromLngLat(2.35, 48.87),
Point.fromLngLat(2.35, 48.855),
Point.fromLngLat(2.32, 48.855),
Point.fromLngLat(2.32, 48.87),
))),
JsonObject().apply { addProperty("name", "Zone A") }
)
val zone2 = Feature.fromGeometry(
Polygon.fromLngLats(listOf(listOf(
Point.fromLngLat(2.35, 48.855),
Point.fromLngLat(2.38, 48.855),
Point.fromLngLat(2.38, 48.84),
Point.fromLngLat(2.35, 48.84),
Point.fromLngLat(2.35, 48.855),
))),
JsonObject().apply { addProperty("name", "Zone B") }
)
style.addSource(
GeoJsonSource("zones-source",
FeatureCollection.fromFeatures(listOf(zone1, zone2)))
)
// Fill layer for zones
style.addLayer(
FillLayer("zones-fill", "zones-source")
.withProperties(
fillColor(Color.parseColor("#4285F4")),
fillOpacity(0.2f)
)
)
// Outline layer for zones
style.addLayer(
LineLayer("zones-outline", "zones-source")
.withProperties(
lineColor(Color.parseColor("#4285F4")),
lineWidth(2f)
)
)
}
private fun addRoutes(style: Style) {
val route = Feature.fromGeometry(
LineString.fromLngLats(listOf(
Point.fromLngLat(2.3200, 48.8600),
Point.fromLngLat(2.3350, 48.8580),
Point.fromLngLat(2.3500, 48.8560),
Point.fromLngLat(2.3600, 48.8500),
Point.fromLngLat(2.3700, 48.8450),
))
)
style.addSource(
GeoJsonSource("routes-source", FeatureCollection.fromFeature(route))
)
style.addLayer(
LineLayer("routes-layer", "routes-source")
.withProperties(
lineColor(Color.parseColor("#FF6B35")),
lineWidth(4f),
lineOpacity(0.8f)
)
)
}
private fun addPointsOfInterest(style: Style) {
val pois = listOf(
Triple(2.3376, 48.8606, "Louvre Museum"),
Triple(2.3266, 48.8600, "Musée d'Orsay"),
Triple(2.3499, 48.8530, "Notre-Dame"),
Triple(2.3464, 48.8462, "Luxembourg Gardens"),
Triple(2.3532, 48.8619, "Centre Pompidou"),
)
val features = pois.map { (lng, lat, name) ->
Feature.fromGeometry(
Point.fromLngLat(lng, lat),
JsonObject().apply { addProperty("name", name) }
)
}
style.addSource(
GeoJsonSource("pois-source", FeatureCollection.fromFeatures(features))
)
style.addLayer(
CircleLayer("pois-layer", "pois-source")
.withProperties(
circleRadius(8f),
circleColor(Color.parseColor("#34A853")),
circleStrokeColor(Color.WHITE),
circleStrokeWidth(2f)
)
)
}
private fun setCamera() {
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.855, 2.350))
.zoom(13.0)
.build()
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Toggle Layer Visibility
Let users show/hide each data layer:
```kotlin
import android.widget.ToggleButton
import org.maplibre.android.style.layers.Property
private fun setupLayerToggles(style: Style) {
val layerToggles = mapOf(
R.id.btnZones to listOf("zones-fill", "zones-outline"),
R.id.btnRoutes to listOf("routes-layer"),
R.id.btnPois to listOf("pois-layer"),
)
for ((btnId, layerIds) in layerToggles) {
findViewById(btnId).setOnCheckedChangeListener { _, checked ->
for (layerId in layerIds) {
val layer = style.getLayer(layerId)
layer?.setProperties(
visibility(
if (checked) Property.VISIBLE else Property.NONE
)
)
}
}
}
}
```
## Mix Local and Remote Sources
Combine bundled data with API data:
```kotlin
private fun addMixedSources(style: Style) {
// Remote: live data from API
style.addSource(
GeoJsonSource(
"live-data",
java.net.URI("https://api.example.com/live-events.geojson")
)
)
style.addLayer(
CircleLayer("live-layer", "live-data")
.withProperties(
circleRadius(6f),
circleColor(Color.RED)
)
)
// Local: static boundary from assets
val boundaryJson = assets.open("data/city-boundary.geojson")
.bufferedReader().readText()
style.addSource(
GeoJsonSource("boundary", FeatureCollection.fromJson(boundaryJson))
)
style.addLayer(
LineLayer("boundary-layer", "boundary")
.withProperties(
lineColor(Color.parseColor("#333333")),
lineWidth(2f),
lineDasharray(arrayOf(3f, 2f))
)
)
}
```
## Layer Ordering
Control which layers appear on top:
```kotlin
// Add below a specific layer
style.addLayerBelow(fillLayer, "road-label")
// Add above a specific layer
style.addLayerAbove(circleLayer, "zones-fill")
// Typical order (bottom to top):
// 1. Fill layers (zones, polygons)
// 2. Line layers (routes, boundaries)
// 3. Circle/Symbol layers (POIs, markers)
```
## Next Steps
- [GeoJSON from URL](./geojson-from-url) — Loading remote data
- [GeoJSON Guide](../geojson-guide) — GeoJSON fundamentals
- [Filter Features](../styling/filter-features) — Filter visible data
---
**Tip**: Add layers in the correct visual order — fills first, then lines, then points. Use `addLayerBelow` or `addLayerAbove` to insert layers at specific positions in the rendering stack. Points should always be on top so they remain clickable.
---
# Using a GeoJSON Source
https://docs.mapatlas.xyz/overview/sdk/android-native/geojson-guide
# Using a GeoJSON Source
This guide will teach you how to use [`GeoJsonSource`](https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.style.sources/-geo-json-source/index.html) by deep diving into [GeoJSON](https://geojson.org/) file format.
## Goals
After finishing this documentation you should be able to:
1. Understand how `Style`, `Layer`, and `Source` interact with each other.
2. Explore building blocks of GeoJSON data.
3. Use GeoJSON files in constructing `GeoJsonSource`s.
4. Update data at runtime.
## 1. Styles, Layers, and Data source
- A style defines the visual representation of the map such as colors and appearance.
- Layers control how data should be presented to the user.
- Data sources hold actual data and provides layers with it.
Styles consist of collections of layers and a data source. Layers reference data sources. Hence, they require a unique source ID when you construct them.
It would be meaningless if we don't have any data to show, so we need know how to supply data through a data source.
Firstly, we need to understand how to store data and pass it into a data source; therefore, we will discuss GeoJSON in the next session.
## 2. GeoJSON
[GeoJSON](https://geojson.org/) is a JSON file for encoding various geographical data structures.
It defines several JSON objects to represent geospatial information. Typicalle the`.geojson` extension is used for GeoJSON files.
We define the most fundamental objects:
- `Geometry` refers to a single geometric shape that contains one or more coordinates. These shapes are visual objects displayed on a map. A geometry can be one of the following six types:
- Point
- MultiPoint
- LineString
- MultilineString
- Polygon
- MultiPolygon
- `Feautue` is a compound object that combines a single geometry with user-defined attributes, such as name, color.
- `FeatureCollection` is set of features stored in an array. It is a root object that introduces all other features.
A typical GeoJSON structure might look like:
```json
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [125.6, 10.1]
},
"properties": {
"name": "Dinagat Islands"
}
}
```
So far we learned describing geospatial data in GeoJSON files. We will start applying this knowledge into our map applications.
## 3. GeoJsonSource
As we discussed before, map requires some sort data to be rendered. We use different sources such as Vector, Raster and GeoJSON.
We will focus exclusively on `GeoJsonSource` and will not address other sources.
`GeoJsonSource` is a type of source that has a unique `String` ID and GeoJSON data.
There are several ways to construct a `GeoJsonSource`:
- Locally stored files such as assets and raw folders
- Remote services
- Raw string parsed into FeatureCollections objects
- Geometry, Feature, and FeatureCollection objects that map to GeoJSON Base builders
A sample `GeoJsonSource`:
```kotlin
val source = GeoJsonSource("source", featureCollection)
val lineLayer = LineLayer("layer", "source")
.withProperties(
PropertyFactory.lineColor(Color.RED),
PropertyFactory.lineWidth(10f)
)
style.addSource(source)
style.addLayer(lineLayer)
```
Note that you can not simply show data on a map. Layers must reference them. Therefore, you create a layer that gives visual appearance to it.
### Creating GeoJSON sources
There are various ways you can create a `GeoJSONSource`. Some of the options are shown below.
```kotlin title="Loading from local files with assets folder file"
binding.mapView.getMapAsync { map ->
map.moveCamera(CameraUpdateFactory.newLatLngZoom(cameraTarget, cameraZoom))
map.setStyle(
Style.Builder()
.withImage(imageId, imageIcon)
.withSource(GeoJsonSource(sourceId, URI("asset://points-sf.geojson")))
.withLayer(SymbolLayer(layerId, sourceId).withProperties(iconImage(imageId)))
)
}
```
```kotlin title="Loading with raw folder file"
val source: Source = try {
GeoJsonSource("amsterdam-spots", ResourceUtils.readRawResource(this, R.raw.amsterdam))
} catch (ioException: IOException) {
Toast.makeText(
this@RuntimeStyleActivity,
"Couldn't add source: " + ioException.message,
Toast.LENGTH_SHORT
).show()
return
}
maplibreMap.style!!.addSource(source)
var layer: FillLayer? = FillLayer("parksLayer", "amsterdam-spots")
layer!!.setProperties(
PropertyFactory.fillColor(Color.RED),
PropertyFactory.fillOutlineColor(Color.BLUE),
PropertyFactory.fillOpacity(0.3f),
PropertyFactory.fillAntialias(true)
)
```
```kotlin title="Parsing inline JSON"
fun readRawResource(context: Context?, @RawRes rawResource: Int): String {
var json = ""
if (context != null) {
val writer: Writer = StringWriter()
val buffer = CharArray(1024)
context.resources.openRawResource(rawResource).use { `is` ->
val reader: Reader = BufferedReader(InputStreamReader(`is`, "UTF-8"))
var numRead: Int
while (reader.read(buffer).also { numRead = it } != -1) {
writer.write(buffer, 0, numRead)
}
}
json = writer.toString()
}
return json
}
```
```kotlin title="Loading from remote services"
private fun createEarthquakeSource(): GeoJsonSource {
return GeoJsonSource(EARTHQUAKE_SOURCE_ID, URI(EARTHQUAKE_SOURCE_URL))
}
```
```kotlin
companion object {
private const val EARTHQUAKE_SOURCE_URL =
"https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/significant_month.geojson"
private const val EARTHQUAKE_SOURCE_ID = "earthquakes"
private const val HEATMAP_LAYER_ID = "earthquakes-heat"
private const val HEATMAP_LAYER_SOURCE = "earthquakes"
private const val CIRCLE_LAYER_ID = "earthquakes-circle"
}
```
```kotlin title="Parsing string with the fromJson method of FeatureCollection"
return FeatureCollection.fromJson(
"""
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-77.06867337226866,
38.90467655551809
],
[
-77.06233263015747,
38.90479344272695
],
[
-77.06234335899353,
38.906463238984344
],
[
-77.06290125846863,
38.907206285691615
],
[
-77.06364154815674,
38.90684728656818
],
[
-77.06326603889465,
38.90637140121084
],
[
-77.06321239471436,
38.905561553883246
],
[
-77.0691454410553,
38.905436318935635
],
[
-77.06912398338318,
38.90466820642439
],
[
-77.06867337226866,
38.90467655551809
]
]
]
}
}
]
}
""".trimIndent()
).features()!![0].geometry() as Polygon
```
```kotlin title="Creating Geometry, Feature, and FeatureCollections from scratch"
val properties = JsonObject()
properties.addProperty("key1", "value1")
val source = GeoJsonSource(
"test-source",
FeatureCollection.fromFeatures(
arrayOf(
Feature.fromGeometry(Point.fromLngLat(17.1, 51.0), properties),
Feature.fromGeometry(Point.fromLngLat(17.2, 51.0), properties),
Feature.fromGeometry(Point.fromLngLat(17.3, 51.0), properties),
Feature.fromGeometry(Point.fromLngLat(17.4, 51.0), properties)
)
)
)
style.addSource(source)
val visible = Expression.eq(Expression.get("key1"), Expression.literal("value1"))
val invisible = Expression.neq(Expression.get("key1"), Expression.literal("value1"))
val layer = CircleLayer("test-layer", source.id)
.withFilter(visible)
style.addLayer(layer)
```
Note that the GeoJSON objects we discussed earlier have classes defined in the MapMetrics SDK.
Therefore, we can either map JSON objects to regular Java/Kotlin objects or build them directly.
## 4. Updating data at runtime
The key feature of `GeoJsonSource`s is that once we add one, we can set another set of data.
We achieve this using `setGeoJson()` method. For instance, we create a source variable and check if we have not assigned it, then we create a new source object and add it to style; otherwise, we set a different data source:
```kotlin
private fun createFeatureCollection(): FeatureCollection {
val point = if (isInitialPosition) {
Point.fromLngLat(-74.01618140, 40.701745)
} else {
Point.fromLngLat(-73.988097, 40.749864)
}
val properties = JsonObject()
properties.addProperty(KEY_PROPERTY_SELECTED, isSelected)
val feature = Feature.fromGeometry(point, properties)
return FeatureCollection.fromFeatures(arrayOf(feature))
}
```
```kotlin
private fun updateSource(style: Style?) {
val featureCollection = createFeatureCollection()
if (source != null) {
source!!.setGeoJson(featureCollection)
} else {
source = GeoJsonSource(SOURCE_ID, featureCollection)
style!!.addSource(source!!)
}
}
```
See [this guide](styling/animated-symbol-layer.md) for an advanced example that showcases random cars and a passenger on a map updating their positions with smooth animation.
## Summary
GeoJsonSources have their pros and cons. They are most effective when you want to add additional data to your style or provide features like animating objects on your map.
However, working with large datasets can be challenging if you need to manipulate and store data within the app; in such cases, it’s better to use a remote data source.
---
# Quickstart
https://docs.mapatlas.xyz/overview/sdk/android-native/getting-started
# Quickstart
::: warning The Kotlin types are `MapLibre*`, not `MapMetrics*`
The MapMetrics Android SDK is a MapLibre distribution: the artifact is
`org.mapmetrics.android-sdk:mapmetrics-native-sdk`, but the classes inside it
keep their upstream `org.maplibre.android.*` package and their upstream
names. There is **no `MapMetricsMap` class** — the AAR contains no type whose
name starts with `MapMetrics` at all.
| Wrong | Correct |
|---|---|
| `MapMetricsMap` | `org.maplibre.android.maps.MapLibreMap` |
| `MapMetricsMapOptions` | `org.maplibre.android.maps.MapLibreMapOptions` |
| `R.drawable.mapmetrics_*` | `R.drawable.maplibre_*` |
`import org.maplibre.android.maps.MapMetricsMap` will not compile — the
package is real, the class is not. Earlier revisions of these guides used the
`MapMetrics*` spelling throughout (and in places contradicted themselves
within one file); every page has been corrected. "MapMetrics" remains correct
for the product, the portal, the API key and the Maven artifact — just not
for Kotlin type names.
:::
To follow this example from scratch, in Android Studio create a new "Empty Views Activity" and then select "Kotlin" as the language. Select "Groovy DSL" as the build configuration language.
1. If you have an older project, you'll need to add Maven Central to your project-level Gradle file (usually `//build.gradle`). Add `mavenCentral()` to where repositories are already defined in that file, something like this:
```gradle
allprojects {
repositories {
...
mavenCentral()
}
}
```
A newly-created app will likely already have `mavenCentral()` in a top-level `settings.gradle` file, and you won't need to add it.
2. Add the library as a dependency into your module Gradle file (usually `//build.gradle`). The current release is `1.0.3` — see [all released versions](https://central.sonatype.com/artifact/org.mapmetrics.android-sdk/mapmetrics-native-sdk/versions):
```gradle
dependencies {
...
implementation 'org.mapmetrics.android-sdk:mapmetrics-native-sdk:1.0.3'
}
```
3. Sync your Android project with Gradle files.
4. Add a `MapView` to your layout XML file (usually `//src/main/res/layout/activity_main.xml`).
```xml
...
(R.id.info_title)
val snippet = view.findViewById(R.id.info_snippet)
title.text = marker.title
snippet.text = marker.snippet
return view
}
})
```
Custom layout XML (`res/layout/custom_info_window.xml`):
```xml
```
## Info Window Events
Listen for clicks on the info window popup:
```kotlin
// Click on info window
map.setOnInfoWindowClickListener { marker ->
// Navigate to detail screen, open URL, etc.
Toast.makeText(
this,
"Clicked: ${marker.title}",
Toast.LENGTH_SHORT
).show()
}
// Info window opens
map.setOnInfoWindowLongClickListener { marker ->
Toast.makeText(
this,
"Long pressed: ${marker.title}",
Toast.LENGTH_SHORT
).show()
}
// Info window closes
map.setOnInfoWindowCloseListener { marker ->
// Cleanup or state updates
}
```
## Next Steps
- [Add Markers](../annotations/add-markers) — Marker basics and icons
- [Fly to a Location](./fly-to-location) — Camera animation to a point
- [GeoJSON Guide](../geojson-guide) — Loading map data from GeoJSON
---
**Tip**: Info windows only support one open at a time — tapping a new marker automatically closes the previous popup. For multiple simultaneous popups, use a symbol layer with custom label text instead.
---
# Add Custom Image Markers
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/add-image-marker
# Add Custom Image Markers
This tutorial shows how to use custom images (PNG, SVG, drawable) as marker icons on your MapMetrics Android map instead of the default pin.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Custom Icon from Drawable Resource
Use an Android drawable as a marker icon:
```kotlin
import android.graphics.Bitmap
import android.graphics.Canvas
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import androidx.core.content.ContextCompat
import org.maplibre.android.annotations.IconFactory
import org.maplibre.android.annotations.MarkerOptions
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class ImageMarkerActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
addCustomMarkers()
}
}
}
private fun addCustomMarkers() {
val iconFactory = IconFactory.getInstance(this)
// Convert vector drawable to bitmap
val icon = iconFactory.fromBitmap(
drawableToBitmap(R.drawable.ic_custom_pin)
)
map.addMarker(
MarkerOptions()
.position(LatLng(48.8584, 2.2945))
.title("Eiffel Tower")
.icon(icon)
)
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8584, 2.2945))
.zoom(14.0)
.build()
}
private fun drawableToBitmap(drawableRes: Int): Bitmap {
val drawable = ContextCompat.getDrawable(this, drawableRes)!!
val bitmap = Bitmap.createBitmap(
drawable.intrinsicWidth,
drawable.intrinsicHeight,
Bitmap.Config.ARGB_8888
)
val canvas = Canvas(bitmap)
drawable.setBounds(0, 0, canvas.width, canvas.height)
drawable.draw(canvas)
return bitmap
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Different Icons per Category
Assign different icons based on data:
```kotlin
private fun addCategoryMarkers() {
val iconFactory = IconFactory.getInstance(this)
val icons = mapOf(
"restaurant" to iconFactory.fromBitmap(drawableToBitmap(R.drawable.ic_restaurant)),
"museum" to iconFactory.fromBitmap(drawableToBitmap(R.drawable.ic_museum)),
"park" to iconFactory.fromBitmap(drawableToBitmap(R.drawable.ic_park)),
"hotel" to iconFactory.fromBitmap(drawableToBitmap(R.drawable.ic_hotel)),
)
val places = listOf(
Triple(LatLng(48.8584, 2.2945), "Café de Flore", "restaurant"),
Triple(LatLng(48.8606, 2.3376), "Louvre Museum", "museum"),
Triple(LatLng(48.8462, 2.3464), "Luxembourg Gardens", "park"),
Triple(LatLng(48.8680, 2.3280), "Le Meurice", "hotel"),
)
for ((position, name, category) in places) {
map.addMarker(
MarkerOptions()
.position(position)
.title(name)
.snippet(category.replaceFirstChar { it.uppercase() })
.icon(icons[category])
)
}
}
```
## Symbol Layer with Custom Images (Recommended)
For many markers, use a symbol layer for better performance:
```kotlin
import android.graphics.BitmapFactory
import com.google.gson.JsonObject
import org.maplibre.android.style.expressions.Expression.*
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.layers.SymbolLayer
import org.maplibre.android.style.sources.GeoJsonSource
import org.maplibre.geojson.Feature
import org.maplibre.geojson.FeatureCollection
import org.maplibre.geojson.Point
private fun addSymbolLayerMarkers(style: Style) {
// Add images to the style
style.addImage("pin-red", drawableToBitmap(R.drawable.ic_pin_red))
style.addImage("pin-blue", drawableToBitmap(R.drawable.ic_pin_blue))
style.addImage("pin-green", drawableToBitmap(R.drawable.ic_pin_green))
// Create features with an "icon" property
val features = listOf(
createFeature(2.2945, 48.8584, "Eiffel Tower", "pin-red"),
createFeature(2.3376, 48.8606, "Louvre", "pin-blue"),
createFeature(2.3464, 48.8462, "Luxembourg", "pin-green"),
)
style.addSource(
GeoJsonSource("markers-source", FeatureCollection.fromFeatures(features))
)
// Symbol layer — picks icon based on feature property
style.addLayer(
SymbolLayer("markers-layer", "markers-source")
.withProperties(
iconImage(get("icon")), // Use the "icon" property
iconSize(0.8f),
iconAllowOverlap(true),
iconAnchor("bottom"), // Anchor at bottom of icon
textField(get("name")),
textSize(12f),
textOffset(arrayOf(0f, 0.8f)),
textAnchor("top"),
textColor("#333333"),
textHaloColor("#ffffff"),
textHaloWidth(1f)
)
)
}
private fun createFeature(lng: Double, lat: Double, name: String, icon: String): Feature {
val props = JsonObject().apply {
addProperty("name", name)
addProperty("icon", icon)
}
return Feature.fromGeometry(Point.fromLngLat(lng, lat), props)
}
```
## Scaled Marker from Bitmap
Resize a bitmap for consistent marker size:
```kotlin
private fun scaledBitmap(drawableRes: Int, widthDp: Int, heightDp: Int): Bitmap {
val density = resources.displayMetrics.density
val widthPx = (widthDp * density).toInt()
val heightPx = (heightDp * density).toInt()
val original = drawableToBitmap(drawableRes)
return Bitmap.createScaledBitmap(original, widthPx, heightPx, true)
}
// Usage:
val icon = iconFactory.fromBitmap(scaledBitmap(R.drawable.ic_pin, 32, 48))
```
## Next Steps
- [Multiple Markers](./multiple-markers) — Many markers with icons
- [Custom Sprite](../styling/custom-sprite) — Sprite-based icons
- [Animated Symbol Layer](../styling/animated-symbol-layer) — Animated icons
---
**Tip**: For the symbol layer approach, use `iconAnchor("bottom")` for pin-style icons so the tip of the pin aligns with the geographic coordinate. The default anchor is center, which causes pins to appear to float above their position.
---
# Animate a Line Being Drawn
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/animate-line
# Animate a Line Being Drawn
This tutorial shows how to animate a line being progressively drawn on your MapMetrics Android map — great for showing routes, delivery paths, or GPS tracks being traced in real time.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Progressive Line Animation
Draw a line point by point with smooth animation:
```kotlin
import android.animation.ValueAnimator
import android.graphics.Color
import android.os.Bundle
import android.os.Handler
import android.os.Looper
import android.view.animation.LinearInterpolator
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.camera.CameraUpdateFactory
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.geometry.LatLngBounds
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
import org.maplibre.android.style.layers.LineLayer
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.sources.GeoJsonSource
import org.maplibre.geojson.Feature
import org.maplibre.geojson.LineString
import org.maplibre.geojson.Point
class AnimateLineActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
private val routePoints = listOf(
Point.fromLngLat(2.3522, 48.8566), // Paris
Point.fromLngLat(2.3700, 48.8550),
Point.fromLngLat(2.3800, 48.8600),
Point.fromLngLat(2.3900, 48.8580),
Point.fromLngLat(2.4000, 48.8620),
Point.fromLngLat(2.4100, 48.8590),
Point.fromLngLat(2.4200, 48.8640),
Point.fromLngLat(2.4300, 48.8610),
)
private var currentPointIndex = 0
private val handler = Handler(Looper.getMainLooper())
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_animate_line)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
setupLine(style)
// Fit camera to full route
val bounds = LatLngBounds.Builder()
for (point in routePoints) {
bounds.include(LatLng(point.latitude(), point.longitude()))
}
map.easeCamera(
CameraUpdateFactory.newLatLngBounds(bounds.build(), 80),
1000
)
}
// Start animation button
findViewById(R.id.btnStart).setOnClickListener {
currentPointIndex = 0
startLineAnimation()
}
}
}
private fun setupLine(style: Style) {
// Empty source for the animated line
style.addSource(GeoJsonSource("line-source"))
// Line layer
style.addLayer(
LineLayer("line-layer", "line-source")
.withProperties(
lineColor(Color.parseColor("#4285F4")),
lineWidth(4f),
lineOpacity(0.9f),
lineJoin("round"),
lineCap("round")
)
)
}
private fun startLineAnimation() {
currentPointIndex = 1
val drawNextSegment = object : Runnable {
override fun run() {
if (currentPointIndex >= routePoints.size) return
// Update line with points up to current index
val visiblePoints = routePoints.subList(0, currentPointIndex + 1)
val lineString = LineString.fromLngLats(visiblePoints)
val source = map.style?.getSource("line-source") as? GeoJsonSource
source?.setGeoJson(Feature.fromGeometry(lineString))
currentPointIndex++
if (currentPointIndex < routePoints.size) {
handler.postDelayed(this, 500) // 500ms between points
}
}
}
handler.post(drawNextSegment)
}
override fun onDestroy() {
handler.removeCallbacksAndMessages(null)
super.onDestroy()
mapView.onDestroy()
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Smooth Interpolated Line Animation
Interpolate smoothly between points using ValueAnimator:
```kotlin
private fun startSmoothAnimation() {
animateSegment(0)
}
private fun animateSegment(index: Int) {
if (index >= routePoints.size - 1) return
val start = routePoints[index]
val end = routePoints[index + 1]
ValueAnimator.ofFloat(0f, 1f).apply {
duration = 1000 // 1 second per segment
interpolator = LinearInterpolator()
addUpdateListener { animation ->
val fraction = animation.animatedValue as Float
// Interpolate between start and end
val currentLng = start.longitude() + (end.longitude() - start.longitude()) * fraction
val currentLat = start.latitude() + (end.latitude() - start.latitude()) * fraction
// Build line from first point to current interpolated position
val visiblePoints = routePoints.subList(0, index + 1).toMutableList()
visiblePoints.add(Point.fromLngLat(currentLng, currentLat))
val lineString = LineString.fromLngLats(visiblePoints)
val source = map.style?.getSource("line-source") as? GeoJsonSource
source?.setGeoJson(Feature.fromGeometry(lineString))
}
addListener(object : android.animation.AnimatorListenerAdapter() {
override fun onAnimationEnd(animation: android.animation.Animator) {
animateSegment(index + 1) // Next segment
}
})
start()
}
}
```
## With Trailing Marker
Show a dot at the leading edge of the animated line:
```kotlin
import android.graphics.BitmapFactory
import org.maplibre.android.style.layers.SymbolLayer
private fun setupLeadingMarker(style: Style) {
val bitmap = BitmapFactory.decodeResource(resources, R.drawable.ic_dot)
style.addImage("dot-icon", bitmap)
style.addSource(GeoJsonSource("dot-source",
Feature.fromGeometry(routePoints[0])
))
style.addLayer(
SymbolLayer("dot-layer", "dot-source")
.withProperties(
iconImage("dot-icon"),
iconSize(0.8f),
iconAllowOverlap(true)
)
)
}
// Inside your animation update listener, also update the dot:
private fun updateDot(lat: Double, lng: Double) {
val source = map.style?.getSource("dot-source") as? GeoJsonSource
source?.setGeoJson(Feature.fromGeometry(Point.fromLngLat(lng, lat)))
}
```
## Next Steps
- [Animate a Marker](./animate-marker) — Move markers along paths
- [Polyline Route](./polyline-route) — Static route lines
- [Fly to a Location](./fly-to-location) — Camera animation
---
**Tip**: For the smoothest visual effect, use the interpolated animation approach with `ValueAnimator`. The step-by-step method is simpler but creates visible "jumps" between points. Interpolation creates a fluid drawing motion.
---
# Animate a Marker Along a Route
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/animate-marker
# Animate a Marker Along a Route
This tutorial shows how to smoothly animate a marker moving along a path — useful for showing vehicle tracking, delivery routes, or GPS playback.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Animate Marker with ValueAnimator
Move a symbol layer marker along a route using Android's animation framework:
```kotlin
import android.animation.TypeEvaluator
import android.animation.ValueAnimator
import android.graphics.BitmapFactory
import android.os.Bundle
import android.view.animation.LinearInterpolator
import androidx.appcompat.app.AppCompatActivity
import com.google.gson.JsonObject
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.camera.CameraUpdateFactory
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.layers.SymbolLayer
import org.maplibre.android.style.sources.GeoJsonSource
import org.maplibre.geojson.Feature
import org.maplibre.geojson.Point
class AnimateMarkerActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
private var markerAnimator: ValueAnimator? = null
// Route coordinates
private val routePoints = listOf(
LatLng(48.8566, 2.3522), // Paris
LatLng(48.8620, 2.3400),
LatLng(48.8680, 2.3310),
LatLng(48.8738, 2.2950), // Arc de Triomphe
LatLng(48.8750, 2.2870),
LatLng(48.8800, 2.2780),
LatLng(48.8867, 2.3431), // Sacré-Cœur
)
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
setupMarker(style)
animateMarkerAlongRoute()
}
}
}
private fun setupMarker(style: Style) {
// Add marker icon
val bitmap = BitmapFactory.decodeResource(resources, R.drawable.ic_marker)
style.addImage("moving-marker", bitmap)
// Create GeoJSON source with initial position
val initialPoint = Point.fromLngLat(
routePoints[0].longitude,
routePoints[0].latitude
)
style.addSource(
GeoJsonSource("marker-source", Feature.fromGeometry(initialPoint))
)
// Add symbol layer
style.addLayer(
SymbolLayer("marker-layer", "marker-source")
.withProperties(
iconImage("moving-marker"),
iconSize(1.0f),
iconAllowOverlap(true),
iconIgnorePlacement(true)
)
)
// Set camera
map.cameraPosition = CameraPosition.Builder()
.target(routePoints[0])
.zoom(13.0)
.build()
}
private fun animateMarkerAlongRoute() {
// Animate through each segment
animateSegment(0)
}
private fun animateSegment(index: Int) {
if (index >= routePoints.size - 1) return
val start = routePoints[index]
val end = routePoints[index + 1]
markerAnimator = ValueAnimator.ofObject(
LatLngEvaluator(), start, end
).apply {
duration = 2000 // 2 seconds per segment
interpolator = LinearInterpolator()
addUpdateListener { animation ->
val position = animation.animatedValue as LatLng
val point = Point.fromLngLat(position.longitude, position.latitude)
// Update marker position
val source = map.style?.getSource("marker-source") as? GeoJsonSource
source?.setGeoJson(Feature.fromGeometry(point))
// Follow marker with camera
map.easeCamera(
CameraUpdateFactory.newLatLng(position),
100
)
}
addListener(object : android.animation.AnimatorListenerAdapter() {
override fun onAnimationEnd(animation: android.animation.Animator) {
// Move to next segment
animateSegment(index + 1)
}
})
start()
}
}
// Custom evaluator for LatLng interpolation
private class LatLngEvaluator : TypeEvaluator {
override fun evaluate(fraction: Float, startValue: LatLng, endValue: LatLng): LatLng {
val lat = startValue.latitude + (endValue.latitude - startValue.latitude) * fraction
val lng = startValue.longitude + (endValue.longitude - startValue.longitude) * fraction
return LatLng(lat, lng)
}
}
override fun onDestroy() {
markerAnimator?.cancel()
super.onDestroy()
mapView.onDestroy()
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## With Route Trail Line
Show the path behind the marker as it moves:
```kotlin
import org.maplibre.android.style.layers.LineLayer
import org.maplibre.geojson.FeatureCollection
import org.maplibre.geojson.LineString
private val visitedPoints = mutableListOf()
private fun setupRouteTrail(style: Style) {
// Trail source — starts empty
style.addSource(GeoJsonSource("trail-source"))
// Trail line layer
style.addLayer(
LineLayer("trail-layer", "trail-source")
.withProperties(
lineColor("#4285F4"),
lineWidth(3f),
lineOpacity(0.7f)
)
)
}
private fun updateTrail(position: LatLng) {
visitedPoints.add(
Point.fromLngLat(position.longitude, position.latitude)
)
if (visitedPoints.size >= 2) {
val lineString = LineString.fromLngLats(visitedPoints)
val source = map.style?.getSource("trail-source") as? GeoJsonSource
source?.setGeoJson(Feature.fromGeometry(lineString))
}
}
```
Then call `updateTrail(position)` inside the `addUpdateListener` callback.
## With Play/Pause Controls
```kotlin
import android.widget.Button
private var isPlaying = true
private fun setupControls() {
val playPauseBtn = findViewById(R.id.btnPlayPause)
playPauseBtn.setOnClickListener {
if (isPlaying) {
markerAnimator?.pause()
playPauseBtn.text = "Play"
} else {
markerAnimator?.resume()
playPauseBtn.text = "Pause"
}
isPlaying = !isPlaying
}
findViewById(R.id.btnRestart).setOnClickListener {
markerAnimator?.cancel()
visitedPoints.clear()
animateSegment(0)
isPlaying = true
playPauseBtn.text = "Pause"
}
}
```
## Next Steps
- [Animated Symbol Layer](../styling/animated-symbol-layer) — Advanced symbol animations
- [Fly to a Location](./fly-to-location) — Camera flight animations
- [Polyline Route](./polyline-route) — Static route drawing
---
**Tip**: For smoother animation at high zoom levels, interpolate every 10-20ms. For performance with many animated markers, use a single GeoJSON source with multiple features instead of separate sources per marker.
---
# Disable Map Gestures
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/disable-gestures
# Disable Map Gestures
This tutorial shows how to selectively enable or disable map interaction gestures on your MapMetrics Android map — useful for embedded maps, kiosk displays, or guided experiences.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Disable All Gestures
Create a static, non-interactive map:
```kotlin
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class StaticMapActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
// Disable all gestures at once
map.uiSettings.setAllGesturesEnabled(false)
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
)
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8566, 2.3522))
.zoom(14.0)
.build()
}
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Disable via XML Attributes
Configure gestures directly in the layout:
```xml
(R.id.switchScroll).apply {
isChecked = ui.isScrollGesturesEnabled
setOnCheckedChangeListener { _, checked ->
ui.isScrollGesturesEnabled = checked
}
}
findViewById(R.id.switchZoom).apply {
isChecked = ui.isZoomGesturesEnabled
setOnCheckedChangeListener { _, checked ->
ui.isZoomGesturesEnabled = checked
ui.isDoubleTapGesturesEnabled = checked
}
}
findViewById(R.id.switchRotate).apply {
isChecked = ui.isRotateGesturesEnabled
setOnCheckedChangeListener { _, checked ->
ui.isRotateGesturesEnabled = checked
}
}
findViewById(R.id.switchTilt).apply {
isChecked = ui.isTiltGesturesEnabled
setOnCheckedChangeListener { _, checked ->
ui.isTiltGesturesEnabled = checked
}
}
}
```
## Disable Velocity Animations
Stop inertia/fling after pan, zoom, or rotate:
```kotlin
val ui = map.uiSettings
ui.isFlingVelocityAnimationEnabled = false // No fling after pan
ui.isScaleVelocityAnimationEnabled = false // No momentum after zoom
ui.isRotateVelocityAnimationEnabled = false // No momentum after rotate
```
## Available Gesture Settings
| Setting | XML Attribute | Default | Description |
|---------|--------------|---------|-------------|
| `isScrollGesturesEnabled` | `maplibre_uiScrollGestures` | `true` | Pan/drag |
| `isZoomGesturesEnabled` | `maplibre_uiZoomGestures` | `true` | Pinch zoom |
| `isDoubleTapGesturesEnabled` | `maplibre_uiDoubleTapGestures` | `true` | Double-tap zoom |
| `isRotateGesturesEnabled` | `maplibre_uiRotateGestures` | `true` | Two-finger rotate |
| `isTiltGesturesEnabled` | `maplibre_uiTiltGestures` | `true` | Two-finger tilt |
| `isHorizontalScrollGesturesEnabled` | `maplibre_uiHorizontalScrollGestures` | `true` | Horizontal scroll |
| `isQuickZoomGesturesEnabled` | — | `true` | Double-tap-drag zoom |
| `isFlingVelocityAnimationEnabled` | — | `true` | Pan momentum |
| `isScaleVelocityAnimationEnabled` | — | `true` | Zoom momentum |
| `isRotateVelocityAnimationEnabled` | — | `true` | Rotation momentum |
## Next Steps
- [Gesture Detector](../camera/gesture-detector) — Advanced gesture handling
- [Configuration](../configuration) — Map options at initialization
- [Fullscreen Map](./fullscreen-map) — Immersive map display
---
**Tip**: For embedded maps inside a `ScrollView` or `RecyclerView`, disable scroll gestures so the map doesn't capture vertical scroll events — users can still tap markers and the map stays interactive for other gestures.
---
# Draw a Circle on the Map
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/draw-a-circle
# Draw a Circle on the Map
This tutorial shows how to draw circular areas on your MapMetrics Android map — useful for showing radius zones, geofences, or proximity areas.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Draw a Circle Using Turf
Since there's no native circle geometry in GeoJSON, we approximate one using a polygon with many points:
```kotlin
import android.graphics.Color
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
import org.maplibre.android.style.layers.FillLayer
import org.maplibre.android.style.layers.LineLayer
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.sources.GeoJsonSource
import org.maplibre.geojson.Feature
import org.maplibre.geojson.Point
import org.maplibre.geojson.Polygon
import kotlin.math.*
class DrawCircleActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
drawCircle(style, LatLng(48.8584, 2.2945), 500.0) // 500m radius
}
}
}
private fun drawCircle(style: Style, center: LatLng, radiusMeters: Double) {
val circlePolygon = createCirclePolygon(center, radiusMeters, 64)
style.addSource(
GeoJsonSource("circle-source", Feature.fromGeometry(circlePolygon))
)
// Fill
style.addLayer(
FillLayer("circle-fill", "circle-source")
.withProperties(
fillColor(Color.parseColor("#4285F4")),
fillOpacity(0.2f)
)
)
// Outline
style.addLayer(
LineLayer("circle-outline", "circle-source")
.withProperties(
lineColor(Color.parseColor("#4285F4")),
lineWidth(2f)
)
)
// Center camera
map.cameraPosition = CameraPosition.Builder()
.target(center)
.zoom(14.0)
.build()
}
/**
* Generate a polygon approximating a circle.
* @param center Center point
* @param radiusMeters Radius in meters
* @param steps Number of polygon vertices (more = smoother)
*/
private fun createCirclePolygon(
center: LatLng,
radiusMeters: Double,
steps: Int
): Polygon {
val points = mutableListOf()
val earthRadius = 6371000.0 // meters
for (i in 0..steps) {
val angle = Math.toRadians((360.0 / steps) * i)
val lat = Math.toRadians(center.latitude)
val lng = Math.toRadians(center.longitude)
val newLat = asin(
sin(lat) * cos(radiusMeters / earthRadius) +
cos(lat) * sin(radiusMeters / earthRadius) * cos(angle)
)
val newLng = lng + atan2(
sin(angle) * sin(radiusMeters / earthRadius) * cos(lat),
cos(radiusMeters / earthRadius) - sin(lat) * sin(newLat)
)
points.add(
Point.fromLngLat(
Math.toDegrees(newLng),
Math.toDegrees(newLat)
)
)
}
return Polygon.fromLngLats(listOf(points))
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Multiple Radius Rings
Show concentric distance rings around a point:
```kotlin
private fun drawRadiusRings(style: Style, center: LatLng) {
val rings = listOf(
Pair(250.0, "#4285F4"), // 250m — blue
Pair(500.0, "#34A853"), // 500m — green
Pair(1000.0, "#FF6B35"), // 1km — orange
)
for ((index, ring) in rings.withIndex()) {
val (radius, color) = ring
val polygon = createCirclePolygon(center, radius, 64)
val sourceId = "ring-source-$index"
style.addSource(GeoJsonSource(sourceId, Feature.fromGeometry(polygon)))
style.addLayer(
FillLayer("ring-fill-$index", sourceId)
.withProperties(
fillColor(Color.parseColor(color)),
fillOpacity(0.1f)
)
)
style.addLayer(
LineLayer("ring-outline-$index", sourceId)
.withProperties(
lineColor(Color.parseColor(color)),
lineWidth(2f),
lineDasharray(arrayOf(2f, 1f))
)
)
}
// Add center marker
map.addMarker(
org.maplibre.android.annotations.MarkerOptions()
.position(center)
.title("Center Point")
.snippet("250m / 500m / 1km radius")
)
}
```
## Circle on Tap
Let users tap the map to place a circle:
```kotlin
private fun setupTapToCircle(style: Style) {
// Pre-create empty source and layers
style.addSource(GeoJsonSource("tap-circle-source"))
style.addLayer(
FillLayer("tap-circle-fill", "tap-circle-source")
.withProperties(
fillColor(Color.parseColor("#FF6B35")),
fillOpacity(0.2f)
)
)
style.addLayer(
LineLayer("tap-circle-outline", "tap-circle-source")
.withProperties(
lineColor(Color.parseColor("#FF6B35")),
lineWidth(2f)
)
)
map.addOnMapClickListener { latLng ->
val polygon = createCirclePolygon(latLng, 300.0, 64)
val source = style.getSource("tap-circle-source") as? GeoJsonSource
source?.setGeoJson(Feature.fromGeometry(polygon))
true
}
}
```
## Using Turf Library
If you include the Turf dependency, circle creation is simpler:
```kotlin
import com.mapbox.turf.TurfTransformation
import com.mapbox.turf.TurfConstants
val center = Point.fromLngLat(2.2945, 48.8584)
val circlePolygon = TurfTransformation.circle(
center,
500.0,
64,
TurfConstants.UNIT_METRES
)
```
## Next Steps
- [Polygon Area](./polygon-area) — Draw custom shapes
- [Measure Distances](./measure-distances) — Distance calculations
- [Circle Layer](../styling/circle-layer) — Circle layer for point data
---
**Tip**: Use 64 steps for smooth circles. Below 32 you'll see visible edges. Above 128 adds points without visible improvement. The Turf library approach is recommended when available as it handles edge cases near the poles.
---
# Fit Map to a Bounding Box
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/fit-bounds
# Fit Map to a Bounding Box
This tutorial shows how to automatically zoom and position your MapMetrics Android map to fit a set of points, markers, or a region.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Fit to Multiple Markers
Automatically adjust the camera to show all markers:
```kotlin
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.annotations.MarkerOptions
import org.maplibre.android.camera.CameraUpdateFactory
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.geometry.LatLngBounds
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class FitBoundsActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
private val cities = listOf(
Pair(LatLng(48.8566, 2.3522), "Paris"),
Pair(LatLng(51.5074, -0.1278), "London"),
Pair(LatLng(52.5200, 13.4050), "Berlin"),
Pair(LatLng(41.9028, 12.4964), "Rome"),
Pair(LatLng(40.4168, -3.7038), "Madrid"),
)
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
addMarkersAndFit()
}
}
}
private fun addMarkersAndFit() {
// Add markers
val boundsBuilder = LatLngBounds.Builder()
for ((position, name) in cities) {
map.addMarker(
MarkerOptions()
.position(position)
.title(name)
)
boundsBuilder.include(position)
}
// Fit camera to show all markers with padding
map.easeCamera(
CameraUpdateFactory.newLatLngBounds(
boundsBuilder.build(),
100 // padding in pixels
),
1000 // animation duration
)
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Fit to a Predefined Region
Zoom to specific geographic regions with buttons:
```kotlin
import android.widget.Button
private val regions = mapOf(
"Europe" to LatLngBounds.Builder()
.include(LatLng(71.0, -25.0)) // Northwest
.include(LatLng(35.0, 45.0)) // Southeast
.build(),
"North America" to LatLngBounds.Builder()
.include(LatLng(72.0, -170.0))
.include(LatLng(15.0, -50.0))
.build(),
"Asia" to LatLngBounds.Builder()
.include(LatLng(55.0, 25.0))
.include(LatLng(-10.0, 150.0))
.build(),
)
private fun setupRegionButtons() {
findViewById(R.id.btnEurope).setOnClickListener {
fitToRegion("Europe")
}
findViewById(R.id.btnNorthAmerica).setOnClickListener {
fitToRegion("North America")
}
findViewById(R.id.btnAsia).setOnClickListener {
fitToRegion("Asia")
}
}
private fun fitToRegion(name: String) {
regions[name]?.let { bounds ->
map.animateCamera(
CameraUpdateFactory.newLatLngBounds(bounds, 50),
2000
)
}
}
```
## Fit Bounds with Custom Padding
Use different padding per edge for UI elements:
```kotlin
// Different padding for each side: [left, top, right, bottom]
val paddingPixels = intArrayOf(50, 200, 50, 100) // extra top for header
val cameraPosition = map.getCameraForLatLngBounds(
boundsBuilder.build(),
paddingPixels
)
cameraPosition?.let {
map.animateCamera(
CameraUpdateFactory.newCameraPosition(it),
1500
)
}
```
## Fit to Route Points
Zoom to fit a polyline route:
```kotlin
import org.maplibre.geojson.LineString
import org.maplibre.geojson.Point
private fun fitToRoute() {
val routePoints = listOf(
LatLng(48.8566, 2.3522), // Paris
LatLng(50.8503, 4.3517), // Brussels
LatLng(52.3676, 4.9041), // Amsterdam
LatLng(53.5511, 9.9937), // Hamburg
LatLng(52.5200, 13.4050), // Berlin
)
val bounds = LatLngBounds.Builder()
for (point in routePoints) {
bounds.include(point)
}
map.animateCamera(
CameraUpdateFactory.newLatLngBounds(bounds.build(), 80),
2000
)
}
```
## Fit Bounds Options
| Parameter | Type | Description |
|-----------|------|-------------|
| `bounds` | `LatLngBounds` | Southwest + northeast corners to fit |
| `padding` | `Int` | Equal padding on all sides (pixels) |
| `padding` | `IntArray` | Per-side padding: [left, top, right, bottom] |
| `duration` | `Int` | Animation duration in milliseconds |
## Animation Methods for Bounds
| Method | Behavior |
|--------|----------|
| `moveCamera()` | Instant jump to bounds |
| `easeCamera()` | Constant-speed animation |
| `animateCamera()` | Natural ease-in/ease-out |
## Next Steps
- [Lat-Lng Bounds](../camera/lat-lng-bounds) — Bounds API deep dive
- [Zoom Methods](../camera/zoom-methods) — Zoom controls
- [Fly to a Location](./fly-to-location) — Point-to-point animation
---
**Tip**: Always add padding (50-100px minimum) when fitting bounds so markers at the edge aren't clipped by the screen boundary. For maps with floating UI panels, use per-side padding to account for the panel area.
---
# Fly to a Location
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/fly-to-location
# Fly to a Location
This tutorial shows how to animate the camera smoothly to a destination point on your MapMetrics Android map using different animation styles.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Basic Fly-To Animation
Animate the camera to a new location with a button:
```kotlin
import android.os.Bundle
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.camera.CameraUpdateFactory
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class FlyToActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_fly_to)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
)
// Set initial position
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(51.5074, -0.1278)) // London
.zoom(10.0)
.build()
// Fly to Paris button
findViewById(R.id.btnFlyToParis).setOnClickListener {
flyToLocation(LatLng(48.8566, 2.3522), 14.0, "Paris")
}
// Fly to Tokyo button
findViewById(R.id.btnFlyToTokyo).setOnClickListener {
flyToLocation(LatLng(35.6762, 139.6503), 12.0, "Tokyo")
}
}
}
private fun flyToLocation(target: LatLng, zoom: Double, name: String) {
val position = CameraPosition.Builder()
.target(target)
.zoom(zoom)
.tilt(45.0)
.bearing(0.0)
.build()
map.animateCamera(
CameraUpdateFactory.newCameraPosition(position),
3000 // 3 seconds duration
)
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Three Animation Styles
Compare `moveCamera`, `easeCamera`, and `animateCamera`:
```kotlin
val target = CameraPosition.Builder()
.target(LatLng(48.8566, 2.3522))
.zoom(14.0)
.tilt(45.0)
.build()
// 1. Instant jump — no animation
map.moveCamera(CameraUpdateFactory.newCameraPosition(target))
// 2. Ease — constant speed, smooth but linear
map.easeCamera(
CameraUpdateFactory.newCameraPosition(target),
2000 // duration in ms
)
// 3. Animate — accelerates and decelerates naturally
map.animateCamera(
CameraUpdateFactory.newCameraPosition(target),
3000 // duration in ms
)
```
## Fly-To with Callback
Run code when the animation finishes or is cancelled:
```kotlin
import org.maplibre.android.maps.MapLibreMap.CancelableCallback
map.animateCamera(
CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder()
.target(LatLng(40.7128, -74.0060)) // New York
.zoom(15.0)
.tilt(50.0)
.bearing(-20.0)
.build()
),
4000,
object : CancelableCallback {
override fun onFinish() {
// Animation completed — add marker, load data, etc.
map.addMarker(
org.maplibre.android.annotations.MarkerOptions()
.position(LatLng(40.7128, -74.0060))
.title("New York City")
)
}
override fun onCancel() {
// User interrupted the animation by touching the map
}
}
)
```
## Tour Through Multiple Locations
Fly through a sequence of locations automatically:
```kotlin
import android.os.Handler
import android.os.Looper
private val tourLocations = listOf(
Triple(LatLng(48.8566, 2.3522), 14.0, "Paris"),
Triple(LatLng(41.9028, 12.4964), 13.0, "Rome"),
Triple(LatLng(52.5200, 13.4050), 12.0, "Berlin"),
Triple(LatLng(59.3293, 18.0686), 13.0, "Stockholm"),
Triple(LatLng(40.4168, -3.7038), 12.0, "Madrid"),
)
private var currentIndex = 0
private fun startTour() {
if (currentIndex >= tourLocations.size) {
currentIndex = 0 // loop back
}
val (target, zoom, name) = tourLocations[currentIndex]
val position = CameraPosition.Builder()
.target(target)
.zoom(zoom)
.tilt(50.0)
.bearing(currentIndex * 30.0) // vary the bearing
.build()
map.animateCamera(
CameraUpdateFactory.newCameraPosition(position),
3000,
object : CancelableCallback {
override fun onFinish() {
currentIndex++
// Wait 2 seconds at each stop, then fly to next
Handler(Looper.getMainLooper()).postDelayed({
startTour()
}, 2000)
}
override fun onCancel() {
// User touched the map — stop the tour
}
}
)
}
```
## Animation Comparison
| Method | Speed | Feel | Use Case |
|--------|-------|------|----------|
| `moveCamera` | Instant | Abrupt jump | Resetting view, loading saved position |
| `easeCamera` | Constant | Smooth, linear | Short transitions, subtle moves |
| `animateCamera` | Eased | Natural acceleration | Fly-to, showcase, tours |
## Next Steps
- [Camera Position](../camera/cameraposition) — Camera position fundamentals
- [Animation Types](../camera/animation-types) — Deep dive into animation options
- [Lat-Lng Bounds](../camera/lat-lng-bounds) — Fit camera to a region
---
**Tip**: For long-distance flights (e.g., Paris → Tokyo), use `animateCamera` with a duration of 4-6 seconds. For short hops within the same city, 1-2 seconds with `easeCamera` feels more natural.
---
# Fullscreen Map
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/fullscreen-map
# Fullscreen Map
This tutorial shows how to create an immersive fullscreen map experience on Android — hiding the status bar, navigation bar, and any toolbars.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Fullscreen Activity
Create a map that fills the entire screen:
```kotlin
import android.os.Build
import android.os.Bundle
import android.view.View
import android.view.WindowInsets
import android.view.WindowInsetsController
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class FullscreenMapActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Hide action bar
supportActionBar?.hide()
setContentView(R.layout.activity_fullscreen_map)
// Enable fullscreen
enableFullscreen()
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
)
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8566, 2.3522))
.zoom(12.0)
.build()
}
}
private fun enableFullscreen() {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
// Android 11+ (API 30+)
window.insetsController?.let { controller ->
controller.hide(
WindowInsets.Type.statusBars() or
WindowInsets.Type.navigationBars()
)
controller.systemBarsBehavior =
WindowInsetsController.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
}
} else {
// Older Android versions
@Suppress("DEPRECATION")
window.decorView.systemUiVisibility = (
View.SYSTEM_UI_FLAG_FULLSCREEN
or View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
or View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY
or View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
or View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
or View.SYSTEM_UI_FLAG_LAYOUT_STABLE
)
}
}
override fun onWindowFocusChanged(hasFocus: Boolean) {
super.onWindowFocusChanged(hasFocus)
if (hasFocus) enableFullscreen()
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
Layout XML (`res/layout/activity_fullscreen_map.xml`):
```xml
```
Also add to `AndroidManifest.xml`:
```xml
(R.id.btnToggleFullscreen)
toggleBtn.setOnClickListener {
isFullscreen = !isFullscreen
if (isFullscreen) {
enableFullscreen()
supportActionBar?.hide()
toggleBtn.setImageResource(R.drawable.ic_fullscreen_exit)
} else {
exitFullscreen()
supportActionBar?.show()
toggleBtn.setImageResource(R.drawable.ic_fullscreen)
}
}
}
private fun exitFullscreen() {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
window.insetsController?.show(
WindowInsets.Type.statusBars() or
WindowInsets.Type.navigationBars()
)
} else {
@Suppress("DEPRECATION")
window.decorView.systemUiVisibility = View.SYSTEM_UI_FLAG_VISIBLE
}
}
```
## Next Steps
- [Getting Started](../getting-started) — Basic map setup
- [Fly to a Location](./fly-to-location) — Camera animations
- [Disable Gestures](./disable-gestures) — Control map interactions
---
**Tip**: Use `BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE` so users can temporarily reveal system bars by swiping from the edge — they auto-hide again after a moment. This provides the best balance between immersion and accessibility.
---
# Game-Style Map Controls
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/game-controls
# Game-Style Map Controls
This tutorial shows how to add D-pad and button controls for navigating the map — useful for kiosk displays, accessibility, or game-like map exploration.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## D-Pad Navigation
Add directional buttons to pan the map:
```kotlin
import android.os.Bundle
import android.os.Handler
import android.os.Looper
import android.view.MotionEvent
import android.view.View
import android.widget.ImageButton
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.camera.CameraUpdateFactory
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class GameControlsActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
private val handler = Handler(Looper.getMainLooper())
private val panSpeed = 50f // pixels per tick
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_game_controls)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
// Disable default gestures — we use buttons instead
map.uiSettings.isScrollGesturesEnabled = false
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
)
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8566, 2.3522))
.zoom(14.0)
.build()
setupDPad()
setupZoomButtons()
setupRotateButtons()
}
}
private fun setupDPad() {
setupHoldButton(R.id.btnUp) { map.scrollBy(0f, -panSpeed) }
setupHoldButton(R.id.btnDown) { map.scrollBy(0f, panSpeed) }
setupHoldButton(R.id.btnLeft) { map.scrollBy(-panSpeed, 0f) }
setupHoldButton(R.id.btnRight) { map.scrollBy(panSpeed, 0f) }
}
private fun setupZoomButtons() {
findViewById(R.id.btnZoomIn).setOnClickListener {
map.animateCamera(CameraUpdateFactory.zoomIn(), 200)
}
findViewById(R.id.btnZoomOut).setOnClickListener {
map.animateCamera(CameraUpdateFactory.zoomOut(), 200)
}
}
private fun setupRotateButtons() {
findViewById(R.id.btnRotateLeft).setOnClickListener {
val current = map.cameraPosition.bearing
map.easeCamera(
CameraUpdateFactory.bearingTo(current - 15),
300
)
}
findViewById(R.id.btnRotateRight).setOnClickListener {
val current = map.cameraPosition.bearing
map.easeCamera(
CameraUpdateFactory.bearingTo(current + 15),
300
)
}
}
/**
* Repeat an action while a button is held down.
*/
private fun setupHoldButton(viewId: Int, action: () -> Unit) {
val button = findViewById(viewId)
var isHolding = false
val repeatRunnable = object : Runnable {
override fun run() {
if (isHolding) {
action()
handler.postDelayed(this, 50) // ~20fps
}
}
}
button.setOnTouchListener { _, event ->
when (event.action) {
MotionEvent.ACTION_DOWN -> {
isHolding = true
handler.post(repeatRunnable)
true
}
MotionEvent.ACTION_UP, MotionEvent.ACTION_CANCEL -> {
isHolding = false
true
}
else -> false
}
}
}
override fun onDestroy() {
handler.removeCallbacksAndMessages(null)
super.onDestroy()
mapView.onDestroy()
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
Layout (`res/layout/activity_game_controls.xml`):
```xml
```
## Next Steps
- [Navigation Controls](./navigation-controls) — Standard map controls
- [Toggle Interactions](./toggle-interactions) — Enable/disable gestures
- [Disable Gestures](./disable-gestures) — Lock the map view
---
**Tip**: The `setupHoldButton` pattern uses `MotionEvent.ACTION_DOWN/UP` to repeat the pan action while the button is held. This gives a smooth, continuous movement similar to game controllers. The 50ms interval (~20fps) is smooth without being too CPU-intensive.
---
# Migrate from Google Maps to MapMetrics
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/google-maps-migration
# Migrate from Google Maps to MapMetrics
This guide helps you migrate an existing Android app from the Google Maps SDK to the MapMetrics SDK, covering the key API differences and code changes needed.
## Prerequisites
- An existing Android project using `com.google.android.gms:play-services-maps`
- A MapMetrics API key from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Step 1: Update Dependencies
Replace the Google Maps dependency in `build.gradle`:
```gradle
// Remove:
// implementation 'com.google.android.gms:play-services-maps:18.x.x'
// Add:
implementation 'org.mapmetrics.android-sdk:mapmetrics-native-sdk:1.0.3'
```
Remove the Google Maps API key from `AndroidManifest.xml`:
```xml
```
## Step 2: Replace the Map View
### Layout XML
```xml
(R.id.btnPrev).setOnClickListener {
if (currentIndex > 0) jumpToLocation(currentIndex - 1)
}
findViewById(R.id.btnNext).setOnClickListener {
if (currentIndex < locations.size - 1) jumpToLocation(currentIndex + 1)
}
}
}
private fun jumpToLocation(index: Int) {
currentIndex = index
val loc = locations[index]
// Update label
locationLabel.text = "${index + 1}/${locations.size} — ${loc.name}"
// Animate camera
map.animateCamera(
CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder()
.target(loc.position)
.zoom(loc.zoom)
.tilt(45.0)
.bearing(0.0)
.build()
),
1500
)
// Update button states
findViewById(R.id.btnPrev).isEnabled = index > 0
findViewById(R.id.btnNext).isEnabled = index < locations.size - 1
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
Layout (`res/layout/activity_jump_locations.xml`):
```xml
```
## Auto-Play Tour
Automatically cycle through locations:
```kotlin
import android.os.Handler
import android.os.Looper
private val autoPlayHandler = Handler(Looper.getMainLooper())
private var isAutoPlaying = false
private fun startAutoPlay() {
isAutoPlaying = true
val autoPlayRunnable = object : Runnable {
override fun run() {
if (!isAutoPlaying) return
val nextIndex = (currentIndex + 1) % locations.size
jumpToLocation(nextIndex)
autoPlayHandler.postDelayed(this, 4000) // 4s per stop
}
}
autoPlayHandler.postDelayed(autoPlayRunnable, 4000)
}
private fun stopAutoPlay() {
isAutoPlaying = false
autoPlayHandler.removeCallbacksAndMessages(null)
}
```
## Next Steps
- [Fly to a Location](./fly-to-location) — Single fly-to animation
- [Orbit Animation](../camera/orbit-animation) — Rotating camera
- [Multiple Markers](./multiple-markers) — Adding many markers
---
**Tip**: Vary the zoom level per location for a more engaging tour — zoom in close (17-18) for small landmarks and zoom out (13-14) for districts or parks.
---
# Handle Map Click Events
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/map-click-events
# Handle Map Click Events
This tutorial covers handling tap, long-press, and feature click events on your MapMetrics Android map.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Basic Map Click
Respond when the user taps anywhere on the map:
```kotlin
import android.os.Bundle
import android.widget.TextView
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.annotations.MarkerOptions
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class MapClickActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
private lateinit var coordsText: TextView
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map_click)
coordsText = findViewById(R.id.tvCoords)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) {
setupClickListeners()
}
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8566, 2.3522))
.zoom(12.0)
.build()
}
}
private fun setupClickListeners() {
// Single tap
map.addOnMapClickListener { latLng ->
coordsText.text = String.format(
"Lat: %.6f, Lng: %.6f",
latLng.latitude, latLng.longitude
)
true
}
// Long press
map.addOnMapLongClickListener { latLng ->
map.addMarker(
MarkerOptions()
.position(latLng)
.title("Dropped Pin")
.snippet(
String.format(
"%.6f, %.6f",
latLng.latitude, latLng.longitude
)
)
)
Toast.makeText(this, "Marker added!", Toast.LENGTH_SHORT).show()
true
}
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Query Features at Click Point
Identify which features (layers, sources) are under the tap:
```kotlin
map.addOnMapClickListener { latLng ->
val screenPoint = map.projection.toScreenLocation(latLng)
// Query all rendered features at the tap point
val features = map.queryRenderedFeatures(screenPoint)
if (features.isNotEmpty()) {
val feature = features[0]
val properties = feature.properties()
Toast.makeText(
this,
"Feature: ${properties?.toString() ?: "no properties"}",
Toast.LENGTH_LONG
).show()
} else {
Toast.makeText(this, "No features here", Toast.LENGTH_SHORT).show()
}
true
}
```
## Query Specific Layers
Only respond to taps on specific layers:
```kotlin
map.addOnMapClickListener { latLng ->
val screenPoint = map.projection.toScreenLocation(latLng)
// Query only the "poi-layer" and "building-layer"
val features = map.queryRenderedFeatures(
screenPoint,
"poi-layer",
"building-layer"
)
if (features.isNotEmpty()) {
val name = features[0].getStringProperty("name")
Toast.makeText(this, "Tapped: $name", Toast.LENGTH_SHORT).show()
}
true
}
```
## Click Priority — Markers vs Layers
Handle markers and layer features with different priority:
```kotlin
private fun setupLayeredClickHandling() {
// Marker click takes priority
map.setOnMarkerClickListener { marker ->
Toast.makeText(
this,
"Marker: ${marker.title}",
Toast.LENGTH_SHORT
).show()
true // consume — don't pass to map click
}
// Map click handles everything else
map.addOnMapClickListener { latLng ->
val screenPoint = map.projection.toScreenLocation(latLng)
// Check custom layers
val poiFeatures = map.queryRenderedFeatures(screenPoint, "poi-layer")
if (poiFeatures.isNotEmpty()) {
handlePoiClick(poiFeatures[0])
return@addOnMapClickListener true
}
// Check polygon zones
val zoneFeatures = map.queryRenderedFeatures(screenPoint, "zone-fill")
if (zoneFeatures.isNotEmpty()) {
handleZoneClick(zoneFeatures[0])
return@addOnMapClickListener true
}
// Nothing hit — show coordinates
coordsText.text = String.format("%.4f, %.4f", latLng.latitude, latLng.longitude)
true
}
}
private fun handlePoiClick(feature: org.maplibre.geojson.Feature) {
val name = feature.getStringProperty("name") ?: "Unknown"
Toast.makeText(this, "POI: $name", Toast.LENGTH_SHORT).show()
}
private fun handleZoneClick(feature: org.maplibre.geojson.Feature) {
val zoneName = feature.getStringProperty("zone_name") ?: "Unknown zone"
Toast.makeText(this, "Zone: $zoneName", Toast.LENGTH_SHORT).show()
}
```
## Screen Coordinate Conversion
Convert between screen pixels and map coordinates:
```kotlin
// LatLng → screen pixel
val screenPoint = map.projection.toScreenLocation(LatLng(48.8566, 2.3522))
// screenPoint.x, screenPoint.y in pixels
// Screen pixel → LatLng
val latLng = map.projection.fromScreenLocation(android.graphics.PointF(500f, 500f))
// latLng.latitude, latLng.longitude
// Get visible region bounds
val visibleRegion = map.projection.visibleRegion
val bounds = visibleRegion.latLngBounds
// bounds.northEast, bounds.southWest
```
## Available Click Listeners
| Listener | Trigger | Returns |
|----------|---------|---------|
| `addOnMapClickListener` | Single tap on map | `LatLng` |
| `addOnMapLongClickListener` | Long press on map | `LatLng` |
| `setOnMarkerClickListener` | Tap on annotation marker | `Marker` |
| `setOnInfoWindowClickListener` | Tap on info window | `Marker` |
| `setOnInfoWindowLongClickListener` | Long press on info window | `Marker` |
| `setOnInfoWindowCloseListener` | Info window closes | `Marker` |
## Next Steps
- [Add a Popup](./add-a-popup) — Show popups on markers
- [Gesture Detector](../camera/gesture-detector) — Advanced gesture handling
- [Multiple Markers](./multiple-markers) — Markers with click handling
---
**Tip**: Return `true` from click listeners to consume the event and prevent it from propagating. Return `false` to let it pass through to the next handler. Order matters: marker listeners fire before map click listeners.
---
# Measure Distances on the Map
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/measure-distances
# Measure Distances on the Map
This tutorial shows how to build a tap-to-measure tool that calculates distances between points on your MapMetrics Android map using the Haversine formula.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Tap-to-Measure Tool
Tap points on the map to measure the total distance:
```kotlin
import android.graphics.Color
import android.os.Bundle
import android.widget.Button
import android.widget.TextView
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.annotations.MarkerOptions
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
import org.maplibre.android.style.layers.LineLayer
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.sources.GeoJsonSource
import org.maplibre.geojson.Feature
import org.maplibre.geojson.LineString
import org.maplibre.geojson.Point
import kotlin.math.*
class MeasureActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
private lateinit var distanceText: TextView
private val measurePoints = mutableListOf()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_measure)
distanceText = findViewById(R.id.tvDistance)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
setupMeasureLine(style)
setupMapClick()
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8566, 2.3522))
.zoom(12.0)
.build()
}
// Clear button
findViewById(R.id.btnClear).setOnClickListener {
clearMeasurement()
}
}
}
private fun setupMeasureLine(style: Style) {
style.addSource(GeoJsonSource("measure-source"))
style.addLayer(
LineLayer("measure-line", "measure-source")
.withProperties(
lineColor(Color.parseColor("#FF6B35")),
lineWidth(3f),
lineDasharray(arrayOf(2f, 1f))
)
)
}
private fun setupMapClick() {
map.addOnMapClickListener { latLng ->
// Add point
measurePoints.add(latLng)
// Add marker at tap point
map.addMarker(
MarkerOptions()
.position(latLng)
.title("Point ${measurePoints.size}")
.snippet(
"Lat: ${String.format("%.6f", latLng.latitude)}, " +
"Lng: ${String.format("%.6f", latLng.longitude)}"
)
)
// Update line
if (measurePoints.size >= 2) {
updateMeasureLine()
}
// Update total distance
updateDistance()
true
}
}
private fun updateMeasureLine() {
val points = measurePoints.map {
Point.fromLngLat(it.longitude, it.latitude)
}
val lineString = LineString.fromLngLats(points)
val source = map.style?.getSource("measure-source") as? GeoJsonSource
source?.setGeoJson(Feature.fromGeometry(lineString))
}
private fun updateDistance() {
var totalDistance = 0.0
for (i in 0 until measurePoints.size - 1) {
totalDistance += haversineDistance(
measurePoints[i], measurePoints[i + 1]
)
}
distanceText.text = when {
totalDistance < 1.0 -> "${(totalDistance * 1000).toInt()} m"
else -> String.format("%.2f km", totalDistance)
}
}
private fun clearMeasurement() {
measurePoints.clear()
map.clear()
distanceText.text = "0 m"
val source = map.style?.getSource("measure-source") as? GeoJsonSource
source?.setGeoJson(Feature.fromGeometry(LineString.fromLngLats(emptyList())))
}
/**
* Calculate distance between two points using the Haversine formula.
* Returns distance in kilometers.
*/
private fun haversineDistance(point1: LatLng, point2: LatLng): Double {
val R = 6371.0 // Earth's radius in km
val lat1 = Math.toRadians(point1.latitude)
val lat2 = Math.toRadians(point2.latitude)
val dLat = Math.toRadians(point2.latitude - point1.latitude)
val dLng = Math.toRadians(point2.longitude - point1.longitude)
val a = sin(dLat / 2).pow(2) +
cos(lat1) * cos(lat2) * sin(dLng / 2).pow(2)
val c = 2 * atan2(sqrt(a), sqrt(1 - a))
return R * c
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
Layout (`res/layout/activity_measure.xml`):
```xml
```
## Show Segment Distances
Display distance on each segment:
```kotlin
private fun updateDistance() {
var totalDistance = 0.0
val segmentInfo = StringBuilder()
for (i in 0 until measurePoints.size - 1) {
val segmentDist = haversineDistance(measurePoints[i], measurePoints[i + 1])
totalDistance += segmentDist
segmentInfo.append("Segment ${i + 1}: ")
segmentInfo.append(
if (segmentDist < 1.0) "${(segmentDist * 1000).toInt()} m"
else String.format("%.2f km", segmentDist)
)
segmentInfo.append("\n")
}
distanceText.text = when {
totalDistance < 1.0 -> "${(totalDistance * 1000).toInt()} m total"
else -> String.format("%.2f km total", totalDistance)
}
}
```
## Next Steps
- [Polyline Route](./polyline-route) — Draw lines on the map
- [Map Click Events](./map-click-events) — Handling taps and gestures
- [Polygon Area](./polygon-area) — Draw filled zones
---
**Tip**: The Haversine formula gives great-circle distances — straight line over the Earth's surface. For road distances, you would need a routing API. The measurements shown here are accurate for aerial/straight-line distance.
---
# Display Multiple Geometry Types Together
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/multiple-geometries
# Display Multiple Geometry Types Together
This tutorial shows how to display markers, polylines, polygons, and circles all on the same MapMetrics Android map.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Combined Geometries
Add points, lines, polygons, and circles in one view:
```kotlin
import android.graphics.Color
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.annotations.MarkerOptions
import org.maplibre.android.camera.CameraUpdateFactory
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.geometry.LatLngBounds
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
import org.maplibre.android.style.layers.CircleLayer
import org.maplibre.android.style.layers.FillLayer
import org.maplibre.android.style.layers.LineLayer
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.sources.GeoJsonSource
import org.maplibre.geojson.*
import com.google.gson.JsonObject
import kotlin.math.*
class MultiGeometryActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
addPolygonZone(style)
addRouteLines(style)
addPointMarkers(style)
addCircleRadius(style)
fitToAll()
}
}
}
// 1. Polygon — park/zone boundary
private fun addPolygonZone(style: Style) {
val parkBoundary = Polygon.fromLngLats(listOf(listOf(
Point.fromLngLat(2.3300, 48.8470),
Point.fromLngLat(2.3400, 48.8470),
Point.fromLngLat(2.3420, 48.8440),
Point.fromLngLat(2.3380, 48.8420),
Point.fromLngLat(2.3280, 48.8430),
Point.fromLngLat(2.3300, 48.8470),
)))
style.addSource(
GeoJsonSource("zone-source", Feature.fromGeometry(parkBoundary))
)
style.addLayer(
FillLayer("zone-fill", "zone-source")
.withProperties(
fillColor(Color.parseColor("#34A853")),
fillOpacity(0.2f)
)
)
style.addLayer(
LineLayer("zone-outline", "zone-source")
.withProperties(
lineColor(Color.parseColor("#34A853")),
lineWidth(2f)
)
)
}
// 2. Polylines — walking routes
private fun addRouteLines(style: Style) {
val route1 = Feature.fromGeometry(
LineString.fromLngLats(listOf(
Point.fromLngLat(2.3350, 48.8560),
Point.fromLngLat(2.3380, 48.8530),
Point.fromLngLat(2.3360, 48.8490),
Point.fromLngLat(2.3340, 48.8460),
)),
JsonObject().apply { addProperty("name", "Route A") }
)
val route2 = Feature.fromGeometry(
LineString.fromLngLats(listOf(
Point.fromLngLat(2.3200, 48.8550),
Point.fromLngLat(2.3250, 48.8520),
Point.fromLngLat(2.3300, 48.8500),
Point.fromLngLat(2.3350, 48.8480),
)),
JsonObject().apply { addProperty("name", "Route B") }
)
style.addSource(
GeoJsonSource("routes-source",
FeatureCollection.fromFeatures(listOf(route1, route2)))
)
style.addLayer(
LineLayer("routes-layer", "routes-source")
.withProperties(
lineColor(Color.parseColor("#4285F4")),
lineWidth(3f),
lineOpacity(0.8f)
)
)
}
// 3. Point markers — landmarks
private fun addPointMarkers(style: Style) {
val landmarks = listOf(
Triple(2.3376, 48.8606, "Louvre Museum"),
Triple(2.3499, 48.8530, "Notre-Dame"),
Triple(2.3266, 48.8600, "Musée d'Orsay"),
)
for ((lng, lat, name) in landmarks) {
map.addMarker(
MarkerOptions()
.position(LatLng(lat, lng))
.title(name)
)
}
}
// 4. Circle — radius zone around a point
private fun addCircleRadius(style: Style) {
val center = LatLng(48.8530, 2.3499) // Notre-Dame
val circlePolygon = createCirclePolygon(center, 300.0, 64)
style.addSource(
GeoJsonSource("circle-source", Feature.fromGeometry(circlePolygon))
)
style.addLayer(
FillLayer("circle-fill", "circle-source")
.withProperties(
fillColor(Color.parseColor("#FF6B35")),
fillOpacity(0.15f)
)
)
style.addLayer(
LineLayer("circle-outline", "circle-source")
.withProperties(
lineColor(Color.parseColor("#FF6B35")),
lineWidth(1.5f),
lineDasharray(arrayOf(2f, 1f))
)
)
}
private fun fitToAll() {
val bounds = LatLngBounds.Builder()
.include(LatLng(48.8606, 2.3376))
.include(LatLng(48.8420, 2.3280))
.include(LatLng(48.8600, 2.3266))
.include(LatLng(48.8560, 2.3350))
.build()
map.easeCamera(
CameraUpdateFactory.newLatLngBounds(bounds, 80),
1000
)
}
private fun createCirclePolygon(center: LatLng, radiusMeters: Double, steps: Int): Polygon {
val points = mutableListOf()
val earthRadius = 6371000.0
for (i in 0..steps) {
val angle = Math.toRadians((360.0 / steps) * i)
val lat = Math.toRadians(center.latitude)
val lng = Math.toRadians(center.longitude)
val newLat = asin(
sin(lat) * cos(radiusMeters / earthRadius) +
cos(lat) * sin(radiusMeters / earthRadius) * cos(angle)
)
val newLng = lng + atan2(
sin(angle) * sin(radiusMeters / earthRadius) * cos(lat),
cos(radiusMeters / earthRadius) - sin(lat) * sin(newLat)
)
points.add(Point.fromLngLat(Math.toDegrees(newLng), Math.toDegrees(newLat)))
}
return Polygon.fromLngLats(listOf(points))
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Layer Rendering Order
Layers render in the order they're added. The correct visual stacking:
```
Top → Annotation markers (always on top)
Symbol layers (icons, labels)
Circle layers (data points)
Line layers (routes, borders)
Bottom → Fill layers (zones, polygons)
```
Use `addLayerBelow` or `addLayerAbove` for precise control:
```kotlin
style.addLayerBelow(fillLayer, "routes-layer") // fills below lines
style.addLayerAbove(circleLayer, "routes-layer") // points above lines
```
## Next Steps
- [Polygon Area](./polygon-area) — Draw filled shapes
- [Polyline Route](./polyline-route) — Draw route lines
- [Draw a Circle](./draw-a-circle) — Circle zones
- [Multiple Data Sources](../data/multiple-sources) — Combining data sources
---
**Tip**: Add fills first, then lines, then points. This ensures points remain clickable on top and lines are visible above filled zones.
---
# Add Multiple Markers with Custom Icons
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/multiple-markers
# Add Multiple Markers with Custom Icons
This tutorial shows how to add many markers with custom icons, categories, and info windows to your MapMetrics Android map.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Multiple Markers from a List
Add markers from a data list with titles and snippets:
```kotlin
import android.graphics.Bitmap
import android.graphics.Canvas
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import androidx.core.content.ContextCompat
import org.maplibre.android.annotations.IconFactory
import org.maplibre.android.annotations.MarkerOptions
import org.maplibre.android.camera.CameraUpdateFactory
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.geometry.LatLngBounds
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class MultipleMarkersActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
data class Place(
val position: LatLng,
val name: String,
val description: String,
val category: String
)
private val places = listOf(
Place(LatLng(48.8584, 2.2945), "Eiffel Tower", "Iconic iron tower, 324m tall", "landmark"),
Place(LatLng(48.8606, 2.3376), "Louvre Museum", "World's largest art museum", "museum"),
Place(LatLng(48.8530, 2.3499), "Notre-Dame", "Medieval Catholic cathedral", "landmark"),
Place(LatLng(48.8738, 2.2950), "Arc de Triomphe", "Triumphal arch monument", "landmark"),
Place(LatLng(48.8462, 2.3464), "Luxembourg Gardens", "Historic public garden", "park"),
Place(LatLng(48.8600, 2.3266), "Musée d'Orsay", "Impressionist art museum", "museum"),
Place(LatLng(48.8867, 2.3431), "Sacré-Cœur", "White-domed basilica", "landmark"),
Place(LatLng(48.8619, 2.3532), "Centre Pompidou", "Modern art museum", "museum"),
)
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
addMarkers()
}
}
}
private fun addMarkers() {
val boundsBuilder = LatLngBounds.Builder()
for (place in places) {
map.addMarker(
MarkerOptions()
.position(place.position)
.title(place.name)
.snippet("${place.category.uppercase()} — ${place.description}")
)
boundsBuilder.include(place.position)
}
// Fit all markers
map.easeCamera(
CameraUpdateFactory.newLatLngBounds(boundsBuilder.build(), 80),
1000
)
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Markers with Custom Vector Icons
Use Android drawable resources as marker icons:
```kotlin
private fun addMarkersWithIcons() {
val iconFactory = IconFactory.getInstance(this)
for (place in places) {
// Pick icon drawable based on category
val drawableRes = when (place.category) {
"landmark" -> R.drawable.ic_landmark
"museum" -> R.drawable.ic_museum
"park" -> R.drawable.ic_park
else -> R.drawable.ic_default_marker
}
// Convert vector drawable to bitmap
val drawable = ContextCompat.getDrawable(this, drawableRes)!!
val bitmap = Bitmap.createBitmap(
drawable.intrinsicWidth,
drawable.intrinsicHeight,
Bitmap.Config.ARGB_8888
)
val canvas = Canvas(bitmap)
drawable.setBounds(0, 0, canvas.width, canvas.height)
drawable.draw(canvas)
val icon = iconFactory.fromBitmap(bitmap)
map.addMarker(
MarkerOptions()
.position(place.position)
.title(place.name)
.snippet(place.description)
.icon(icon)
)
}
}
```
## Symbol Layer Approach (Recommended for Many Markers)
For 50+ markers, use a symbol layer instead of annotation markers for better performance:
```kotlin
import com.google.gson.JsonObject
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.layers.SymbolLayer
import org.maplibre.android.style.sources.GeoJsonSource
import org.maplibre.geojson.Feature
import org.maplibre.geojson.FeatureCollection
import org.maplibre.geojson.Point
private fun addSymbolLayerMarkers(style: Style) {
// Build feature collection from places
val features = places.map { place ->
val properties = JsonObject().apply {
addProperty("name", place.name)
addProperty("description", place.description)
addProperty("category", place.category)
}
Feature.fromGeometry(
Point.fromLngLat(
place.position.longitude,
place.position.latitude
),
properties
)
}
val featureCollection = FeatureCollection.fromFeatures(features)
// Add source
style.addSource(GeoJsonSource("places-source", featureCollection))
// Add symbol layer
style.addLayer(
SymbolLayer("places-layer", "places-source")
.withProperties(
iconImage("marker-15"), // Built-in sprite icon
iconSize(1.5f),
iconAllowOverlap(true),
textField(Expression.get("name")),
textSize(11f),
textOffset(arrayOf(0f, 1.5f)),
textAnchor("top"),
textColor("#333333"),
textHaloColor("#ffffff"),
textHaloWidth(1f)
)
)
// Handle tap on symbols
map.addOnMapClickListener { latLng ->
val screenPoint = map.projection.toScreenLocation(latLng)
val features = map.queryRenderedFeatures(screenPoint, "places-layer")
if (features.isNotEmpty()) {
val name = features[0].getStringProperty("name")
val desc = features[0].getStringProperty("description")
android.widget.Toast.makeText(
this, "$name: $desc", android.widget.Toast.LENGTH_SHORT
).show()
}
true
}
}
```
## Filter Markers by Category
Show/hide markers by category with buttons:
```kotlin
import android.widget.ToggleButton
import org.maplibre.android.style.expressions.Expression
import org.maplibre.android.style.expressions.Expression.*
private fun setupCategoryFilters(style: Style) {
addSymbolLayerMarkers(style) // Add symbol layer first
val layer = style.getLayer("places-layer") as? SymbolLayer
findViewById(R.id.btnLandmarks).setOnCheckedChangeListener { _, checked ->
updateFilter(layer)
}
findViewById(R.id.btnMuseums).setOnCheckedChangeListener { _, checked ->
updateFilter(layer)
}
findViewById(R.id.btnParks).setOnCheckedChangeListener { _, checked ->
updateFilter(layer)
}
}
private fun updateFilter(layer: SymbolLayer?) {
val activeCategories = mutableListOf()
if (findViewById(R.id.btnLandmarks).isChecked) {
activeCategories.add(literal("landmark"))
}
if (findViewById(R.id.btnMuseums).isChecked) {
activeCategories.add(literal("museum"))
}
if (findViewById(R.id.btnParks).isChecked) {
activeCategories.add(literal("park"))
}
if (activeCategories.isEmpty()) {
// Show all when nothing selected
layer?.setFilter(literal(true))
} else {
layer?.setFilter(
match(
get("category"),
literal(false),
*activeCategories.map { stop(it, literal(true)) }.toTypedArray()
)
)
}
}
```
## Annotation vs Symbol Layer
| Feature | Annotation Markers | Symbol Layer |
|---------|-------------------|--------------|
| Performance | Good for < 50 | Scales to thousands |
| Custom views | Full Android views | Icons + text only |
| Built-in info window | Yes | Manual via click query |
| Drag support | Yes | No |
| Data-driven styling | No | Yes (expressions) |
| Filtering | Remove/add manually | `setFilter()` on layer |
## Next Steps
- [Add Markers](../annotations/add-markers) — Annotation marker basics
- [Marker Annotations](../annotations/marker-annotations) — Advanced annotations
- [Add Clusters](./add-a-cluster) — Group dense markers
---
**Tip**: Switch from annotation markers to symbol layers when you have more than ~50 markers. Symbol layers are GPU-rendered and handle thousands of points smoothly, while annotation markers create individual Android views that can cause jank at scale.
---
# Add Navigation Controls
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/navigation-controls
# Add Navigation Controls
This tutorial shows how to add zoom buttons, compass, and location buttons as on-screen controls for your MapMetrics Android map.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Built-in Compass Control
The compass appears automatically when the map is rotated and resets bearing to north on tap:
```kotlin
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class NavigationControlsActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
val ui = map.uiSettings
// Compass — shows when map is rotated, taps resets to north
ui.isCompassEnabled = true
ui.setCompassFadeFacingNorth(true) // hide when facing north
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
)
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8566, 2.3522))
.zoom(12.0)
.build()
}
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Custom Zoom Buttons
Add plus/minus zoom buttons as a floating overlay:
```kotlin
import android.widget.ImageButton
import org.maplibre.android.camera.CameraUpdateFactory
private fun setupZoomControls() {
findViewById(R.id.btnZoomIn).setOnClickListener {
map.animateCamera(CameraUpdateFactory.zoomIn(), 300)
}
findViewById(R.id.btnZoomOut).setOnClickListener {
map.animateCamera(CameraUpdateFactory.zoomOut(), 300)
}
}
```
Layout overlay for zoom buttons:
```xml
```
## My Location Button
Add a button to fly to the user's GPS location:
```kotlin
import android.Manifest
import android.content.pm.PackageManager
import androidx.core.app.ActivityCompat
import org.maplibre.android.location.LocationComponentActivationOptions
import org.maplibre.android.location.modes.CameraMode
private fun setupLocationButton(style: Style) {
findViewById(R.id.btnMyLocation).setOnClickListener {
if (ActivityCompat.checkSelfPermission(
this, Manifest.permission.ACCESS_FINE_LOCATION
) == PackageManager.PERMISSION_GRANTED
) {
enableLocationAndFly(style)
} else {
ActivityCompat.requestPermissions(
this,
arrayOf(Manifest.permission.ACCESS_FINE_LOCATION),
LOCATION_REQUEST_CODE
)
}
}
}
private fun enableLocationAndFly(style: Style) {
val locationComponent = map.locationComponent
locationComponent.activateLocationComponent(
LocationComponentActivationOptions.builder(this, style)
.useDefaultLocationEngine(true)
.build()
)
locationComponent.isLocationComponentEnabled = true
locationComponent.cameraMode = CameraMode.TRACKING
// Fly to current location
locationComponent.lastKnownLocation?.let { location ->
map.animateCamera(
CameraUpdateFactory.newLatLngZoom(
LatLng(location.latitude, location.longitude),
15.0
),
1500
)
}
}
companion object {
private const val LOCATION_REQUEST_CODE = 1001
}
```
## Reset North Button
Reset bearing and tilt to default:
```kotlin
private fun setupResetNorthButton() {
findViewById(R.id.btnNorth).setOnClickListener {
map.animateCamera(
CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder(map.cameraPosition)
.bearing(0.0)
.tilt(0.0)
.build()
),
500
)
}
}
```
## Complete Control Panel
Combine all controls in one overlay:
```xml
```
## Compass Settings
| Setting | XML Attribute | Description |
|---------|--------------|-------------|
| `isCompassEnabled` | `maplibre_uiCompass` | Show/hide compass |
| `setCompassFadeFacingNorth` | `maplibre_uiCompassFadeFacingNorth` | Auto-hide when north up |
| `compassGravity` | `maplibre_uiCompassGravity` | Screen position |
## Next Steps
- [Zoom Methods](../camera/zoom-methods) — Zoom API reference
- [Location Component](../location-component) — User location tracking
- [Set Pitch & Bearing](../camera/set-pitch-bearing) — 3D camera controls
---
**Tip**: On mobile, keep navigation controls small (40-48dp) and place them on the right edge so they don't overlap the map's built-in compass (top-left by default) or attribution (bottom-left).
---
# Draw a Polygon Area
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/polygon-area
# Draw a Polygon Area
This tutorial shows how to draw filled polygon shapes on your MapMetrics Android map — useful for highlighting zones, districts, or geofences.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Basic Polygon with Fill
Add a filled polygon using a GeoJSON source and fill layer:
```kotlin
import android.graphics.Color
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
import org.maplibre.android.style.layers.FillLayer
import org.maplibre.android.style.layers.LineLayer
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.sources.GeoJsonSource
import org.maplibre.geojson.Feature
import org.maplibre.geojson.FeatureCollection
import org.maplibre.geojson.Point
import org.maplibre.geojson.Polygon
class PolygonActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
addPolygon(style)
}
}
}
private fun addPolygon(style: Style) {
// Define polygon vertices (must form a closed ring)
val polygonPoints = listOf(
listOf(
Point.fromLngLat(2.3200, 48.8700),
Point.fromLngLat(2.3800, 48.8700),
Point.fromLngLat(2.3800, 48.8400),
Point.fromLngLat(2.3200, 48.8400),
Point.fromLngLat(2.3200, 48.8700) // Close the ring
)
)
val polygon = Polygon.fromLngLats(polygonPoints)
val feature = Feature.fromGeometry(polygon)
// Add GeoJSON source
style.addSource(GeoJsonSource("polygon-source", feature))
// Add fill layer
style.addLayer(
FillLayer("polygon-fill", "polygon-source").withProperties(
fillColor(Color.parseColor("#4285F4")),
fillOpacity(0.3f)
)
)
// Add outline layer
style.addLayer(
LineLayer("polygon-outline", "polygon-source").withProperties(
lineColor(Color.parseColor("#4285F4")),
lineWidth(2f),
lineOpacity(0.8f)
)
)
// Center camera on polygon
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.855, 2.350))
.zoom(13.0)
.build()
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Multiple Colored Zones
Display several zones with different colors:
```kotlin
private fun addMultipleZones(style: Style) {
data class Zone(
val id: String,
val points: List,
val color: String,
val name: String
)
val zones = listOf(
Zone(
"zone-a",
listOf(
Point.fromLngLat(2.32, 48.87),
Point.fromLngLat(2.35, 48.87),
Point.fromLngLat(2.35, 48.855),
Point.fromLngLat(2.32, 48.855),
Point.fromLngLat(2.32, 48.87),
),
"#FF6B35", "District A"
),
Zone(
"zone-b",
listOf(
Point.fromLngLat(2.35, 48.87),
Point.fromLngLat(2.38, 48.87),
Point.fromLngLat(2.38, 48.855),
Point.fromLngLat(2.35, 48.855),
Point.fromLngLat(2.35, 48.87),
),
"#34A853", "District B"
),
Zone(
"zone-c",
listOf(
Point.fromLngLat(2.32, 48.855),
Point.fromLngLat(2.38, 48.855),
Point.fromLngLat(2.38, 48.84),
Point.fromLngLat(2.32, 48.84),
Point.fromLngLat(2.32, 48.855),
),
"#9C27B0", "District C"
),
)
for (zone in zones) {
val polygon = Polygon.fromLngLats(listOf(zone.points))
val feature = Feature.fromGeometry(polygon)
style.addSource(GeoJsonSource("${zone.id}-source", feature))
style.addLayer(
FillLayer("${zone.id}-fill", "${zone.id}-source").withProperties(
fillColor(Color.parseColor(zone.color)),
fillOpacity(0.3f)
)
)
style.addLayer(
LineLayer("${zone.id}-outline", "${zone.id}-source").withProperties(
lineColor(Color.parseColor(zone.color)),
lineWidth(2f)
)
)
}
}
```
## Clickable Polygon
Show info when the user taps inside a polygon:
```kotlin
private fun addClickablePolygon(style: Style) {
addPolygon(style) // Add polygon first
map.addOnMapClickListener { latLng ->
// Query the polygon layer at the tap point
val screenPoint = map.projection.toScreenLocation(latLng)
val features = map.queryRenderedFeatures(screenPoint, "polygon-fill")
if (features.isNotEmpty()) {
android.widget.Toast.makeText(
this,
"Tapped inside polygon!",
android.widget.Toast.LENGTH_SHORT
).show()
}
true
}
}
```
## Fill Layer Properties
| Property | Type | Description |
|----------|------|-------------|
| `fillColor` | Color/Expression | Fill color |
| `fillOpacity` | Float | Fill transparency (0.0 - 1.0) |
| `fillOutlineColor` | Color | Border color (1px only) |
| `fillAntialias` | Boolean | Smooth edges (default: true) |
## Next Steps
- [GeoJSON Guide](../geojson-guide) — Load polygons from GeoJSON files
- [Data-Driven Styling](../styling/data-driven-style) — Color polygons by data properties
- [Building Layer](../styling/building-layer) — 3D extruded polygons
---
**Tip**: Always close polygon rings — the first and last point must be identical. For outlines thicker than 1px, add a separate `LineLayer` on top of the `FillLayer` as shown above.
---
# Show Polygon Info on Click
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/polygon-info-on-click
# Show Polygon Info on Click
This tutorial shows how to display information about a polygon zone when users tap inside it on your MapMetrics Android map.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Clickable Polygons with Info
Create named zones and show details on tap:
```kotlin
import android.graphics.Color
import android.os.Bundle
import android.widget.TextView
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import com.google.gson.JsonObject
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
import org.maplibre.android.style.expressions.Expression.*
import org.maplibre.android.style.layers.FillLayer
import org.maplibre.android.style.layers.LineLayer
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.sources.GeoJsonSource
import org.maplibre.geojson.*
class PolygonInfoActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
private lateinit var infoPanel: TextView
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_polygon_info)
infoPanel = findViewById(R.id.tvInfo)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
addZones(style)
setupClickHandler()
}
}
}
private fun addZones(style: Style) {
val zones = listOf(
createZoneFeature(
"zone-1", "Le Marais",
"Historic district, popular for art galleries and cafés",
"#FF6B35",
listOf(
Point.fromLngLat(2.3500, 48.8600),
Point.fromLngLat(2.3650, 48.8600),
Point.fromLngLat(2.3650, 48.8530),
Point.fromLngLat(2.3500, 48.8530),
Point.fromLngLat(2.3500, 48.8600),
)
),
createZoneFeature(
"zone-2", "Saint-Germain",
"Left Bank intellectual quarter with bookshops and bistros",
"#4285F4",
listOf(
Point.fromLngLat(2.3200, 48.8550),
Point.fromLngLat(2.3400, 48.8550),
Point.fromLngLat(2.3400, 48.8480),
Point.fromLngLat(2.3200, 48.8480),
Point.fromLngLat(2.3200, 48.8550),
)
),
createZoneFeature(
"zone-3", "Montmartre",
"Hilltop village known for Sacré-Cœur and street artists",
"#34A853",
listOf(
Point.fromLngLat(2.3300, 48.8900),
Point.fromLngLat(2.3500, 48.8900),
Point.fromLngLat(2.3500, 48.8830),
Point.fromLngLat(2.3300, 48.8830),
Point.fromLngLat(2.3300, 48.8900),
)
),
)
style.addSource(
GeoJsonSource("zones-source", FeatureCollection.fromFeatures(zones))
)
// Fill layer — colored by feature property
style.addLayer(
FillLayer("zones-fill", "zones-source")
.withProperties(
fillColor(get("color")),
fillOpacity(0.25f)
)
)
// Outline
style.addLayer(
LineLayer("zones-outline", "zones-source")
.withProperties(
lineColor(get("color")),
lineWidth(2f)
)
)
// Camera
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.865, 2.340))
.zoom(12.5)
.build()
}
private fun createZoneFeature(
id: String,
name: String,
description: String,
color: String,
points: List
): Feature {
val props = JsonObject().apply {
addProperty("id", id)
addProperty("name", name)
addProperty("description", description)
addProperty("color", color)
}
return Feature.fromGeometry(
Polygon.fromLngLats(listOf(points)),
props,
id
)
}
private fun setupClickHandler() {
map.addOnMapClickListener { latLng ->
val screenPoint = map.projection.toScreenLocation(latLng)
val features = map.queryRenderedFeatures(screenPoint, "zones-fill")
if (features.isNotEmpty()) {
val feature = features[0]
val name = feature.getStringProperty("name") ?: "Unknown"
val description = feature.getStringProperty("description") ?: ""
// Show in info panel
infoPanel.text = "$name\n$description"
infoPanel.visibility = android.view.View.VISIBLE
// Highlight the tapped zone
highlightZone(feature.getStringProperty("id"))
} else {
infoPanel.visibility = android.view.View.GONE
clearHighlight()
}
true
}
}
private fun highlightZone(zoneId: String?) {
val layer = map.style?.getLayer("zones-fill") as? FillLayer
layer?.setProperties(
fillOpacity(
match(
get("id"),
literal(0.15f), // default: dim
stop(zoneId ?: "", literal(0.5f)) // highlighted: bright
)
)
)
}
private fun clearHighlight() {
val layer = map.style?.getLayer("zones-fill") as? FillLayer
layer?.setProperties(fillOpacity(0.25f))
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
Layout (`res/layout/activity_polygon_info.xml`):
```xml
```
## Next Steps
- [Polygon Area](./polygon-area) — Drawing polygon shapes
- [Filter Features](../styling/filter-features) — Data-driven filtering
- [Map Click Events](./map-click-events) — General click handling
---
**Tip**: Use `queryRenderedFeatures` with the specific layer ID (`"zones-fill"`) to only detect polygon taps. Without a layer filter, it would also match road labels, building polygons, and other style features under the tap point.
---
# Draw a Polyline Route
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/polyline-route
# Draw a Polyline Route
This tutorial shows how to draw polyline routes on your MapMetrics Android map using both the annotation API and GeoJSON line layers.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Using a GeoJSON Line Layer
The recommended approach — add a styled line from GeoJSON data:
```kotlin
import android.graphics.Color
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.camera.CameraUpdateFactory
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.geometry.LatLngBounds
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
import org.maplibre.android.style.layers.LineLayer
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.sources.GeoJsonSource
import org.maplibre.geojson.Feature
import org.maplibre.geojson.FeatureCollection
import org.maplibre.geojson.LineString
import org.maplibre.geojson.Point
class PolylineActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
addRoute(style)
}
}
}
private fun addRoute(style: Style) {
// Define route points
val routePoints = listOf(
Point.fromLngLat(2.3522, 48.8566), // Paris
Point.fromLngLat(4.3517, 50.8503), // Brussels
Point.fromLngLat(4.9041, 52.3676), // Amsterdam
Point.fromLngLat(9.9937, 53.5511), // Hamburg
Point.fromLngLat(13.4050, 52.5200), // Berlin
)
// Create GeoJSON line feature
val lineString = LineString.fromLngLats(routePoints)
val feature = Feature.fromGeometry(lineString)
val featureCollection = FeatureCollection.fromFeature(feature)
// Add source
style.addSource(GeoJsonSource("route-source", featureCollection))
// Add line layer
style.addLayer(
LineLayer("route-layer", "route-source").withProperties(
lineColor(Color.parseColor("#4285F4")),
lineWidth(4f),
lineOpacity(0.8f)
)
)
// Fit camera to route
val bounds = LatLngBounds.Builder()
for (point in routePoints) {
bounds.include(LatLng(point.latitude(), point.longitude()))
}
map.easeCamera(
CameraUpdateFactory.newLatLngBounds(bounds.build(), 80),
1000
)
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Styled Route with Markers at Stops
Add start/end markers along the route:
```kotlin
private fun addStyledRoute(style: Style) {
val stops = listOf(
Pair(Point.fromLngLat(2.3522, 48.8566), "Paris"),
Pair(Point.fromLngLat(4.3517, 50.8503), "Brussels"),
Pair(Point.fromLngLat(4.9041, 52.3676), "Amsterdam"),
Pair(Point.fromLngLat(13.4050, 52.5200), "Berlin"),
)
val routePoints = stops.map { it.first }
// Line source and layer
val lineString = LineString.fromLngLats(routePoints)
style.addSource(GeoJsonSource("route-source", Feature.fromGeometry(lineString)))
style.addLayer(
LineLayer("route-layer", "route-source").withProperties(
lineColor(Color.parseColor("#FF6B35")),
lineWidth(5f),
lineOpacity(0.9f),
lineJoin("round")
)
)
// Add markers at each stop
for ((point, name) in stops) {
map.addMarker(
org.maplibre.android.annotations.MarkerOptions()
.position(LatLng(point.latitude(), point.longitude()))
.title(name)
)
}
}
```
## Dashed Line
Create a dashed polyline using `lineDasharray`:
```kotlin
style.addLayer(
LineLayer("dashed-route", "route-source").withProperties(
lineColor(Color.parseColor("#333333")),
lineWidth(3f),
lineDasharray(arrayOf(2f, 1f)) // 2px dash, 1px gap
)
)
```
## Multiple Route Layers
Show different route options with different colors:
```kotlin
private fun addMultipleRoutes(style: Style) {
// Route 1 — fastest
val fastRoute = listOf(
Point.fromLngLat(2.3522, 48.8566),
Point.fromLngLat(6.1296, 49.8153),
Point.fromLngLat(13.4050, 52.5200),
)
// Route 2 — scenic
val scenicRoute = listOf(
Point.fromLngLat(2.3522, 48.8566),
Point.fromLngLat(4.3517, 50.8503),
Point.fromLngLat(4.9041, 52.3676),
Point.fromLngLat(9.9937, 53.5511),
Point.fromLngLat(13.4050, 52.5200),
)
// Fast route — blue, thicker
style.addSource(
GeoJsonSource("fast-source",
Feature.fromGeometry(LineString.fromLngLats(fastRoute)))
)
style.addLayer(
LineLayer("fast-layer", "fast-source").withProperties(
lineColor(Color.parseColor("#4285F4")),
lineWidth(5f),
lineOpacity(0.9f)
)
)
// Scenic route — green, thinner
style.addSource(
GeoJsonSource("scenic-source",
Feature.fromGeometry(LineString.fromLngLats(scenicRoute)))
)
style.addLayer(
LineLayer("scenic-layer", "scenic-source").withProperties(
lineColor(Color.parseColor("#34A853")),
lineWidth(3f),
lineOpacity(0.7f)
)
)
}
```
## Line Layer Properties
| Property | Type | Description |
|----------|------|-------------|
| `lineColor` | Color | Line color |
| `lineWidth` | Float | Width in pixels |
| `lineOpacity` | Float | Transparency (0.0 - 1.0) |
| `lineJoin` | String | `"round"`, `"bevel"`, `"miter"` |
| `lineCap` | String | `"round"`, `"butt"`, `"square"` |
| `lineDasharray` | Array | Dash and gap lengths |
## Next Steps
- [GeoJSON Guide](../geojson-guide) — Working with GeoJSON data
- [Data-Driven Lines](../styling/data-driven-style) — Style lines by properties
- [Polygon Area](./polygon-area) — Draw filled shapes
---
**Tip**: For route lines that pass beneath map labels, use `style.addLayerBelow(layer, "labelLayerId")` to insert the line layer below the label layer in the rendering stack.
---
# Restrict Map Panning to a Region
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/restrict-panning
# Restrict Map Panning to a Region
This tutorial shows how to limit the map view to a specific geographic area — useful for city-specific apps, campus maps, or regional applications.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Restrict Using Camera Bounds
Constrain the map so users cannot pan outside a bounding box:
```kotlin
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.geometry.LatLngBounds
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class RestrictPanActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
// Paris bounding box
private val parisBounds = LatLngBounds.Builder()
.include(LatLng(48.9020, 2.4700)) // Northeast
.include(LatLng(48.8100, 2.2200)) // Southwest
.build()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
// Set the bounds constraint
map.setLatLngBoundsForCameraTarget(parisBounds)
// Also restrict zoom range
map.setMinZoomPreference(10.0)
map.setMaxZoomPreference(18.0)
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
)
// Center on Paris
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8566, 2.3522))
.zoom(12.0)
.build()
}
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Switchable Region Constraints
Let users switch between predefined regions:
```kotlin
import android.widget.Button
import org.maplibre.android.camera.CameraUpdateFactory
private val regions = mapOf(
"Paris" to Pair(
LatLngBounds.Builder()
.include(LatLng(48.9020, 2.4700))
.include(LatLng(48.8100, 2.2200))
.build(),
LatLng(48.8566, 2.3522)
),
"London" to Pair(
LatLngBounds.Builder()
.include(LatLng(51.6723, 0.1480))
.include(LatLng(51.3850, -0.3517))
.build(),
LatLng(51.5074, -0.1278)
),
"Berlin" to Pair(
LatLngBounds.Builder()
.include(LatLng(52.6755, 13.7611))
.include(LatLng(52.3383, 13.0884))
.build(),
LatLng(52.5200, 13.4050)
),
)
private fun setupRegionButtons() {
findViewById(R.id.btnParis).setOnClickListener { switchRegion("Paris") }
findViewById(R.id.btnLondon).setOnClickListener { switchRegion("London") }
findViewById(R.id.btnBerlin).setOnClickListener { switchRegion("Berlin") }
}
private fun switchRegion(name: String) {
regions[name]?.let { (bounds, center) ->
// Update bounds constraint
map.setLatLngBoundsForCameraTarget(bounds)
// Fly to the new region
map.animateCamera(
CameraUpdateFactory.newLatLngZoom(center, 12.0),
1500
)
}
}
```
## Restrict with Zoom Constraints
Combine panning bounds with zoom limits:
```kotlin
// Allow only zoom levels 11-16
map.setMinZoomPreference(11.0)
map.setMaxZoomPreference(16.0)
// Restrict panning area
map.setLatLngBoundsForCameraTarget(parisBounds)
// Disable rotation and tilt for a fixed 2D view
map.uiSettings.isRotateGesturesEnabled = false
map.uiSettings.isTiltGesturesEnabled = false
```
## Remove Restrictions
Clear all constraints at runtime:
```kotlin
// Remove panning bounds
map.setLatLngBoundsForCameraTarget(null)
// Reset zoom limits
map.setMinZoomPreference(0.0)
map.setMaxZoomPreference(22.0)
// Re-enable all gestures
map.uiSettings.setAllGesturesEnabled(true)
```
## Next Steps
- [Max/Min Zoom](../camera/max-min-zoom) — Zoom level constraints
- [Disable Gestures](./disable-gestures) — Control individual gestures
- [Lat-Lng Bounds](../camera/lat-lng-bounds) — Bounds API reference
---
**Tip**: Set min zoom high enough that the bounds fill the screen — if users can zoom out too far, they'll see the restricted area as a small box on a larger map, which looks odd. Typically `minZoom = 10-12` works well for city-level restrictions.
---
# Slowly Fly to a Location
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/slowly-fly-to-location
# Slowly Fly to a Location
This tutorial shows how to create a cinematic slow camera flight — useful for showcases, presentations, or atmospheric map experiences.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Cinematic Slow Flight
A long-duration animated camera move with tilt and bearing changes:
```kotlin
import android.os.Bundle
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.camera.CameraUpdateFactory
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class SlowFlyActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_slow_fly)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
)
// Start from a wide aerial view
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8566, 2.3522)) // Paris overview
.zoom(10.0)
.tilt(0.0)
.bearing(0.0)
.build()
// Slow fly button
findViewById(R.id.btnSlowFly).setOnClickListener {
slowFlyToEiffelTower()
}
}
}
private fun slowFlyToEiffelTower() {
val destination = CameraPosition.Builder()
.target(LatLng(48.8584, 2.2945)) // Eiffel Tower
.zoom(17.0) // Street level
.tilt(60.0) // Dramatic 3D angle
.bearing(-30.0) // Slight rotation
.build()
map.animateCamera(
CameraUpdateFactory.newCameraPosition(destination),
10000 // 10 seconds — slow, cinematic
)
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Multi-Stage Cinematic Sequence
Chain multiple slow flights for a full cinematic experience:
```kotlin
private data class CinematicStop(
val target: LatLng,
val zoom: Double,
val tilt: Double,
val bearing: Double,
val flightDuration: Long, // ms to fly there
val pauseDuration: Long // ms to pause before next
)
private val cinematicStops = listOf(
CinematicStop(
LatLng(48.8566, 2.3522), 11.0, 0.0, 0.0,
0, 1000 // Start: Paris overview
),
CinematicStop(
LatLng(48.8584, 2.2945), 16.0, 55.0, -20.0,
8000, 3000 // Fly to Eiffel Tower
),
CinematicStop(
LatLng(48.8606, 2.3376), 16.5, 50.0, 30.0,
6000, 3000 // Fly to Louvre
),
CinematicStop(
LatLng(48.8530, 2.3499), 17.0, 60.0, -10.0,
6000, 3000 // Fly to Notre-Dame
),
CinematicStop(
LatLng(48.8867, 2.3431), 15.5, 45.0, 0.0,
8000, 2000 // Fly to Sacré-Cœur
),
)
private fun startCinematicTour() {
playCinematicStop(0)
}
private fun playCinematicStop(index: Int) {
if (index >= cinematicStops.size) return
val stop = cinematicStops[index]
val position = CameraPosition.Builder()
.target(stop.target)
.zoom(stop.zoom)
.tilt(stop.tilt)
.bearing(stop.bearing)
.build()
if (stop.flightDuration == 0L) {
// First stop — instant position
map.moveCamera(CameraUpdateFactory.newCameraPosition(position))
android.os.Handler(android.os.Looper.getMainLooper()).postDelayed({
playCinematicStop(index + 1)
}, stop.pauseDuration)
} else {
map.animateCamera(
CameraUpdateFactory.newCameraPosition(position),
stop.flightDuration.toInt(),
object : MapLibreMap.CancelableCallback {
override fun onFinish() {
android.os.Handler(android.os.Looper.getMainLooper()).postDelayed({
playCinematicStop(index + 1)
}, stop.pauseDuration)
}
override fun onCancel() {
// User interrupted — stop the tour
}
}
)
}
}
```
## Slow Fly with easeCamera
Use `easeCamera` for a constant-speed flight (no acceleration):
```kotlin
private fun slowEaseFlight() {
map.easeCamera(
CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder()
.target(LatLng(48.8584, 2.2945))
.zoom(16.0)
.tilt(50.0)
.bearing(-15.0)
.build()
),
15000 // 15 seconds, constant speed
)
}
```
## Speed Comparison
| Duration | Feel | Use Case |
|----------|------|----------|
| 1-2s | Quick snap | UI navigation |
| 3-5s | Normal fly-to | Standard interaction |
| 6-10s | Slow, cinematic | Showcase, guided tour |
| 10-20s | Very slow | Presentation, ambient display |
| `easeCamera` 10s+ | Constant speed, no acceleration | Smooth documentary feel |
## Next Steps
- [Fly to a Location](./fly-to-location) — Standard fly-to animation
- [Orbit Animation](../camera/orbit-animation) — Rotating camera
- [Jump to Locations](./jump-to-locations) — Step through waypoints
---
**Tip**: For the most cinematic effect, combine slow flights (8-15s) with tilt changes (0° → 60°) and slight bearing shifts. The simultaneous zoom + tilt + bearing creates the "Google Earth" swooping effect.
---
# Sync Multiple Maps Side by Side
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/sync-multiple-maps
# Sync Multiple Maps Side by Side
This tutorial shows how to display two MapMetrics maps side by side and keep their camera positions synchronized — useful for comparing map styles, before/after views, or satellite vs. street map.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Synchronized Dual Maps
Create two maps that stay in sync:
```kotlin
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.camera.CameraUpdateFactory
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class SyncMapsActivity : AppCompatActivity() {
private lateinit var mapViewLeft: MapView
private lateinit var mapViewRight: MapView
private var mapLeft: MapLibreMap? = null
private var mapRight: MapLibreMap? = null
private var isSyncing = false // prevent infinite loop
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_sync_maps)
mapViewLeft = findViewById(R.id.mapViewLeft)
mapViewRight = findViewById(R.id.mapViewRight)
mapViewLeft.onCreate(savedInstanceState)
mapViewRight.onCreate(savedInstanceState)
// Initialize left map
mapViewLeft.getMapAsync { map ->
mapLeft = map
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/STYLE_A?token=YOUR_API_KEY"
)
)
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8566, 2.3522))
.zoom(12.0)
.build()
setupSync()
}
// Initialize right map
mapViewRight.getMapAsync { map ->
mapRight = map
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/STYLE_B?token=YOUR_API_KEY"
)
)
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8566, 2.3522))
.zoom(12.0)
.build()
setupSync()
}
}
private fun setupSync() {
// Only set up once both maps are ready
if (mapLeft == null || mapRight == null) return
// Sync left → right
mapLeft?.addOnCameraMoveListener {
if (isSyncing) return@addOnCameraMoveListener
isSyncing = true
mapLeft?.cameraPosition?.let { pos ->
mapRight?.moveCamera(
CameraUpdateFactory.newCameraPosition(pos)
)
}
isSyncing = false
}
// Sync right → left
mapRight?.addOnCameraMoveListener {
if (isSyncing) return@addOnCameraMoveListener
isSyncing = true
mapRight?.cameraPosition?.let { pos ->
mapLeft?.moveCamera(
CameraUpdateFactory.newCameraPosition(pos)
)
}
isSyncing = false
}
}
// Lifecycle — must forward to BOTH map views
override fun onStart() {
super.onStart()
mapViewLeft.onStart()
mapViewRight.onStart()
}
override fun onResume() {
super.onResume()
mapViewLeft.onResume()
mapViewRight.onResume()
}
override fun onPause() {
super.onPause()
mapViewLeft.onPause()
mapViewRight.onPause()
}
override fun onStop() {
super.onStop()
mapViewLeft.onStop()
mapViewRight.onStop()
}
override fun onDestroy() {
super.onDestroy()
mapViewLeft.onDestroy()
mapViewRight.onDestroy()
}
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapViewLeft.onSaveInstanceState(outState)
mapViewRight.onSaveInstanceState(outState)
}
}
```
Layout (`res/layout/activity_sync_maps.xml`):
```xml
```
## Vertical Split (Top/Bottom)
For portrait orientation, stack maps vertically:
```xml
```
## Style Comparison Use Cases
| Left Map | Right Map | Purpose |
|----------|-----------|---------|
| Streets | Satellite | Terrain comparison |
| Light theme | Dark theme | Theme preview |
| Current data | Historical data | Time comparison |
| Default style | Custom style | Style development |
## Next Steps
- [Custom Styling](../styling/custom-styling) — Map style customization
- [Fly to a Location](./fly-to-location) — Camera animations
- [Configuration](../configuration) — Map options
---
**Tip**: The `isSyncing` flag is critical — without it, map A's move triggers map B's listener, which triggers map A's listener, creating an infinite loop. Always guard against re-entrant sync.
---
# Toggle Map Interactions
https://docs.mapatlas.xyz/overview/sdk/android-native/interactions/toggle-interactions
# Toggle Map Interactions
This tutorial shows how to individually enable and disable specific map gestures at runtime — giving users fine-grained control over how they interact with the map.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Interactive Toggle Panel
Create a panel of switches to control each gesture:
```kotlin
import android.os.Bundle
import android.widget.Switch
import android.widget.TextView
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class ToggleInteractionsActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_toggle_interactions)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
)
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8566, 2.3522))
.zoom(13.0)
.tilt(30.0)
.build()
setupToggles()
}
}
private fun setupToggles() {
val ui = map.uiSettings
// Scroll (pan)
bindToggle(R.id.switchScroll, "Scroll/Pan", ui.isScrollGesturesEnabled) {
ui.isScrollGesturesEnabled = it
}
// Zoom (pinch)
bindToggle(R.id.switchZoom, "Pinch Zoom", ui.isZoomGesturesEnabled) {
ui.isZoomGesturesEnabled = it
}
// Double-tap zoom
bindToggle(R.id.switchDoubleTap, "Double-Tap Zoom", ui.isDoubleTapGesturesEnabled) {
ui.isDoubleTapGesturesEnabled = it
}
// Rotate
bindToggle(R.id.switchRotate, "Rotate", ui.isRotateGesturesEnabled) {
ui.isRotateGesturesEnabled = it
}
// Tilt
bindToggle(R.id.switchTilt, "Tilt", ui.isTiltGesturesEnabled) {
ui.isTiltGesturesEnabled = it
}
// Fling momentum
bindToggle(R.id.switchFling, "Fling Momentum", ui.isFlingVelocityAnimationEnabled) {
ui.isFlingVelocityAnimationEnabled = it
}
}
private fun bindToggle(
viewId: Int,
label: String,
initialValue: Boolean,
onChange: (Boolean) -> Unit
) {
findViewById(viewId).apply {
text = label
isChecked = initialValue
setOnCheckedChangeListener { _, checked -> onChange(checked) }
}
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
Layout (`res/layout/activity_toggle_interactions.xml`):
```xml
```
## Preset Interaction Modes
Quickly switch between common configurations:
```kotlin
import android.widget.Button
private fun setupPresets() {
val ui = map.uiSettings
// Full interaction
findViewById(R.id.btnFullMode).setOnClickListener {
ui.setAllGesturesEnabled(true)
ui.isFlingVelocityAnimationEnabled = true
refreshToggles()
}
// View-only (no interaction)
findViewById(R.id.btnViewOnly).setOnClickListener {
ui.setAllGesturesEnabled(false)
ui.isFlingVelocityAnimationEnabled = false
refreshToggles()
}
// Pan-only (embedded map)
findViewById(R.id.btnPanOnly).setOnClickListener {
ui.isScrollGesturesEnabled = true
ui.isZoomGesturesEnabled = false
ui.isDoubleTapGesturesEnabled = false
ui.isRotateGesturesEnabled = false
ui.isTiltGesturesEnabled = false
refreshToggles()
}
// 2D mode (no rotate/tilt)
findViewById(R.id.btn2dMode).setOnClickListener {
ui.isScrollGesturesEnabled = true
ui.isZoomGesturesEnabled = true
ui.isDoubleTapGesturesEnabled = true
ui.isRotateGesturesEnabled = false
ui.isTiltGesturesEnabled = false
// Reset to flat view
map.animateCamera(
org.maplibre.android.camera.CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder(map.cameraPosition)
.bearing(0.0)
.tilt(0.0)
.build()
),
500
)
refreshToggles()
}
}
private fun refreshToggles() {
val ui = map.uiSettings
findViewById(R.id.switchScroll).isChecked = ui.isScrollGesturesEnabled
findViewById(R.id.switchZoom).isChecked = ui.isZoomGesturesEnabled
findViewById(R.id.switchDoubleTap).isChecked = ui.isDoubleTapGesturesEnabled
findViewById(R.id.switchRotate).isChecked = ui.isRotateGesturesEnabled
findViewById(R.id.switchTilt).isChecked = ui.isTiltGesturesEnabled
findViewById(R.id.switchFling).isChecked = ui.isFlingVelocityAnimationEnabled
}
```
## Next Steps
- [Disable Gestures](./disable-gestures) — Static map and gesture settings
- [Gesture Detector](../camera/gesture-detector) — Advanced gesture handling
- [Game-Style Controls](./game-controls) — D-pad navigation
---
**Tip**: For maps embedded inside scrollable content (like a `RecyclerView`), disable scroll and zoom gestures so the map doesn't steal touch events from the parent scroll view.
---
# LocationComponent
https://docs.mapatlas.xyz/overview/sdk/android-native/location-component
# LocationComponent
This guide will demonstrate how to utilize the [LocationComponent] to represent the user's current location.
When implementing the [LocationComponent], the application should request location permissions. Declare the need for foreground location in the `AndroidManifest.xml` file. For more information, please refer to the [Android Developer Documentation].
```xml
```
Create a new activity named `BasicLocationPulsingCircleActivity`:
- This Activity should implement the `OnMapReadyCallback` interface. The `onMapReady()` method is triggered when the map is ready to be used.
- Add a variable `permissionsManager` to manage permissions.
- Add a variable `locationComponent` to manage user location.
- At the end of the `onCreate()` method, call `checkPermissions()` to ensure that the application can access the user's location.
```kotlin
/**
* This activity shows a basic usage of the LocationComponent's pulsing circle. There's no
* customization of the pulsing circle's color, radius, speed, etc.
*/
class BasicLocationPulsingCircleActivity : AppCompatActivity(), OnMapReadyCallback {
private var lastLocation: Location? = null
private lateinit var mapView: MapView
private var permissionsManager: PermissionsManager? = null
private var locationComponent: LocationComponent? = null
private lateinit var maplibreMap: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_location_layer_basic_pulsing_circle)
mapView = findViewById(R.id.mapView)
if (savedInstanceState != null) {
lastLocation =
savedInstanceState.getParcelable(SAVED_STATE_LOCATION, Location::class.java)
}
mapView.onCreate(savedInstanceState)
checkPermissions()
}}
```
In the `checkPermissions()` method, the [PermissionManager] is used to request location permissions at runtime and handle the callbacks for permission granting or rejection.Additionally, you should pass the results of `Activity.onRequestPermissionResult()` to it. If the permissions are granted, call `mapView.getMapAsync(this)` to register the activity as a listener for onMapReady event.
```kotlin
private fun checkPermissions() {
if (PermissionsManager.areLocationPermissionsGranted(this)) {
mapView.getMapAsync(this)
} else {
permissionsManager = PermissionsManager(object : PermissionsListener {
override fun onExplanationNeeded(permissionsToExplain: List) {
Toast.makeText(
this@BasicLocationPulsingCircleActivity,
"You need to accept location permissions.",
Toast.LENGTH_SHORT
).show()
}
override fun onPermissionResult(granted: Boolean) {
if (granted) {
mapView.getMapAsync(this@BasicLocationPulsingCircleActivity)
} else {
finish()
}
}
})
permissionsManager!!.requestLocationPermissions(this)
}
}
override fun onRequestPermissionsResult(
requestCode: Int,
permissions: Array,
grantResults: IntArray
) {
super.onRequestPermissionsResult(requestCode, permissions, grantResults)
permissionsManager!!.onRequestPermissionsResult(requestCode, permissions, grantResults)
}
```
In the `onMapReady()` method, first set the style and then handle the user's location using the [LocationComponent].
To configure the [LocationComponent], developers should use [LocationComponentOptions].
In this demonstration, we create an instance of this class.
In this method:
- Use the annotation `@SuppressLint("MissingPermission")` to suppress warnings related to missing location access permissions.
- In `setStyle(),` you can pass a MapMetrics Atlas gateway style URL — `https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY` — instead of one of the [predefined styles].
- For the builder of [LocationComponentOptions], use `pulseEnabled(true)` to enable the pulse animation, which enhances awareness of the user's location.
- Use method `buildLocationComponentActivationOptions()` to set [LocationComponentActivationOptions], then activate `locatinoComponent` with it.
- To apply options, make sure you call `activateLocationComponent()` of `locationComponent`. You can also set `locationComponent`'s various properties like `isLocationComponentEnabled` , `cameraMode` , etc...
- `CameraMode.TRACKING`[^1] means that when the user's location is updated, the camera will reposition accordingly.
- `locationComponent!!.forceLocationUpdate(lastLocation)` updates the the user's last known location.
```kotlin
@SuppressLint("MissingPermission")
override fun onMapReady(maplibreMap: MapLibreMap) {
this.maplibreMap = maplibreMap
maplibreMap.setStyle(TestStyles.getPredefinedStyleWithFallback("Streets")) { style: Style ->
locationComponent = maplibreMap.locationComponent
val locationComponentOptions =
LocationComponentOptions.builder(this@BasicLocationPulsingCircleActivity)
.pulseEnabled(true)
.build()
val locationComponentActivationOptions =
buildLocationComponentActivationOptions(style, locationComponentOptions)
locationComponent!!.activateLocationComponent(locationComponentActivationOptions)
locationComponent!!.isLocationComponentEnabled = true
locationComponent!!.cameraMode = CameraMode.TRACKING
locationComponent!!.forceLocationUpdate(lastLocation)
}
}
```
[LocationComponentActivationOptions] is used to hold the style, [LocationComponentOptions] and other locating behaviors.
- It can also be used to configure how to obtain the current location, such as [LocationEngine] and intervals.
- In this demonstration, it sets 750ms as the fastest interval for location updates, providing high accuracy location results (but with higher power consumption).
- For more information, please visit the [documentation page][LocationComponentActivationOptions].
```kotlin
private fun buildLocationComponentActivationOptions(
style: Style,
locationComponentOptions: LocationComponentOptions
): LocationComponentActivationOptions {
return LocationComponentActivationOptions
.builder(this, style)
.locationComponentOptions(locationComponentOptions)
.useDefaultLocationEngine(true)
.locationEngineRequest(
LocationEngineRequest.Builder(750)
.setFastestInterval(750)
.setPriority(LocationEngineRequest.PRIORITY_HIGH_ACCURACY)
.build()
)
.build()
}
```
For further customization, you can also utilize the `foregroundTintColor()` and `pulseColor()` methods on the [LocationComponentOptions] builder:
```kotlin
val locationComponentOptions =
LocationComponentOptions.builder(this@BasicLocationPulsingCircleActivity)
.pulseEnabled(true)
.pulseColor(Color.RED) // Set color of pulse
.foregroundTintColor(Color.BLACK) // Set color of user location
.build()
```
[//]: # (Here is the final results with different color configurations. For the complete content of this demo, please refer to the source code of the [Test App].)
[//]: # ()
[//]: # ()
[//]: # ( )
[//]: # ( {{ openmaptiles_caption() }})
[//]: # ( )
[^1]: A variety of [camera modes] determine how the camera will track the user location.
They provide the right context to your users at the correct time.
[LocationComponent]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.location/-location-component/index.html
[Android Developer Documentation]: https://developer.android.com/training/location/permissions
[onMapReadyCallback]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.maps/-on-map-ready-callback/index.html
[PermissionManager]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.location.permissions/-permissions-manager/index.html
[LocationComponentOptions]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.location/-location-component-options/index.html
[predefined styles]: https://github.com/MapMetrics/mapmetrics-native-sdk/tree/main/src/mbgl/util/tile_server_options.cpp
[LocationComponentActivationOptions]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.location/-location-component-activation-options/index.html
[LocationEngine]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.location.engine/-location-engine/index.html
[Test APP]: https://github.com/MapMetrics/mapmetrics-native-sdk/tree/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/location/BasicLocationPulsingCircleActivity.kt
[camera modes]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.location.modes/-camera-mode/index.html
---
# Using the Snapshotter
https://docs.mapatlas.xyz/overview/sdk/android-native/snapshotter
# Using the Snapshotter
This guide will help you walk through how to use [MapSnapshotter](https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.snapshotter/-map-snapshotter/index.html).
## Map Snapshot with Local Style
[//]: # ({{ activity_source_note("MapSnapshotterLocalStyleActivity.kt") }})
[//]: # (To get started we will show how to use the map snapshotter with a local style.)
[//]: # ()
[//]: # ()
[//]: # ( { width="300" })
[//]: # ( )
Save a style document as `atlas_style.json` in the `res/raw` directory of our app[^1]. You can fetch one from the MapMetrics Atlas gateway — `https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY` — and save the response. First we will read this style:
[^1]: See [App resources overview](https://developer.android.com/guide/topics/resources/providing-resources) for this and other ways you can provide resources to your app.
```kotlin
val styleJson = resources.openRawResource(R.raw.atlas_style).reader().readText()
```
Next, we configure the MapSnapshotter, passing height and width, the style we just read and the camera position:
```kotlin
mapSnapshotter = MapSnapshotter(
applicationContext,
MapSnapshotter.Options(
container.measuredWidth.coerceAtMost(1024),
container.measuredHeight.coerceAtMost(1024)
)
.withStyleBuilder(Style.Builder().fromJson(styleJson))
.withCameraPosition(
CameraPosition.Builder().target(LatLng(LATITUDE, LONGITUDE))
.zoom(ZOOM).build()
)
)
```
Lastly we use the `.start()` method to create the snapshot, and pass callbacks for when the snapshot is ready or for when an error occurs.
```kotlin
mapSnapshotter.start({ snapshot ->
Timber.i("Snapshot ready")
val imageView = findViewById(R.id.snapshot_image) as ImageView
imageView.setImageBitmap(snapshot.bitmap)
}) { error -> Timber.e(error )}
```
## Show a Grid of Snapshots
[//]: # ({{ activity_source_note("MapSnapshotterActivity.kt") }})
In this example, we demonstrate how to use the `MapSnapshotter` to create multiple map snapshots with different styles and camera positions, displaying them in a grid layout.
[//]: # ()
[//]: # ( { width="300" })
[//]: # ( )
First we create a [`GridLayout`](https://developer.android.com/reference/kotlin/android/widget/GridLayout) and a list of `MapSnapshotter` instances. We create a `Style.Builder` with a different style for each cell in the grid. The first entry is a MapMetrics Atlas gateway style — that is what you would use in your own app. The rest are third-party demo styles, included here only so the grid shows visibly different cells; they are not defaults and are not covered by your MapMetrics plan.
```kotlin
val styles = arrayOf(
// Your MapMetrics Atlas style — use this shape in production.
"https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY",
// Third-party demo styles, for contrast in this grid only.
TestStyles.AMERICANA,
TestStyles.OPENFREEMAP_LIBERTY,
TestStyles.AWS_OPEN_DATA_STANDARD_LIGHT,
TestStyles.PROTOMAPS_LIGHT,
TestStyles.PROTOMAPS_DARK,
TestStyles.PROTOMAPS_WHITE,
TestStyles.PROTOMAPS_GRAYSCALE
)
val builder = Style.Builder().fromUri(
styles[(row * grid.rowCount + column) % styles.size]
)
```
Next we create a `MapSnapshotter.Options` object to customize the settings of each snapshot(ter).
```kotlin
val options = MapSnapshotter.Options(
grid.measuredWidth / grid.columnCount,
grid.measuredHeight / grid.rowCount
)
.withPixelRatio(1f)
.withLocalIdeographFontFamily(MapLibreConstants.DEFAULT_FONT)
```
For some rows we randomize the visible region of the snapshot:
```kotlin
if (row % 2 == 0) {
options.withRegion(
LatLngBounds.Builder()
.include(
LatLng(
randomInRange(-80f, 80f).toDouble(),
randomInRange(-160f, 160f).toDouble()
)
)
.include(
LatLng(
randomInRange(-80f, 80f).toDouble(),
randomInRange(-160f, 160f).toDouble()
)
)
.build()
)
}
```
For some columns we randomize the camera position:
```kotlin
if (column % 2 == 0) {
options.withCameraPosition(
CameraPosition.Builder()
.target(
options.region?.center ?: LatLng(
randomInRange(-80f, 80f).toDouble(),
randomInRange(-160f, 160f).toDouble()
)
)
.bearing(randomInRange(0f, 360f).toDouble())
.tilt(randomInRange(0f, 60f).toDouble())
.zoom(randomInRange(0f, 10f).toDouble())
.padding(1.0, 1.0, 1.0, 1.0)
.build()
)
}
```
In the last column of the first row we add two bitmaps. See the next example for more details.
```kotlin
if (row == 0 && column == 2) {
val carBitmap = BitmapUtils.getBitmapFromDrawable(
ResourcesCompat.getDrawable(resources, R.drawable.ic_directions_car_black, theme)
)
// Marker source
val markerCollection = FeatureCollection.fromFeatures(
arrayOf(
Feature.fromGeometry(
Point.fromLngLat(4.91638, 52.35673),
featureProperties("1", "Android")
),
Feature.fromGeometry(
Point.fromLngLat(4.91638, 12.34673),
featureProperties("2", "Car")
)
)
)
val markerSource: Source = GeoJsonSource(MARKER_SOURCE, markerCollection)
// Marker layer
val markerSymbolLayer = SymbolLayer(MARKER_LAYER, MARKER_SOURCE)
.withProperties(
PropertyFactory.iconImage(Expression.get(TITLE_FEATURE_PROPERTY)),
PropertyFactory.iconIgnorePlacement(true),
PropertyFactory.iconAllowOverlap(true),
PropertyFactory.iconSize(
Expression.switchCase(
Expression.toBool(Expression.get(SELECTED_FEATURE_PROPERTY)),
Expression.literal(1.5f),
Expression.literal(1.0f)
)
),
PropertyFactory.iconAnchor(Property.ICON_ANCHOR_BOTTOM),
PropertyFactory.iconColor(Color.BLUE)
)
builder.withImage("Car", Objects.requireNonNull(carBitmap!!), false)
.withSources(markerSource)
.withLayers(markerSymbolLayer)
options
.withRegion(null)
.withCameraPosition(
CameraPosition.Builder()
.target(
LatLng(5.537109374999999, 52.07950600379697)
)
.zoom(1.0)
.padding(1.0, 1.0, 1.0, 1.0)
.build()
)
}
```
## Map Snapshot with Bitmap Overlay
[//]: # ({{ activity_source_note("MapSnapshotterBitMapOverlayActivity.kt") }})
This example adds a bitmap on top of the snapshot. It also demonstrates how you can add a click listener to a snapshot.
[//]: # ()
[//]: # ()
[//]: # ( { width="300" })
[//]: # ( )
```kotlin title="MapSnapshotterBitMapOverlayActivity.kt"
/**
* Test activity showing how to use a the [MapSnapshotter] and overlay
* [android.graphics.Bitmap]s on top.
*/
class MapSnapshotterBitMapOverlayActivity :
AppCompatActivity(),
MapSnapshotter.SnapshotReadyCallback {
private var mapSnapshotter: MapSnapshotter? = null
@get:VisibleForTesting
var mapSnapshot: MapSnapshot? = null
private set
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map_snapshotter_marker)
val container = findViewById(R.id.container)
container.viewTreeObserver
.addOnGlobalLayoutListener(object : OnGlobalLayoutListener {
override fun onGlobalLayout() {
container.viewTreeObserver.removeOnGlobalLayoutListener(this)
Timber.i("Starting snapshot")
mapSnapshotter = MapSnapshotter(
applicationContext,
MapSnapshotter.Options(
Math.min(container.measuredWidth, 1024),
Math.min(container.measuredHeight, 1024)
)
.withStyleBuilder(
Style.Builder().fromUri(TestStyles.AMERICANA)
)
.withCameraPosition(
CameraPosition.Builder().target(LatLng(52.090737, 5.121420))
.zoom(15.0).build()
)
)
mapSnapshotter!!.start(this@MapSnapshotterBitMapOverlayActivity)
}
})
}
override fun onStop() {
super.onStop()
mapSnapshotter!!.cancel()
}
@SuppressLint("ClickableViewAccessibility")
override fun onSnapshotReady(snapshot: MapSnapshot) {
mapSnapshot = snapshot
Timber.i("Snapshot ready")
val imageView = findViewById(R.id.snapshot_image) as ImageView
val image = addMarker(snapshot)
imageView.setImageBitmap(image)
imageView.setOnTouchListener { v: View?, event: MotionEvent ->
if (event.action == MotionEvent.ACTION_DOWN) {
val latLng = snapshot.latLngForPixel(PointF(event.x, event.y))
Timber.e("Clicked LatLng is %s", latLng)
return@setOnTouchListener true
}
false
}
}
private fun addMarker(snapshot: MapSnapshot): Bitmap {
val canvas = Canvas(snapshot.bitmap)
val marker =
BitmapFactory.decodeResource(resources, R.drawable.maplibre_marker_icon_default, null)
// Dom toren
val markerLocation = snapshot.pixelForLatLng(LatLng(52.090649433011315, 5.121310651302338))
canvas.drawBitmap(
marker, /* Subtract half of the width so we center the bitmap correctly */
markerLocation.x - marker.width / 2, /* Subtract half of the height so we align the bitmap bottom correctly */
markerLocation.y - marker.height / 2,
null
)
return snapshot.bitmap
}
}
```
## Map Snapshotter with Heatmap Layer
[//]: # ({{ activity_source_note("MapSnapshotterHeatMapActivity.kt") }})
In this example, we demonstrate how to use the `MapSnapshotter` to create a snapshot of a map that includes a heatmap layer. The heatmap represents earthquake data loaded from a GeoJSON source.
[//]: # ()
[//]: # ()
[//]: # ( { width="300" })
[//]: # ( )
First, we create the `MapSnapshotterHeatMapActivity` class, which extends `AppCompatActivity` and implements `MapSnapshotter.SnapshotReadyCallback` to receive the snapshot once it's ready.
```kotlin
class MapSnapshotterHeatMapActivity : AppCompatActivity(), MapSnapshotter.SnapshotReadyCallback
```
In the `onCreate` method, we set up the layout and initialize the `MapSnapshotter` once the layout is ready.
```kotlin
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map_snapshotter_marker)
val container = findViewById(R.id.container)
container.viewTreeObserver
.addOnGlobalLayoutListener(object : OnGlobalLayoutListener {
override fun onGlobalLayout() {
container.viewTreeObserver.removeOnGlobalLayoutListener(this)
Timber.i("Starting snapshot")
val builder = Style.Builder().fromUri(TestStyles.AMERICANA)
.withSource(earthquakeSource!!)
.withLayerAbove(heatmapLayer, "water")
mapSnapshotter = MapSnapshotter(
applicationContext,
MapSnapshotter.Options(container.measuredWidth, container.measuredHeight)
.withStyleBuilder(builder)
.withCameraPosition(
CameraPosition.Builder()
.target(LatLng(15.0, (-94).toDouble()))
.zoom(5.0)
.padding(1.0, 1.0, 1.0, 1.0)
.build()
)
)
mapSnapshotter!!.start(this@MapSnapshotterHeatMapActivity)
}
})
}
```
Here, we wait for the layout to be laid out using an `OnGlobalLayoutListener` before initializing the `MapSnapshotter`. We create a `Style.Builder` with a base style (`TestStyles.AMERICANA`), add the earthquake data source, and add the heatmap layer above the "water" layer.
The `heatmapLayer` property defines the `HeatmapLayer` used to visualize the earthquake data.
```kotlin
private val heatmapLayer: HeatmapLayer
get() {
val layer = HeatmapLayer(HEATMAP_LAYER_ID, EARTHQUAKE_SOURCE_ID)
layer.maxZoom = 9f
layer.sourceLayer = HEATMAP_LAYER_SOURCE
layer.setProperties(
PropertyFactory.heatmapColor(
Expression.interpolate(
Expression.linear(), Expression.heatmapDensity(),
Expression.literal(0), Expression.rgba(33, 102, 172, 0),
Expression.literal(0.2), Expression.rgb(103, 169, 207),
Expression.literal(0.4), Expression.rgb(209, 229, 240),
Expression.literal(0.6), Expression.rgb(253, 219, 199),
Expression.literal(0.8), Expression.rgb(239, 138, 98),
Expression.literal(1), Expression.rgb(178, 24, 43)
)
),
PropertyFactory.heatmapWeight(
Expression.interpolate(
Expression.linear(),
Expression.get("mag"),
Expression.stop(0, 0),
Expression.stop(6, 1)
)
),
PropertyFactory.heatmapIntensity(
Expression.interpolate(
Expression.linear(),
Expression.zoom(),
Expression.stop(0, 1),
Expression.stop(9, 3)
)
),
PropertyFactory.heatmapRadius(
Expression.interpolate(
Expression.linear(),
Expression.zoom(),
Expression.stop(0, 2),
Expression.stop(9, 20)
)
),
PropertyFactory.heatmapOpacity(
Expression.interpolate(
Expression.linear(),
Expression.zoom(),
Expression.stop(7, 1),
Expression.stop(9, 0)
)
)
)
return layer
}
```
This code sets up the heatmap layer's properties, such as color ramp, weight, intensity, radius, and opacity, using expressions that interpolate based on data properties and zoom level.
We also define the `earthquakeSource`, which loads data from a GeoJSON file containing earthquake information.
```kotlin
private val earthquakeSource: Source?
get() {
var source: Source? = null
try {
source = GeoJsonSource(EARTHQUAKE_SOURCE_ID, URI(EARTHQUAKE_SOURCE_URL))
} catch (uriSyntaxException: URISyntaxException) {
Timber.e(uriSyntaxException, "That's not a valid URL.")
}
return source
}
```
When the snapshot is ready, the `onSnapshotReady` callback is invoked, where we set the snapshot bitmap to an `ImageView` to display it.
```kotlin
@SuppressLint("ClickableViewAccessibility")
override fun onSnapshotReady(snapshot: MapSnapshot) {
Timber.i("Snapshot ready")
val imageView = findViewById(R.id.snapshot_image)
imageView.setImageBitmap(snapshot.bitmap)
}
```
Finally, we ensure to cancel the snapshotter in the `onStop` method to free up resources.
```kotlin
override fun onStop() {
super.onStop()
mapSnapshotter?.cancel()
}
```
## Map Snapshotter with Expression
[//]: # ({{ activity_source_note("MapSnapshotterWithinExpression.kt") }})
In this example the map on top is a live while the map on the bottom is a snapshot that is updated as you pan the map. We style of the snapshot is modified: using a [within](https://maplibre.org/maplibre-style-spec/expressions/#within) expression only POIs within a certain distance to a line is shown. A highlight for this area is added to the map as are various points.
[//]: # ()
[//]: # ()
[//]: # ( { width="300" })
[//]: # ( )
```kotlin title="MapSnapshotterWithinExpression.kt"
/**
* An Activity that showcases the use of MapSnapshotter with 'within' expression
*/
class MapSnapshotterWithinExpression : AppCompatActivity() {
private lateinit var binding: ActivityMapsnapshotterWithinExpressionBinding
private lateinit var maplibreMap: MapLibreMap
private lateinit var snapshotter: MapSnapshotter
private var snapshotInProgress = false
private val cameraListener = object : MapView.OnCameraDidChangeListener {
override fun onCameraDidChange(animated: Boolean) {
if (!snapshotInProgress) {
snapshotInProgress = true
snapshotter.setCameraPosition(maplibreMap.cameraPosition)
snapshotter.start(object : MapSnapshotter.SnapshotReadyCallback {
override fun onSnapshotReady(snapshot: MapSnapshot) {
binding.imageView.setImageBitmap(snapshot.bitmap)
snapshotInProgress = false
}
})
}
}
}
private val snapshotterObserver = object : MapSnapshotter.Observer {
override fun onStyleImageMissing(imageName: String) {
}
override fun onDidFinishLoadingStyle() {
// Show only POI labels inside geometry using within expression
(snapshotter.getLayer("poi-label") as SymbolLayer).setFilter(
within(
bufferLineStringGeometry()
)
)
// Hide other types of labels to highlight POI labels
(snapshotter.getLayer("road-label") as SymbolLayer).setProperties(visibility(NONE))
(snapshotter.getLayer("transit-label") as SymbolLayer).setProperties(visibility(NONE))
(snapshotter.getLayer("road-number-shield") as SymbolLayer).setProperties(visibility(NONE))
}
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
binding = ActivityMapsnapshotterWithinExpressionBinding.inflate(layoutInflater)
setContentView(binding.root)
binding.mapView.onCreate(savedInstanceState)
binding.mapView.getMapAsync { map ->
maplibreMap = map
// Setup camera position above Georgetown
maplibreMap.cameraPosition = CameraPosition.Builder().target(LatLng(38.90628988399711, -77.06574689337494)).zoom(15.5).build()
// Wait for the map to become idle before manipulating the style and camera of the map
binding.mapView.addOnDidBecomeIdleListener(object : MapView.OnDidBecomeIdleListener {
override fun onDidBecomeIdle() {
maplibreMap.easeCamera(
CameraUpdateFactory.newCameraPosition(
CameraPosition.Builder().zoom(16.0).target(LatLng(38.905156245642814, -77.06535338052844)).bearing(80.68015859462369).tilt(55.0).build()
),
1000
)
binding.mapView.removeOnDidBecomeIdleListener(this)
}
})
// Load the base style and add lines and circles
setupStyle()
}
}
private fun setupStyle() {
// Assume the route is represented by an array of coordinates.
val coordinates = listOf(
Point.fromLngLat(-77.06866264343262, 38.90506061276737),
Point.fromLngLat(-77.06283688545227, 38.905194197410545),
Point.fromLngLat(-77.06285834312439, 38.906429843444094),
Point.fromLngLat(-77.0630407333374, 38.90680554236621)
)
// Setup style with additional layers,
// using streets as a base style
maplibreMap.setStyle(
Style.Builder().fromUri(getPredefinedStyleWithFallback("Streets"))
) {
binding.mapView.addOnCameraDidChangeListener(cameraListener)
}
val options = MapSnapshotter.Options(binding.imageView.measuredWidth / 2, binding.imageView.measuredHeight / 2)
.withCameraPosition(maplibreMap.cameraPosition)
.withPixelRatio(2.0f).withStyleBuilder(
Style.Builder().fromUri(getPredefinedStyleWithFallback("Streets")).withSources(
GeoJsonSource(
POINT_ID,
LineString.fromLngLats(coordinates)
),
GeoJsonSource(
FILL_ID,
FeatureCollection.fromFeature(
Feature.fromGeometry(bufferLineStringGeometry())
),
GeoJsonOptions().withBuffer(0).withTolerance(0.0f)
)
).withLayerBelow(
LineLayer(LINE_ID, POINT_ID).withProperties(
lineWidth(7.5f),
lineColor(Color.LTGRAY)
),
"poi-label"
).withLayerBelow(
CircleLayer(POINT_ID, POINT_ID).withProperties(
circleRadius(7.5f),
circleColor(Color.DKGRAY),
circleOpacity(0.75f)
),
"poi-label"
).withLayerBelow(
FillLayer(FILL_ID, FILL_ID).withProperties(
fillOpacity(0.12f),
fillColor(Color.YELLOW)
),
LINE_ID
)
)
snapshotter = MapSnapshotter(this, options)
snapshotter.setObserver(snapshotterObserver)
}
override fun onStart() {
super.onStart()
binding.mapView.onStart()
}
override fun onResume() {
super.onResume()
binding.mapView.onResume()
}
override fun onPause() {
super.onPause()
binding.mapView.onPause()
}
override fun onStop() {
super.onStop()
binding.mapView.onStop()
}
override fun onLowMemory() {
super.onLowMemory()
binding.mapView.onLowMemory()
}
override fun onDestroy() {
super.onDestroy()
binding.mapView.onDestroy()
}
override fun onSaveInstanceState(outState: Bundle, outPersistentState: PersistableBundle) {
super.onSaveInstanceState(outState, outPersistentState)
binding.mapView.onSaveInstanceState(outState)
}
private fun bufferLineStringGeometry(): Polygon {
// Static buffer geometry; could be computed at runtime with a Turf-style buffer helper.
return FeatureCollection.fromJson(
"""
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-77.06867337226866,
38.90467655551809
],
[
-77.06233263015747,
38.90479344272695
],
[
-77.06234335899353,
38.906463238984344
],
[
-77.06290125846863,
38.907206285691615
],
[
-77.06364154815674,
38.90684728656818
],
[
-77.06326603889465,
38.90637140121084
],
[
-77.06321239471436,
38.905561553883246
],
[
-77.0691454410553,
38.905436318935635
],
[
-77.06912398338318,
38.90466820642439
],
[
-77.06867337226866,
38.90467655551809
]
]
]
}
}
]
}
""".trimIndent()
).features()!![0].geometry() as Polygon
}
companion object {
const val POINT_ID = "point"
const val FILL_ID = "fill"
const val LINE_ID = "line"
}
}
```
---
# Animated Image Source
https://docs.mapatlas.xyz/overview/sdk/android-native/styling/animated-image-source
# Animated Image Source
[//]: # ({{ activity_source_note("AnimatedImageSourceActivity.kt") }})
In this example we will see how we can animate an image source. This is the MapMetrics Native equivalent of [this MapMetrics GL JS example](https://maplibre.org/maplibre-gl-js/docs/examples/animate-images/).
[//]: # ()
[//]: # ( )
[//]: # ( )
[//]: # ( {{ openmaptiles_caption() }})
[//]: # ( )
We set up an [image source](https://maplibre.org/maplibre-style-spec/sources/#image) in a particular quad. Then we kick of a runnable that periodically updates the image source.
```kotlin title="Creating the image source"
val quad = LatLngQuad(
LatLng(46.437, -80.425),
LatLng(46.437, -71.516),
LatLng(37.936, -71.516),
LatLng(37.936, -80.425)
)
val imageSource = ImageSource(ID_IMAGE_SOURCE, quad, R.drawable.southeast_radar_0)
val layer = RasterLayer(ID_IMAGE_LAYER, ID_IMAGE_SOURCE)
map.setStyle(
Style.Builder()
.fromUri(TestStyles.AMERICANA)
.withSource(imageSource)
.withLayer(layer)
) { style: Style? ->
runnable = RefreshImageRunnable(imageSource, handler)
runnable?.let {
handler.postDelayed(it, 100)
}
}
```
```kotlin title="Updating the image source"
imageSource.setImage(drawables[drawableIndex++]!!)
if (drawableIndex > 3) {
drawableIndex = 0
}
handler.postDelayed(this, 1000)
```
---
# Animated SymbolLayer
https://docs.mapatlas.xyz/overview/sdk/android-native/styling/animated-symbol-layer
# Animated SymbolLayer
[//]: # ({{ activity_source_note("AnimatedSymbolLayerActivity.kt") }})
[//]: # ()
[//]: # ( )
[//]: # ( )
[//]: # ( {{ openmaptiles_caption() }})
[//]: # ( )
Notice that there are (red) cars randomly moving around, and a (yellow) taxi that is always heading to the passenger (indicated by the M symbol), which upon arrival hops to a different location again. We will focus on the passanger and the taxi, because the cars randomly moving around follow a similar pattern.
In a real application you would of course retrieve the locations from some sort of external API, but for the purposes of this example a random latitude longtitude pair within bounds of the currently visible screen will do.
```kotlin title="Getter method to get a random location on the screen"
private val latLngInBounds: LatLng
get() {
val bounds = maplibreMap.projection.visibleRegion.latLngBounds
val generator = Random()
val randomLat = bounds.latitudeSouth + generator.nextDouble() * (bounds.latitudeNorth - bounds.latitudeSouth)
val randomLon = bounds.longitudeWest + generator.nextDouble() * (bounds.longitudeEast - bounds.longitudeWest)
return LatLng(randomLat, randomLon)
}
```
```kotlin title="Adding a passenger at a random location (on screen)"
private fun addPassenger(style: Style) {
passenger = latLngInBounds
val featureCollection = FeatureCollection.fromFeatures(
arrayOf(
Feature.fromGeometry(
Point.fromLngLat(
passenger!!.longitude,
passenger!!.latitude
)
)
)
)
style.addImage(
PASSENGER,
ResourcesCompat.getDrawable(resources, R.drawable.icon_burned, theme)!!
)
val geoJsonSource = GeoJsonSource(PASSENGER_SOURCE, featureCollection)
style.addSource(geoJsonSource)
val symbolLayer = SymbolLayer(PASSENGER_LAYER, PASSENGER_SOURCE)
symbolLayer.withProperties(
PropertyFactory.iconImage(PASSENGER),
PropertyFactory.iconIgnorePlacement(true),
PropertyFactory.iconAllowOverlap(true)
)
style.addLayerBelow(symbolLayer, RANDOM_CAR_LAYER)
}
```
Adding the taxi on screen is done very similarly.
```kotlin title="Adding the taxi with bearing"
private fun addTaxi(style: Style) {
val latLng = latLngInBounds
val properties = JsonObject()
properties.addProperty(PROPERTY_BEARING, Car.getBearing(latLng, passenger))
val feature = Feature.fromGeometry(
Point.fromLngLat(
latLng.longitude,
latLng.latitude
),
properties
)
val featureCollection = FeatureCollection.fromFeatures(arrayOf(feature))
taxi = Car(feature, passenger, duration)
style.addImage(
TAXI,
(ResourcesCompat.getDrawable(resources, R.drawable.ic_taxi_top, theme) as BitmapDrawable).bitmap
)
taxiSource = GeoJsonSource(TAXI_SOURCE, featureCollection)
style.addSource(taxiSource!!)
val symbolLayer = SymbolLayer(TAXI_LAYER, TAXI_SOURCE)
symbolLayer.withProperties(
PropertyFactory.iconImage(TAXI),
PropertyFactory.iconRotate(Expression.get(PROPERTY_BEARING)),
PropertyFactory.iconAllowOverlap(true),
PropertyFactory.iconIgnorePlacement(true)
)
style.addLayer(symbolLayer)
}
```
For animating the taxi we use a [`ValueAnimator`](https://developer.android.com/reference/android/animation/ValueAnimator).
```kotlin title="Animate the taxi driving towards the passenger"
private fun animateTaxi(style: Style) {
val valueAnimator = ValueAnimator.ofObject(LatLngEvaluator(), taxi!!.current, taxi!!.next)
valueAnimator.addUpdateListener(object : AnimatorUpdateListener {
private var latLng: LatLng? = null
override fun onAnimationUpdate(animation: ValueAnimator) {
latLng = animation.animatedValue as LatLng
taxi!!.current = latLng
updateTaxiSource()
}
})
valueAnimator.addListener(object : AnimatorListenerAdapter() {
override fun onAnimationEnd(animation: Animator) {
super.onAnimationEnd(animation)
updatePassenger(style)
animateTaxi(style)
}
})
valueAnimator.addListener(object : AnimatorListenerAdapter() {
override fun onAnimationStart(animation: Animator) {
super.onAnimationStart(animation)
taxi!!.feature.properties()!!
.addProperty("bearing", Car.getBearing(taxi!!.current, taxi!!.next))
}
})
valueAnimator.duration = (7 * taxi!!.current!!.distanceTo(taxi!!.next!!)).toLong()
valueAnimator.interpolator = AccelerateDecelerateInterpolator()
valueAnimator.start()
animators.add(valueAnimator)
}
```
---
# Building Layer
https://docs.mapatlas.xyz/overview/sdk/android-native/styling/building-layer
# Building Layer
[//]: # ({{ activity_source_note("BuildingFillExtrusionActivity.kt") }})
In this example will show how to add a [Fill Extrusion](https://maplibre.org/maplibre-style-spec/layers/#fill-extrusion) layer to a style.
[//]: # ()
[//]: # ( )
[//]: # ( )
[//]: # ( {{ openmaptiles_caption() }})
[//]: # ( )
We use the [OpenFreeMap Bright](https://openfreemap.org/quick_start/) style which, unlike OpenFreeMap Libery, does not have a fill extrusion layer by default. However, if you inspect this style with [Maputnik](https://maplibre.org/maputnik) you will find that the multipolygons in the `building` layer (of the `openfreemap` source) each have `render_min_height` and `render_height` properties.
```kotlin title="Setting up the fill extrusion layer"
val fillExtrusionLayer = FillExtrusionLayer("building-3d", "openmaptiles")
fillExtrusionLayer.sourceLayer = "building"
fillExtrusionLayer.setFilter(
Expression.all(
Expression.has("render_height"),
Expression.has("render_min_height")
)
)
fillExtrusionLayer.minZoom = 15f
fillExtrusionLayer.setProperties(
PropertyFactory.fillExtrusionColor(Color.LTGRAY),
PropertyFactory.fillExtrusionHeight(Expression.get("render_height")),
PropertyFactory.fillExtrusionBase(Expression.get("render_min_height")),
PropertyFactory.fillExtrusionOpacity(0.9f)
)
style.addLayer(fillExtrusionLayer)
```
```kotlin title="Changing the light direction"
isInitPosition = !isInitPosition
if (isInitPosition) {
light!!.position = Position(1.5f, 90f, 80f)
} else {
light!!.position = Position(1.15f, 210f, 30f)
}
```
```kotlin title="Changing the light color"
isRedColor = !isRedColor
light!!.setColor(ColorUtils.colorToRgbaString(if (isRedColor) Color.RED else Color.BLUE))
```
---
# Circle Layer (with Clustering)
https://docs.mapatlas.xyz/overview/sdk/android-native/styling/circle-layer
# Circle Layer (with Clustering)
[//]: # ({{ activity_source_note("CircleLayerActivity.kt") }})
In this example we will add a circle layer for a GeoJSON source. We also show how you can use the [cluster](https://maplibre.org/maplibre-style-spec/sources/#cluster) property of a GeoJSON source.
[//]: # ()
[//]: # ( )
[//]: # ( )
[//]: # ( )
Create a `GeoJsonSource` instance, pass a unique identifier for the source and the URL where the GeoJSON is available. Next add the source to the style.
```kotlin title="Setting up the GeoJSON source"
try {
source = GeoJsonSource(SOURCE_ID, URI(URL_BUS_ROUTES))
} catch (exception: URISyntaxException) {
Timber.e(exception, "That's not an url... ")
}
style.addSource(source!!)
```
Now you can create a `CircleLayer`, pass it a unique identifier for the layer and the source identifier of the GeoJSON source just created. You can use a `PropertyFactory` to pass [circle layer properties](https://maplibre.org/maplibre-style-spec/layers/#circle). Lastly add the layer to your style.
```kotlin title="Create circle layer a small orange circle for each bus stop"
layer = CircleLayer(LAYER_ID, SOURCE_ID)
layer!!.setProperties(
PropertyFactory.circleColor(Color.parseColor("#FF9800")),
PropertyFactory.circleRadius(2.0f)
)
style.addLayer(layer!!)
```
## Clustering
Next we will show you how you can use clustering. Create a `GeoJsonSource` as before, but with some additional options to enable clustering.
```kotlin title="Setting up the clustered GeoJSON source"
style.addSource(
GeoJsonSource(
SOURCE_ID_CLUSTER,
URI(URL_BUS_ROUTES),
GeoJsonOptions()
.withCluster(true)
.withClusterMaxZoom(14)
.withClusterRadius(50)
)
)
```
When enabling clustering some [special attributes](https://maplibre.org/maplibre-style-spec/sources/#cluster) will be available to the points in the newly created layer. One is `cluster`, which is true if the point indicates a cluster. We want to show a bus stop for points that are **not** clustered.
```kotlin title="Add a symbol layers for points that are not clustered"
val unclustered = SymbolLayer("unclustered-points", SOURCE_ID_CLUSTER)
unclustered.setProperties(
PropertyFactory.iconImage("bus-icon"),
)
unclustered.setFilter(
Expression.neq(Expression.get("cluster"), true)
)
style.addLayer(unclustered)
```
Next we define which point amounts correspond to which colors. More than 150 points will get a red circle, clusters with 21-150 points will be green and clusters with 20 or less points will be green.
```kotlin title="Define different colors for different point amounts"
val layers = arrayOf(
150 to ResourcesCompat.getColor(
resources,
R.color.redAccent,
theme
),
20 to ResourcesCompat.getColor(resources, R.color.greenAccent, theme),
0 to ResourcesCompat.getColor(
resources,
R.color.blueAccent,
theme
)
)
```
Lastly we iterate over the array of `Pair`s to create a `CircleLayer` for each element.
```kotlin title="Add different circle layers for clusters of different point amounts"
for (i in layers.indices) {
// Add some nice circles
val circles = CircleLayer("cluster-$i", SOURCE_ID_CLUSTER)
circles.setProperties(
PropertyFactory.circleColor(layers[i].second),
PropertyFactory.circleRadius(18f)
)
val pointCount = Expression.toNumber(Expression.get("point_count"))
circles.setFilter(
if (i == 0) {
Expression.all(
Expression.has("point_count"),
Expression.gte(
pointCount,
Expression.literal(layers[i].first)
)
)
} else {
Expression.all(
Expression.has("point_count"),
Expression.gt(
pointCount,
Expression.literal(layers[i].first)
),
Expression.lt(
pointCount,
Expression.literal(layers[i - 1].first)
)
)
}
)
style.addLayer(circles)
}
```
---
# Add Custom Sprite
https://docs.mapatlas.xyz/overview/sdk/android-native/styling/custom-sprite
# Add Custom Sprite
[//]: # ({{ activity_source_note("CustomSpriteActivity.kt") }})
This example showcases adding a sprite image and using it in a Symbol Layer.
```kotlin
// Add an icon to reference later
style.addImage(
CUSTOM_ICON,
BitmapFactory.decodeResource(
resources,
R.drawable.ic_car_top
)
)
// Add a source with a geojson point
point = Point.fromLngLat(13.400972, 52.519003)
source = GeoJsonSource(
"point",
FeatureCollection.fromFeatures(arrayOf(Feature.fromGeometry(point)))
)
maplibreMap.style!!.addSource(source!!)
// Add a symbol layer that references that point source
layer = SymbolLayer("layer", "point")
layer.setProperties( // Set the id of the sprite to use
PropertyFactory.iconImage(CUSTOM_ICON),
PropertyFactory.iconAllowOverlap(true),
PropertyFactory.iconIgnorePlacement(true)
)
// lets add a circle below labels!
maplibreMap.style!!.addLayerBelow(layer, "water-intermittent")
fab.setImageResource(R.drawable.ic_directions_car_black)
```
---
# Custom Map Styling
https://docs.mapatlas.xyz/overview/sdk/android-native/styling/custom-styling
# Custom Map Styling
This tutorial shows how to customize the appearance of your MapMetrics Android map — switching styles, modifying layers at runtime, and applying light/dark themes.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Switch Between Map Styles
Let users choose a map style at runtime:
```kotlin
import android.os.Bundle
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
class CustomStylingActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
private val styles = mapOf(
"Streets" to "https://gateway.mapmetrics-atlas.net/styles/STREETS_STYLE_ID?token=YOUR_API_KEY",
"Dark" to "https://gateway.mapmetrics-atlas.net/styles/DARK_STYLE_ID?token=YOUR_API_KEY",
"Satellite" to "https://gateway.mapmetrics-atlas.net/styles/SATELLITE_STYLE_ID?token=YOUR_API_KEY",
)
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_custom_styling)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
// Set initial style
setMapStyle("Streets")
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8566, 2.3522))
.zoom(12.0)
.build()
// Style switch buttons
findViewById(R.id.btnStreets).setOnClickListener { setMapStyle("Streets") }
findViewById(R.id.btnDark).setOnClickListener { setMapStyle("Dark") }
findViewById(R.id.btnSatellite).setOnClickListener { setMapStyle("Satellite") }
}
}
private fun setMapStyle(name: String) {
val url = styles[name] ?: return
// Save current camera position
val currentCamera = map.cameraPosition
map.setStyle(Style.Builder().fromUri(url)) { style ->
// Restore camera after style loads
map.cameraPosition = currentCamera
}
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Modify Existing Style Layers
Change layer properties of the current style at runtime:
```kotlin
private fun modifyStyleLayers(style: Style) {
// Change water color
val waterLayer = style.getLayerAs("water")
waterLayer?.setProperties(
org.maplibre.android.style.layers.PropertyFactory.fillColor(
android.graphics.Color.parseColor("#1A73E8")
)
)
// Change building color
val buildingLayer = style.getLayerAs("building")
buildingLayer?.setProperties(
org.maplibre.android.style.layers.PropertyFactory.fillColor(
android.graphics.Color.parseColor("#E8E0D8")
)
)
// Hide POI labels
val poiLabels = style.getLayer("poi-label")
poiLabels?.setProperties(
org.maplibre.android.style.layers.PropertyFactory.visibility(
org.maplibre.android.style.layers.Property.NONE
)
)
}
```
## Show/Hide Layer Categories
Toggle entire categories of map features:
```kotlin
import android.widget.ToggleButton
import org.maplibre.android.style.layers.Property
import org.maplibre.android.style.layers.PropertyFactory.visibility
private fun setupLayerToggles(style: Style) {
// Toggle roads
findViewById(R.id.btnRoads).setOnCheckedChangeListener { _, show ->
toggleLayersByPrefix(style, "road", show)
}
// Toggle buildings
findViewById(R.id.btnBuildings).setOnCheckedChangeListener { _, show ->
toggleLayersByPrefix(style, "building", show)
}
// Toggle labels
findViewById(R.id.btnLabels).setOnCheckedChangeListener { _, show ->
toggleLayersByPrefix(style, "label", show)
toggleLayersByPrefix(style, "place", show)
}
}
private fun toggleLayersByPrefix(style: Style, prefix: String, visible: Boolean) {
for (layer in style.layers) {
if (layer.id.contains(prefix, ignoreCase = true)) {
layer.setProperties(
visibility(if (visible) Property.VISIBLE else Property.NONE)
)
}
}
}
```
## Load Style from JSON String
Load a custom style from a local JSON string or asset:
```kotlin
// From assets file
private fun loadLocalStyle() {
val json = assets.open("styles/custom-style.json")
.bufferedReader()
.readText()
map.setStyle(Style.Builder().fromJson(json)) { style ->
// Style loaded from local JSON
}
}
```
## List All Layers in Current Style
Useful for debugging and discovering layer IDs:
```kotlin
private fun listLayers(style: Style) {
for (layer in style.layers) {
android.util.Log.d("MapStyle", "Layer: ${layer.id} (${layer.javaClass.simpleName})")
}
}
```
## Next Steps
- [Data-Driven Styling](./data-driven-style) — Style by data properties
- [Building Layer](./building-layer) — 3D building extrusions
- [Custom Sprite](./custom-sprite) — Custom icon images
---
**Tip**: When switching styles, the camera position resets to the new style's default. Always save `map.cameraPosition` before calling `setStyle()` and restore it in the callback, as shown above.
---
# Data Driven Style
https://docs.mapatlas.xyz/overview/sdk/android-native/styling/data-driven-style
# Data Driven Style
[//]: # ({{ activity_source_note("DataDrivenStyleActivity.kt") }})
In this example we will look at various types of data-driven styling.
The examples with 'Source' in the title apply data-driven styling the [parks of Amsterdam](https://github.com/maplibre/maplibre-native/blob/main/platform/android/MapLibreAndroidTestApp/src/main/res/raw/amsterdam.geojson). Those examples often are based on the somewhat arbitrary `stroke-width` property part of the GeoJSON features. These examples are therefore most interesting to learn about the Kotlin API that can be used for data-driven styling.
Refer to the [MapMetrics Style Spec](https://maplibre.org/maplibre-style-spec/) for more information about [expressions](https://maplibre.org/maplibre-style-spec/expressions/) such as [`interpolate`](https://maplibre.org/maplibre-style-spec/expressions/#interpolate) and [`step`](https://maplibre.org/maplibre-style-spec/expressions/#step).
## Exponential Zoom Function
```kotlin
layer.setProperties(
PropertyFactory.fillColor(
Expression.interpolate(
Expression.exponential(0.5f),
Expression.zoom(),
Expression.stop(1, Expression.color(Color.RED)),
Expression.stop(5, Expression.color(Color.BLUE)),
Expression.stop(10, Expression.color(Color.GREEN))
)
)
)
```
[//]: # ()
[//]: # ( )
[//]: # ( )
[//]: # ( )
## Interval Zoom Function
```kotlin
layer.setProperties(
PropertyFactory.fillColor(
Expression.step(
Expression.zoom(),
Expression.rgba(0.0f, 255.0f, 255.0f, 1.0f),
Expression.stop(1, Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f)),
Expression.stop(5, Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f)),
Expression.stop(10, Expression.rgba(0.0f, 255.0f, 0.0f, 1.0f))
)
)
)
```
[//]: # ()
[//]: # ( )
[//]: # ( )
[//]: # ( )
```json title="Equivalent JSON"
["step",["zoom"],["rgba",0.0,255.0,255.0,1.0],1.0,["rgba",255.0,0.0,0.0,1.0],5.0,["rgba",0.0,0.0,255.0,1.0],10.0,["rgba",0.0,255.0,0.0,1.0]]
```
## Exponential Source Function
```kotlin
val layer = maplibreMap.style!!.getLayerAs(AMSTERDAM_PARKS_LAYER)!!
layer.setProperties(
PropertyFactory.fillColor(
Expression.interpolate(
Expression.exponential(0.5f),
Expression.get("stroke-width"),
Expression.stop(1f, Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f)),
Expression.stop(5f, Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f)),
Expression.stop(10f, Expression.rgba(0.0f, 255.0f, 0.0f, 1.0f))
)
)
)
```
## Categorical Source Function
```kotlin
val layer = maplibreMap.style!!.getLayerAs(AMSTERDAM_PARKS_LAYER)!!
layer.setProperties(
PropertyFactory.fillColor(
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.literal("Jordaan"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.literal("Prinseneiland"),
Expression.rgba(0.0f, 255.0f, 0.0f, 1.0f),
Expression.rgba(0.0f, 255.0f, 255.0f, 1.0f)
)
)
)
```
## Identity Source Function
```kotlin
val layer = maplibreMap.style!!.getLayerAs(AMSTERDAM_PARKS_LAYER)!!
layer.setProperties(
PropertyFactory.fillOpacity(
Expression.get("fill-opacity")
)
)
```
## Interval Source Function
```kotlin
val layer = maplibreMap.style!!.getLayerAs(AMSTERDAM_PARKS_LAYER)!!
layer.setProperties(
PropertyFactory.fillColor(
Expression.step(
Expression.get("stroke-width"),
Expression.rgba(0.0f, 255.0f, 255.0f, 1.0f),
Expression.stop(1f, Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f)),
Expression.stop(2f, Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f)),
Expression.stop(3f, Expression.rgba(0.0f, 255.0f, 0.0f, 1.0f))
)
)
)
```
## Composite Exponential Function
```kotlin
val layer = maplibreMap.style!!.getLayerAs(AMSTERDAM_PARKS_LAYER)!!
layer.setProperties(
PropertyFactory.fillColor(
Expression.interpolate(
Expression.exponential(1f),
Expression.zoom(),
Expression.stop(
12,
Expression.step(
Expression.get("stroke-width"),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f),
Expression.stop(1f, Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f)),
Expression.stop(2f, Expression.rgba(0.0f, 0.0f, 0.0f, 1.0f)),
Expression.stop(3f, Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f))
)
),
Expression.stop(
15,
Expression.step(
Expression.get("stroke-width"),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f),
Expression.stop(1f, Expression.rgba(255.0f, 255.0f, 0.0f, 1.0f)),
Expression.stop(2f, Expression.rgba(211.0f, 211.0f, 211.0f, 1.0f)),
Expression.stop(3f, Expression.rgba(0.0f, 255.0f, 255.0f, 1.0f))
)
),
Expression.stop(
18,
Expression.step(
Expression.get("stroke-width"),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f),
Expression.stop(1f, Expression.rgba(0.0f, 0.0f, 0.0f, 1.0f)),
Expression.stop(2f, Expression.rgba(128.0f, 128.0f, 128.0f, 1.0f)),
Expression.stop(3f, Expression.rgba(0.0f, 255.0f, 0.0f, 1.0f))
)
)
)
)
)
```
## Identity Source Function
```kotlin
val layer = maplibreMap.style!!.getLayerAs(AMSTERDAM_PARKS_LAYER)!!
layer.setProperties(
PropertyFactory.fillOpacity(
Expression.get("fill-opacity")
)
)
```
## Composite Interval Function
```kotlin
val layer = maplibreMap.style!!.getLayerAs(AMSTERDAM_PARKS_LAYER)!!
layer.setProperties(
PropertyFactory.fillColor(
Expression.step(
Expression.zoom(),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f),
Expression.stop(
7f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
8f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
9f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
10f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
11f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
12f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
13f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
14f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.literal("Jordaan"),
Expression.rgba(0.0f, 255.0f, 0.0f, 1.0f),
Expression.literal("PrinsenEiland"),
Expression.rgba(0.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
15f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
16f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
17f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
18f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.literal("Jordaan"),
Expression.rgba(0.0f, 255.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
19f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
20f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
21f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
22f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
)
)
)
)
```
## Composite Categorical Function
```kotlin
val layer = maplibreMap.style!!.getLayerAs(AMSTERDAM_PARKS_LAYER)!!
layer.setProperties(
PropertyFactory.fillColor(
Expression.step(
Expression.zoom(),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f),
Expression.stop(
7f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
8f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
9f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
10f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
11f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
12f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
13f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
14f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.literal("Jordaan"),
Expression.rgba(0.0f, 255.0f, 0.0f, 1.0f),
Expression.literal("PrinsenEiland"),
Expression.rgba(0.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
15f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
16f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
17f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
18f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.literal("Jordaan"),
Expression.rgba(0.0f, 255.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
19f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
20f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
21f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(255.0f, 0.0f, 0.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
),
Expression.stop(
22f,
Expression.match(
Expression.get("name"),
Expression.literal("Westerpark"),
Expression.rgba(0.0f, 0.0f, 255.0f, 1.0f),
Expression.rgba(255.0f, 255.0f, 255.0f, 1.0f)
)
)
)
)
)
```
---
# Distance Expression
https://docs.mapatlas.xyz/overview/sdk/android-native/styling/distance-expression
# Distance Expression
[//]: # ({{ activity_source_note("DistanceExpressionActivity.kt") }})
This example shows how you can modify a style to only show certain features within a certain distance to a point. For this the [distance expression](https://maplibre.org/maplibre-style-spec/expressions/#within) is used.
[//]: # ()
[//]: # ( ![Screenshot of map where only labels inside some circular area are shown]({{ s3_url("distance_expression_activity.png") }}){ width="400" })
[//]: # ( {{ openmaptiles_caption() }})
[//]: # ( )
First we add a [fill layer](https://maplibre.org/maplibre-style-spec/layers/#fill) and a GeoJSON source.
```kotlin
val center = Point.fromLngLat(lon, lat)
val circle = TurfTransformation.circle(center, 150.0, TurfConstants.UNIT_METRES)
maplibreMap.setStyle(
Style.Builder()
.fromUri(TestStyles.OPENFREEMAP_BRIGHT)
.withSources(
GeoJsonSource(
POINT_ID,
Point.fromLngLat(lon, lat)
),
GeoJsonSource(CIRCLE_ID, circle)
)
.withLayerBelow(
FillLayer(CIRCLE_ID, CIRCLE_ID)
.withProperties(
fillOpacity(0.5f),
fillColor(Color.parseColor("#3bb2d0"))
),
"poi"
)
)
```
Next, we only show features from symbol layers that are less than a certain distance from the point. All symbol layers whose identifier does not start with `poi` are completely hidden.
```kotlin
for (layer in style.layers) {
if (layer is SymbolLayer) {
if (layer.id.startsWith("poi")) {
layer.setFilter(lt(
distance(
Point.fromLngLat(lon, lat)
),
150
))
} else {
layer.setProperties(visibility(NONE))
}
}
}
```
---
# Draggable Marker
https://docs.mapatlas.xyz/overview/sdk/android-native/styling/draggable-marker
# Draggable Marker
[//]: # ({{ activity_source_note("DraggableMarkerActivity.kt") }})
[//]: # ()
[//]: # ( )
[//]: # ( )
[//]: # ( )
## Adding a marker on tap
```kotlin title="Adding a tap listener to the map to add a marker on tap"
maplibreMap.addOnMapClickListener {
// Adding a marker on map click
val features = maplibreMap.queryRenderedSymbols(it, layerId)
if (features.isEmpty()) {
addMarker(it)
} else {
// Displaying marker info on marker click
Snackbar.make(
mapView,
"Marker's position: %.4f, %.4f".format(it.latitude, it.longitude),
Snackbar.LENGTH_LONG
)
.show()
}
false
}
```
## Allowing markers to be dragged
This is slightly more involved, as we implement it by implementing a `DraggableSymbolsManager` helper class.
This class is initialized and we pass a few callbacks when when markers are start or end being dragged.
```kotlin
draggableSymbolsManager = DraggableSymbolsManager(
mapView,
maplibreMap,
featureCollection,
source,
layerId,
actionBarHeight,
0
)
// Adding symbol drag listeners
draggableSymbolsManager?.addOnSymbolDragListener(object : DraggableSymbolsManager.OnSymbolDragListener {
override fun onSymbolDragStarted(id: String) {
binding.draggedMarkerPositionTv.visibility = View.VISIBLE
Snackbar.make(
mapView,
"Marker drag started (%s)".format(id),
Snackbar.LENGTH_SHORT
)
.show()
}
override fun onSymbolDrag(id: String) {
val point = featureCollection.features()?.find {
it.id() == id
}?.geometry() as Point
binding.draggedMarkerPositionTv.text = "Dragged marker's position: %.4f, %.4f".format(point.latitude(), point.longitude())
}
override fun onSymbolDragFinished(id: String) {
binding.draggedMarkerPositionTv.visibility = View.GONE
Snackbar.make(
mapView,
"Marker drag finished (%s)".format(id),
Snackbar.LENGTH_SHORT
)
.show()
}
})
```
The implementation of `DraggableSymbolsManager` follows. In its initializer we define a handler for when a user long taps on a marker. This then starts dragging that marker. It does this by temporarily suspending all other gestures.
We create a custom implementation of `MoveGestureDetector.OnMoveGestureListener` and pass this to an instance of `AndroidGesturesManager` linked to the map view.
See [mapmetrics-gestures-android](https://github.com/MapMetrics/MapMetrics-gestures-android) for the implementation details of the gestures library used by MapMetrics Android.
```kotlin
/**
* A manager, that allows dragging symbols after they are long clicked.
* Since this manager lives outside of the Maps SDK, we need to intercept parent's motion events
* and pass them with [DraggableSymbolsManager.onParentTouchEvent].
* If we were to try and overwrite [AppCompatActivity.onTouchEvent], those events would've been
* consumed by the map.
*
* We also need to setup a [DraggableSymbolsManager.androidGesturesManager],
* because after disabling map's gestures and starting the drag process
* we still need to listen for move gesture events which map won't be able to provide anymore.
*
* @param mapView the mapView
* @param maplibreMap the maplibreMap
* @param symbolsCollection the collection that contains all the symbols that we want to be draggable
* @param symbolsSource the source that contains the [symbolsCollection]
* @param symbolsLayerId the ID of the layer that the symbols are displayed on
* @param touchAreaShiftX X-axis padding that is applied to the parent's window motion event,
* as that window can be bigger than the [mapView].
* @param touchAreaShiftY Y-axis padding that is applied to the parent's window motion event,
* as that window can be bigger than the [mapView].
* @param touchAreaMaxX maximum value of X-axis motion event
* @param touchAreaMaxY maximum value of Y-axis motion event
*/
class DraggableSymbolsManager(
mapView: MapView,
private val maplibreMap: MapLibreMap,
private val symbolsCollection: FeatureCollection,
private val symbolsSource: GeoJsonSource,
private val symbolsLayerId: String,
private val touchAreaShiftY: Int = 0,
private val touchAreaShiftX: Int = 0,
private val touchAreaMaxX: Int = mapView.width,
private val touchAreaMaxY: Int = mapView.height
) {
private val androidGesturesManager: AndroidGesturesManager = AndroidGesturesManager(mapView.context, false)
private var draggedSymbolId: String? = null
private val onSymbolDragListeners: MutableList = mutableListOf()
init {
maplibreMap.addOnMapLongClickListener {
// Starting the drag process on long click
draggedSymbolId = maplibreMap.queryRenderedSymbols(it, symbolsLayerId).firstOrNull()?.id()?.also { id ->
maplibreMap.uiSettings.setAllGesturesEnabled(false)
maplibreMap.gesturesManager.moveGestureDetector.interrupt()
notifyOnSymbolDragListeners {
onSymbolDragStarted(id)
}
}
false
}
androidGesturesManager.setMoveGestureListener(MyMoveGestureListener())
}
inner class MyMoveGestureListener : MoveGestureDetector.OnMoveGestureListener {
override fun onMoveBegin(detector: MoveGestureDetector): Boolean {
return true
}
override fun onMove(detector: MoveGestureDetector, distanceX: Float, distanceY: Float): Boolean {
if (detector.pointersCount > 1) {
// Stopping the drag when we don't work with a simple, on-pointer move anymore
stopDragging()
return true
}
// Updating symbol's position
draggedSymbolId?.also { draggedSymbolId ->
val moveObject = detector.getMoveObject(0)
val point = PointF(moveObject.currentX - touchAreaShiftX, moveObject.currentY - touchAreaShiftY)
if (point.x < 0 || point.y < 0 || point.x > touchAreaMaxX || point.y > touchAreaMaxY) {
stopDragging()
}
val latLng = maplibreMap.projection.fromScreenLocation(point)
symbolsCollection.features()?.indexOfFirst {
it.id() == draggedSymbolId
}?.also { index ->
symbolsCollection.features()?.get(index)?.also { oldFeature ->
val properties = oldFeature.properties()
val newFeature = Feature.fromGeometry(
Point.fromLngLat(latLng.longitude, latLng.latitude),
properties,
draggedSymbolId
)
symbolsCollection.features()?.set(index, newFeature)
symbolsSource.setGeoJson(symbolsCollection)
notifyOnSymbolDragListeners {
onSymbolDrag(draggedSymbolId)
}
return true
}
}
}
return false
}
override fun onMoveEnd(detector: MoveGestureDetector, velocityX: Float, velocityY: Float) {
// Stopping the drag when move ends
stopDragging()
}
}
private fun stopDragging() {
maplibreMap.uiSettings.setAllGesturesEnabled(true)
draggedSymbolId?.let {
notifyOnSymbolDragListeners {
onSymbolDragFinished(it)
}
}
draggedSymbolId = null
}
fun onParentTouchEvent(ev: MotionEvent?) {
androidGesturesManager.onTouchEvent(ev)
}
private fun notifyOnSymbolDragListeners(action: OnSymbolDragListener.() -> Unit) {
onSymbolDragListeners.forEach(action)
}
fun addOnSymbolDragListener(listener: OnSymbolDragListener) {
onSymbolDragListeners.add(listener)
}
fun removeOnSymbolDragListener(listener: OnSymbolDragListener) {
onSymbolDragListeners.remove(listener)
}
interface OnSymbolDragListener {
fun onSymbolDragStarted(id: String)
fun onSymbolDrag(id: String)
fun onSymbolDragFinished(id: String)
}
}
```
---
# 3D Fill Extrusion Buildings
https://docs.mapatlas.xyz/overview/sdk/android-native/styling/fill-extrusion-3d
# 3D Fill Extrusion Buildings
This tutorial shows how to add 3D extruded buildings and shapes to your MapMetrics Android map using `FillExtrusionLayer`.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## 3D Buildings from Style Data
Extrude building footprints from the map style's built-in data:
```kotlin
import android.graphics.Color
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
import org.maplibre.android.style.expressions.Expression
import org.maplibre.android.style.expressions.Expression.*
import org.maplibre.android.style.layers.FillExtrusionLayer
import org.maplibre.android.style.layers.PropertyFactory.*
class Extrusion3DActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
add3DBuildings(style)
}
}
}
private fun add3DBuildings(style: Style) {
// Add 3D building extrusion layer
val extrusionLayer = FillExtrusionLayer("3d-buildings", "composite")
extrusionLayer.setSourceLayer("building")
extrusionLayer.minZoom = 14f
extrusionLayer.setProperties(
// Height from data property
fillExtrusionHeight(
interpolate(
linear(), zoom(),
stop(14, literal(0)),
stop(14.05, get("height"))
)
),
// Base height for multi-part buildings
fillExtrusionBase(
interpolate(
linear(), zoom(),
stop(14, literal(0)),
stop(14.05, get("min_height"))
)
),
// Color
fillExtrusionColor(Color.parseColor("#AAAAAA")),
// Opacity that increases with zoom
fillExtrusionOpacity(
interpolate(
linear(), zoom(),
stop(14, 0.0f),
stop(15, 0.6f)
)
)
)
style.addLayer(extrusionLayer)
// Set 3D perspective camera
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8584, 2.2945))
.zoom(15.5)
.tilt(55.0)
.bearing(-20.0)
.build()
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Color Buildings by Height
Apply a height-based color gradient:
```kotlin
private fun addColoredBuildings(style: Style) {
val extrusionLayer = FillExtrusionLayer("3d-buildings", "composite")
extrusionLayer.setSourceLayer("building")
extrusionLayer.minZoom = 14f
extrusionLayer.setProperties(
fillExtrusionHeight(get("height")),
fillExtrusionBase(get("min_height")),
// Color gradient based on height
fillExtrusionColor(
interpolate(
linear(), get("height"),
stop(0, color(Color.parseColor("#2DC4B2"))), // Low: teal
stop(20, color(Color.parseColor("#3BB3C3"))), // Medium
stop(40, color(Color.parseColor("#669EC4"))), // Tall
stop(60, color(Color.parseColor("#8B88B6"))), // Taller
stop(100, color(Color.parseColor("#A2719B"))), // Very tall
stop(200, color(Color.parseColor("#AA5E79"))) // Skyscraper
)
),
fillExtrusionOpacity(0.7f)
)
style.addLayer(extrusionLayer)
}
```
## Custom 3D Shapes from GeoJSON
Extrude custom polygon data:
```kotlin
import com.google.gson.JsonObject
import org.maplibre.android.style.sources.GeoJsonSource
import org.maplibre.geojson.Feature
import org.maplibre.geojson.FeatureCollection
import org.maplibre.geojson.Point
import org.maplibre.geojson.Polygon
private fun addCustomExtrusions(style: Style) {
// Create features with height properties
val features = listOf(
createBuildingFeature(
listOf(
Point.fromLngLat(2.2930, 48.8580),
Point.fromLngLat(2.2945, 48.8580),
Point.fromLngLat(2.2945, 48.8570),
Point.fromLngLat(2.2930, 48.8570),
Point.fromLngLat(2.2930, 48.8580),
),
height = 50.0, name = "Building A", color = "#FF6B35"
),
createBuildingFeature(
listOf(
Point.fromLngLat(2.2950, 48.8580),
Point.fromLngLat(2.2965, 48.8580),
Point.fromLngLat(2.2965, 48.8570),
Point.fromLngLat(2.2950, 48.8570),
Point.fromLngLat(2.2950, 48.8580),
),
height = 80.0, name = "Building B", color = "#4285F4"
),
)
val collection = FeatureCollection.fromFeatures(features)
// Add source
style.addSource(GeoJsonSource("custom-buildings", collection))
// Add extrusion layer
style.addLayer(
FillExtrusionLayer("custom-3d", "custom-buildings")
.withProperties(
fillExtrusionHeight(get("height")),
fillExtrusionBase(literal(0)),
fillExtrusionColor(get("color")),
fillExtrusionOpacity(0.8f)
)
)
}
private fun createBuildingFeature(
points: List,
height: Double,
name: String,
color: String
): Feature {
val properties = JsonObject().apply {
addProperty("height", height)
addProperty("name", name)
addProperty("color", color)
}
val polygon = Polygon.fromLngLats(listOf(points))
return Feature.fromGeometry(polygon, properties)
}
```
## Light and Shadow Settings
The 3D appearance uses the map style's light configuration. Buildings facing the light source appear brighter while the opposite side is shadowed — this happens automatically based on the camera bearing and style light settings.
## Fill Extrusion Properties
| Property | Type | Description |
|----------|------|-------------|
| `fillExtrusionHeight` | Double/Expression | Top height in meters |
| `fillExtrusionBase` | Double/Expression | Base height (for stacked floors) |
| `fillExtrusionColor` | Color/Expression | Fill color |
| `fillExtrusionOpacity` | Float | Transparency (0.0 - 1.0) |
## Next Steps
- [Building Layer](./building-layer) — More building layer examples
- [Set Pitch and Bearing](../camera/set-pitch-bearing) — 3D camera angles
- [Data-Driven Styling](./data-driven-style) — Style by data properties
---
**Tip**: 3D extrusions only look good at tilt angles of 30-60°. At 0° tilt (top-down) they're invisible. Always pair `FillExtrusionLayer` with a tilted camera for the best visual effect.
---
# Filter Map Features by Properties
https://docs.mapatlas.xyz/overview/sdk/android-native/styling/filter-features
# Filter Map Features by Properties
This tutorial shows how to dynamically filter what's visible on your MapMetrics Android map based on data properties — useful for category filtering, search, and interactive data exploration.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Filter by Category
Show/hide features based on a category property:
```kotlin
import android.graphics.Color
import android.os.Bundle
import android.widget.ToggleButton
import androidx.appcompat.app.AppCompatActivity
import com.google.gson.JsonObject
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
import org.maplibre.android.style.expressions.Expression
import org.maplibre.android.style.expressions.Expression.*
import org.maplibre.android.style.layers.CircleLayer
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.sources.GeoJsonSource
import org.maplibre.geojson.Feature
import org.maplibre.geojson.FeatureCollection
import org.maplibre.geojson.Point
class FilterActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_filter)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
addData(style)
setupFilters(style)
}
}
}
private fun addData(style: Style) {
// Sample data with categories
val features = listOf(
createFeature(2.3522, 48.8566, "restaurant", "Le Petit Bistro"),
createFeature(2.3400, 48.8600, "restaurant", "Café de Flore"),
createFeature(2.3376, 48.8606, "museum", "Louvre Museum"),
createFeature(2.3266, 48.8600, "museum", "Musée d'Orsay"),
createFeature(2.3464, 48.8462, "park", "Luxembourg Gardens"),
createFeature(2.3131, 48.8601, "park", "Tuileries Garden"),
createFeature(2.3350, 48.8550, "hotel", "Hôtel Lutetia"),
createFeature(2.3280, 48.8680, "hotel", "Le Meurice"),
)
style.addSource(
GeoJsonSource("places", FeatureCollection.fromFeatures(features))
)
// Color circles by category
style.addLayer(
CircleLayer("places-layer", "places")
.withProperties(
circleRadius(8f),
circleColor(
match(
get("category"),
color(Color.GRAY), // default
stop("restaurant", color(Color.parseColor("#FF6B35"))),
stop("museum", color(Color.parseColor("#4285F4"))),
stop("park", color(Color.parseColor("#34A853"))),
stop("hotel", color(Color.parseColor("#9C27B0")))
)
),
circleStrokeColor(Color.WHITE),
circleStrokeWidth(2f)
)
)
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.857, 2.335))
.zoom(13.0)
.build()
}
private fun createFeature(lng: Double, lat: Double, category: String, name: String): Feature {
val props = JsonObject().apply {
addProperty("category", category)
addProperty("name", name)
}
return Feature.fromGeometry(Point.fromLngLat(lng, lat), props)
}
private fun setupFilters(style: Style) {
val layer = style.getLayer("places-layer") as? CircleLayer
val categories = mapOf(
R.id.btnRestaurants to "restaurant",
R.id.btnMuseums to "museum",
R.id.btnParks to "park",
R.id.btnHotels to "hotel",
)
val activeCategories = mutableSetOf("restaurant", "museum", "park", "hotel")
for ((btnId, category) in categories) {
findViewById(btnId).apply {
isChecked = true
setOnCheckedChangeListener { _, checked ->
if (checked) activeCategories.add(category)
else activeCategories.remove(category)
applyFilter(layer, activeCategories)
}
}
}
}
private fun applyFilter(layer: CircleLayer?, categories: Set) {
if (categories.isEmpty()) {
// Hide all
layer?.setFilter(literal(false))
} else if (categories.size == 4) {
// Show all — clear filter
layer?.setFilter(literal(true))
} else {
// Show only selected categories
val conditions = categories.map { cat ->
eq(get("category"), literal(cat))
}
layer?.setFilter(any(*conditions.toTypedArray()))
}
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Filter by Numeric Range
Show features within a value range:
```kotlin
// Show only features with "rating" >= 4.0
layer?.setFilter(
gte(get("rating"), literal(4.0))
)
// Show features with "price" between 10 and 50
layer?.setFilter(
all(
gte(get("price"), literal(10)),
lte(get("price"), literal(50))
)
)
```
## Filter by Text Search
Filter features whose name contains a search query:
```kotlin
import android.text.Editable
import android.text.TextWatcher
import android.widget.EditText
private fun setupSearch(style: Style) {
val layer = style.getLayer("places-layer") as? CircleLayer
findViewById(R.id.searchInput).addTextChangedListener(
object : TextWatcher {
override fun afterTextChanged(s: Editable?) {
val query = s.toString().lowercase()
if (query.isEmpty()) {
layer?.setFilter(literal(true))
} else {
// Note: Expression-based text search is limited.
// For full text search, filter the GeoJSON source instead.
filterSourceByName(style, query)
}
}
override fun beforeTextChanged(s: CharSequence?, start: Int, count: Int, after: Int) {}
override fun onTextChanged(s: CharSequence?, start: Int, before: Int, count: Int) {}
}
)
}
private fun filterSourceByName(style: Style, query: String) {
val allFeatures = /* keep a reference to all features */ listOf()
val filtered = allFeatures.filter { feature ->
val name = feature.getStringProperty("name") ?: ""
name.lowercase().contains(query)
}
val source = style.getSource("places") as? GeoJsonSource
source?.setGeoJson(FeatureCollection.fromFeatures(filtered))
}
```
## Common Filter Expressions
| Expression | Description | Example |
|-----------|-------------|---------|
| `eq(a, b)` | Equals | `eq(get("type"), literal("park"))` |
| `neq(a, b)` | Not equals | `neq(get("status"), literal("closed"))` |
| `gt(a, b)` | Greater than | `gt(get("rating"), literal(3))` |
| `gte(a, b)` | Greater or equal | `gte(get("price"), literal(10))` |
| `lt(a, b)` | Less than | `lt(get("age"), literal(5))` |
| `lte(a, b)` | Less or equal | `lte(get("distance"), literal(100))` |
| `has("key")` | Property exists | `has("phone")` |
| `all(...)` | AND — all must match | `all(gt(...), lt(...))` |
| `any(...)` | OR — at least one must match | `any(eq(...), eq(...))` |
| `not(expr)` | Negate | `not(has("archived"))` |
## Next Steps
- [Data-Driven Styling](./data-driven-style) — Style features by properties
- [Multiple Markers](../interactions/multiple-markers) — Marker category filtering
- [Circle Layer](./circle-layer) — Styled point data
---
**Tip**: For better search performance with large datasets, filter at the source level (`source.setGeoJson()`) instead of the layer level (`layer.setFilter()`). Source-level filtering prevents features from being rendered at all, while layer filters still process them on the GPU.
---
# Add an Image Overlay
https://docs.mapatlas.xyz/overview/sdk/android-native/styling/image-overlay
# Add an Image Overlay
This tutorial shows how to overlay an image (photo, floor plan, historical map) on top of your MapMetrics Android map, positioned at specific geographic coordinates.
## Prerequisites
- Completed the [Getting Started Guide](../getting-started)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Basic Image Overlay
Place an image on the map anchored to four corner coordinates:
```kotlin
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.geometry.LatLngQuad
import org.maplibre.android.maps.MapView
import org.maplibre.android.maps.MapLibreMap
import org.maplibre.android.maps.Style
import org.maplibre.android.style.layers.RasterLayer
import org.maplibre.android.style.layers.PropertyFactory.*
import org.maplibre.android.style.sources.ImageSource
class ImageOverlayActivity : AppCompatActivity() {
private lateinit var mapView: MapView
private lateinit var map: MapLibreMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
mapView = findViewById(R.id.mapView)
mapView.onCreate(savedInstanceState)
mapView.getMapAsync { maplibreMap ->
map = maplibreMap
map.setStyle(
Style.Builder().fromUri(
"https://gateway.mapmetrics-atlas.net/styles/YOUR_STYLE_ID?token=YOUR_API_KEY"
)
) { style ->
addImageOverlay(style)
}
}
}
private fun addImageOverlay(style: Style) {
// Define the four corners of the image placement
val quad = LatLngQuad(
LatLng(48.8640, 2.2880), // Top-left (NW)
LatLng(48.8640, 2.3010), // Top-right (NE)
LatLng(48.8530, 2.3010), // Bottom-right (SE)
LatLng(48.8530, 2.2880) // Bottom-left (SW)
)
// Add image source from drawable resource
style.addSource(
ImageSource("overlay-source", quad, R.drawable.historic_map)
)
// Add raster layer to display the image
style.addLayer(
RasterLayer("overlay-layer", "overlay-source")
.withProperties(
rasterOpacity(0.7f)
)
)
// Center on the overlay
map.cameraPosition = CameraPosition.Builder()
.target(LatLng(48.8585, 2.2945))
.zoom(15.0)
.build()
}
override fun onStart() { super.onStart(); mapView.onStart() }
override fun onResume() { super.onResume(); mapView.onResume() }
override fun onPause() { super.onPause(); mapView.onPause() }
override fun onStop() { super.onStop(); mapView.onStop() }
override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView.onSaveInstanceState(outState)
}
}
```
## Adjustable Opacity
Let users control the overlay transparency:
```kotlin
import android.widget.SeekBar
import android.widget.TextView
private fun setupOpacitySlider(style: Style) {
val opacityText = findViewById(R.id.tvOpacity)
findViewById(R.id.seekOpacity).apply {
max = 100
progress = 70 // default 70%
setOnSeekBarChangeListener(object : SeekBar.OnSeekBarChangeListener {
override fun onProgressChanged(seekBar: SeekBar?, value: Int, user: Boolean) {
val opacity = value / 100f
opacityText.text = "Opacity: $value%"
val layer = style.getLayer("overlay-layer") as? RasterLayer
layer?.setProperties(rasterOpacity(opacity))
}
override fun onStartTrackingTouch(seekBar: SeekBar?) {}
override fun onStopTrackingTouch(seekBar: SeekBar?) {}
})
}
}
```
## Toggle Overlay Visibility
Show or hide the overlay with a button:
```kotlin
import android.widget.ToggleButton
import org.maplibre.android.style.layers.Property
private var overlayVisible = true
private fun setupToggle(style: Style) {
findViewById(R.id.btnToggleOverlay).setOnCheckedChangeListener { _, checked ->
overlayVisible = checked
val layer = style.getLayer("overlay-layer") as? RasterLayer
layer?.setProperties(
visibility(
if (checked) Property.VISIBLE else Property.NONE
)
)
}
}
```
## Next Steps
- [Animated Image Source](./animated-image-source) — Animate image overlays
- [Custom Sprite](./custom-sprite) — Custom icons and sprites
- [Building Layer](./building-layer) — 3D building extrusions
---
**Tip**: Image overlays work best for small areas (a few blocks). For larger coverage, use raster tile sources instead — they load tiles progressively and don't require loading one massive image into memory.
---
# Add live realtime data
https://docs.mapatlas.xyz/overview/sdk/android-native/styling/live-realtime-data
# Add live realtime data
[//]: # ({{ activity_source_note("RealTimeGeoJsonActivity.kt") }})
In this example you will learn how to add a live GeoJSON source. We have set up a [lambda function](https://m6rgfvqjp34nnwqcdm4cmmy3cm0dtupu.lambda-url.us-east-1.on.aws/) that returns a new GeoJSON point every time it is called.
[//]: # ()
[//]: # ( )
[//]: # ( )
[//]: # ( )
First we will create a `GeoJSONSource`.
```kotlin title="Adding GeoJSON source"
try {
style.addSource(GeoJsonSource(ID_GEOJSON_SOURCE, URI(URL_GEOJSON_SOURCE)))
} catch (malformedUriException: URISyntaxException) {
Timber.e(malformedUriException, "Invalid URL")
}
```
Next we will create a `SymbolLayer` that uses the source.
```kotlin title="Adding a SymbolLayer source"
val layer = SymbolLayer(ID_GEOJSON_LAYER, ID_GEOJSON_SOURCE)
layer.setProperties(
PropertyFactory.iconImage("plane"),
PropertyFactory.iconAllowOverlap(true)
)
style.addLayer(layer)
```
We use define a `Runnable` and use `android.os.Handler` with a `android.os.Looper` to update the GeoJSON source every 2 seconds.
```kotlin title="Defining a Runnable for updating the GeoJSON source"
private inner class RefreshGeoJsonRunnable(
private val maplibreMap: MapLibreMap,
private val handler: Handler
) : Runnable {
override fun run() {
val geoJsonSource = maplibreMap.style!!.getSource(ID_GEOJSON_SOURCE) as GeoJsonSource
geoJsonSource.setUri(URL_GEOJSON_SOURCE)
val features = geoJsonSource.querySourceFeatures(null)
setIconRotation(features)
handler.postDelayed(this, 2000)
}
}
```
## Bonus: set icon rotation
You can set the icon rotation of the icon when ever the point is updated based on the last two points.
```kotlin title="Defining a Runnable for updating the GeoJSON source"
if (features.size != 1) {
Timber.e("Expected only one feature")
return
}
val feature = features[0]
val geometry = feature.geometry()
if (geometry !is Point) {
Timber.e("Expected geometry to be a point")
return
}
if (lastLocation == null) {
lastLocation = geometry
return
}
maplibreMap.style!!.getLayer(ID_GEOJSON_LAYER)!!.setProperties(
PropertyFactory.iconRotate(calculateRotationAngle(lastLocation!!, geometry)),
)
```
---
# Flutter — MapController
https://docs.mapatlas.xyz/overview/sdk/flutter/controller
---
title: "Flutter — MapController"
description: "Reference for MapController: camera movement, projection, feature querying, user location, navigation route snapping, and style switching"
---
# Flutter — `MapController`
`MapController` is handed to you in `MapMetricsView(onMapCreated: (controller) => ...)` — or fetched from context with `MapController.of(context)` / `MapController.maybeOf(context)` from inside `MapMetricsView`'s `mapChildren`. It's the only object you use to drive the map programmatically.
There is **no** `onMapClick`, `onCameraMove`, `onCameraIdle`, `addSymbol`, `addMarker`, `SymbolManager`, `MapMetricsController`, `CameraPosition`, `LatLng`, or `MyLocationTrackingMode` on this or any other type in the package. Map interaction events (clicks, camera changes) come through `MapMetricsView(onEvent: (MapEvent event) => ...)` instead — see [`MapEvent`](#map-events) below.
All coordinates are `Position(longitude, latitude)` — see the [coordinate order warning](./map-options#coordinate-order-longitude-first) on the `MapOptions` page.
## Getting a controller
```dart
MapMetricsView(
options: MapOptions(initCenter: Position(4.8952, 52.3702), initZoom: 12),
onMapCreated: (MapController controller) {
// store it, e.g. in a State field
},
)
```
## Camera
```dart
Future moveCamera({Position? center, double? zoom, double? bearing, double? pitch});
void moveCameraSync({Position? center, double? zoom, double? bearing, double? pitch});
Future animateCamera({
Position? center,
double? zoom,
double? bearing,
double? pitch,
Duration nativeDuration = const Duration(seconds: 2),
double webSpeed = 1.2,
Duration? webMaxDuration,
});
Future fitBounds({
required LngLatBounds bounds,
double? bearing,
double? pitch,
Duration nativeDuration = const Duration(seconds: 2),
double webSpeed = 1.2,
Duration? webMaxDuration,
Offset offset = Offset.zero,
double webMaxZoom = double.maxFinite,
bool webLinear = false,
EdgeInsets padding = EdgeInsets.zero,
});
MapCamera getCamera();
MapCamera? get camera;
```
- `moveCamera` jumps instantly; all parameters are optional — omit one to leave it unchanged.
- `moveCameraSync` is the same but synchronous (Android JNI only; falls back to async `moveCamera` on other platforms). Use it in tight render loops to avoid microtask scheduling gaps.
- `animateCamera` eases to the new position over `nativeDuration` (native) or at `webSpeed` (web, capped by `webMaxDuration`).
- `fitBounds` animates the camera to frame a `LngLatBounds`, with optional `padding`/`offset`.
- `getCamera()` / `camera` return the current `MapCamera` (`center`, `zoom`, `bearing`, `pitch`).
```dart
await controller.animateCamera(
center: Position(2.3522, 48.8566), // Paris: lng, lat
zoom: 13,
nativeDuration: const Duration(milliseconds: 1500),
);
await controller.fitBounds(
bounds: const LngLatBounds(
longitudeWest: 9.589786,
longitudeEast: 9.766498,
latitudeSouth: 47.446159,
latitudeNorth: 47.574776,
),
padding: const EdgeInsets.all(32),
);
```
Also on `MapController`:
```dart
Future getMetersPerPixelAtLatitude(double latitude);
double getMetersPerPixelAtLatitudeSync(double latitude);
Future getVisibleRegion();
LngLatBounds getVisibleRegionSync();
```
## Projection
```dart
Future toScreenLocation(Position lngLat);
Future toLngLat(Offset screenLocation);
Future> toScreenLocations(List lngLats);
Future> toLngLats(List screenLocations);
Offset toScreenLocationSync(Position lngLat);
Position toLngLatSync(Offset screenLocation);
List toScreenLocationsSync(List lngLats);
List toLngLatsSync(List screenLocations);
```
Async and sync forms exist for both single values and lists — use the plural (`toScreenLocations`/`toLngLats`) when converting several points at once instead of looping the singular form.
```dart
final screenPoint = await controller.toScreenLocation(Position(4.8952, 52.3702));
final geoPoint = await controller.toLngLat(const Offset(150, 300));
```
## Querying rendered features
```dart
Future>> queryLayers(Offset screenLocation);
Future>> queryLayersInRect(Rect rect);
```
Both return the properties of every rendered feature at the point (or within the rectangle), including layer/source metadata keys. `queryLayersInRect` is more efficient than repeated point queries when you need hit detection over an area.
```dart
Future _handleTap(Offset screenLocation) async {
final features = await controller.queryLayers(screenLocation);
final poiHits = features.where((f) => f['layerId'] == 'poi-symbols');
// ...
}
```
## User location
```dart
Future enableLocation({
Duration fastestInterval = const Duration(milliseconds: 750),
Duration maxWaitTime = const Duration(seconds: 1),
bool pulseFade = true,
bool accuracyAnimation = true,
bool compassAnimation = true,
bool pulse = true,
});
Future trackLocation({
bool trackLocation = true,
BearingTrackMode trackBearing = BearingTrackMode.gps,
});
Future showUserLocationPuck({bool show = true});
Future setLocationDraggable({bool draggable = true});
```
- `enableLocation` starts showing the user location puck (blue dot).
- `trackLocation` re-centers the camera on the user's position as it updates; `trackBearing` controls whether/how the camera bearing follows (`BearingTrackMode.none`, `.compass`, or `.gps`).
- `showUserLocationPuck` toggles puck visibility without disabling tracking.
- `setLocationDraggable` lets the user tap-drag the puck to a new position once tapped into drag mode.
Runtime location permissions must be granted first — see [Location & Permissions](./location-and-permissions).
```dart
await controller.enableLocation();
await controller.trackLocation(trackBearing: BearingTrackMode.gps);
```
## Navigation route snapping
```dart
Future setNavigationRoute(List routePoints);
Future clearNavigationRoute();
void navigateFrame({
required Position center,
required double zoom,
required double bearing,
required double pitch,
required String sourceId,
required String geoJsonData,
});
```
`setNavigationRoute` gives the location puck a route line to snap to, improving on-road accuracy while navigating. `navigateFrame` is a single synchronous call that moves the camera **and** updates a GeoJSON source together in one native frame — use it in a navigation ticker to avoid camera/marker desync that two separate calls (`moveCameraSync` + a style source update) would introduce.
## Style
```dart
Future setStyleUri(String styleUri);
```
Switches the map style in place without destroying and recreating the native map view (avoiding a crash class that can occur when GeoJSON messages are queued on the native looper during teardown). `MapMetricsView(onStyleLoaded: ...)` fires again once the new style has finished loading.
```dart
await controller.setStyleUri(
'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/dark.json&token=YOUR_API_KEY',
);
```
## Other members
```dart
MapOptions get options; // the MapOptions this map was created with
StyleController? get style; // null until onStyleLoaded has fired
```
## Map events
`MapController` itself has no click/camera-move callbacks. Instead, `MapMetricsView(onEvent: (MapEvent event) => ...)` delivers a sealed `MapEvent` hierarchy: `MapEventStyleLoaded`, `MapEventMapCreated`, `MapEventMoveCamera`, `MapEventStartMoveCamera` (carries a `CameraChangeReason`), `MapEventClick`, `MapEventDoubleClick`, `MapEventSecondaryClick`, `MapEventLongClick` (all carry a `Position point`), `MapEventIdle`, and `MapEventCameraIdle`.
```dart
MapMetricsView(
options: MapOptions(initCenter: Position(4.8952, 52.3702), initZoom: 12),
onEvent: (event) {
switch (event) {
case MapEventClick(:final point):
debugPrint('tapped at $point');
case MapEventCameraIdle():
debugPrint('camera settled');
default:
break;
}
},
)
```
## See also
- [MapOptions reference](./map-options) — the object that configures the map this controller belongs to
- [Location & Permissions](./location-and-permissions) — `PermissionManager` paired with `enableLocation`/`trackLocation`
- [Offline maps](./offline) — downloading regions ahead of using `setStyleUri`/`moveCamera` offline
---
# Flutter — Getting Started
https://docs.mapatlas.xyz/overview/sdk/flutter/getting-started
---
title: "Flutter — Getting Started"
description: "End-to-end first map with the mapmetrics Flutter package: pubspec dependency, Android and iOS platform setup, and a full runnable main.dart"
---
# Flutter — Getting Started
This walks through everything needed to render a MapMetrics Atlas map in a Flutter app, from the pubspec entry to a runnable `main.dart`.
::: warning Coordinate order
`mapmetrics` takes coordinates as `Position(longitude, latitude)` — **longitude first**, GeoJSON order. This is the opposite order from the `LatLng(latitude, longitude)` pattern used by `google_maps_flutter` and older MapMetrics docs. See [MapOptions reference](./map-options) for the full warning.
:::
## 1. Add the dependency
```yaml
dependencies:
mapmetrics: ^1.0.6
```
```bash
flutter pub get
```
The package re-exports `package:geotypes/geotypes.dart` (for `Position`), so you don't need to add `geotypes` yourself.
## 2. Platform setup
### Android
`mapmetrics`'s own `android/build.gradle` sets `minSdk = 21` — your app module needs at least that:
```gradle
// android/app/build.gradle
android {
defaultConfig {
minSdk = 21
}
}
```
If you plan to use [user location](./location-and-permissions) (`MapController.enableLocation()`/`trackLocation()`/`PermissionManager`), declare the location permissions in `android/app/src/main/AndroidManifest.xml` — this is what the SDK's own example app declares:
```xml
NSLocationWhenInUseUsageDescription
This app needs your location to display your location on the map.
NSLocationAlwaysUsageDescription
This app requires access to your location.
NSLocationAlwaysAndWhenInUseUsageDescription
This app requires access to your location.
```
Skip these three keys if your app never calls `enableLocation()`/`trackLocation()` — iOS will reject the build-time permission prompt wiring if the keys are missing but the location APIs are called at runtime, so only add what you use.
::: tip Could not verify
The exact minimum Xcode/Swift toolchain version isn't pinned anywhere in the repo beyond the podspec's `s.swift_version = '5.0'` and MapLibre iOS dependency `~> 6.11`. If you hit a build error referencing Swift language version, check `ios/mapmetrics.podspec` in the installed package for the current constraint.
:::
## 3. Get a style URL and API key
Create a style and an API key in the [MapMetrics portal](https://portal.mapmetrics.org), then build a style URL of this shape:
```
https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY
```
Both the `fileName` and `token` query parameters are required — the gateway will reject a bare `?token=` URL without a `fileName`.
## 4. A full runnable `main.dart`
```dart
import 'package:flutter/material.dart';
import 'package:mapmetrics/mapmetrics.dart';
const String _styleUrl =
'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'MapMetrics Demo',
theme: ThemeData(colorSchemeSeed: Colors.blue),
home: const MapPage(),
);
}
}
class MapPage extends StatefulWidget {
const MapPage({super.key});
@override
State createState() => _MapPageState();
}
class _MapPageState extends State {
MapController? _controller;
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('MapMetrics')),
body: MapMetricsView(
options: MapOptions(
initStyle: _styleUrl,
// Position(longitude, latitude) — Amsterdam is lng 4.8952, lat 52.3702.
initCenter: Position(4.8952, 52.3702),
initZoom: 12,
),
onMapCreated: (controller) {
_controller = controller;
},
onStyleLoaded: (style) {
// The style has finished loading; safe to add sources/layers here.
},
),
);
}
}
```
Run it with `flutter run`.
## Next steps
- [MapOptions reference](./map-options) — every constructor field, defaults, and the coordinate-order trap
- [MapController reference](./controller) — camera control, projection, feature querying, style switching
- [Location & Permissions](./location-and-permissions) — showing and tracking the user's own position
- [Offline maps](./offline) — downloading a region for offline use
---
# Flutter — Location & Permissions
https://docs.mapatlas.xyz/overview/sdk/flutter/location-and-permissions
---
title: "Flutter — Location & Permissions"
description: "PermissionManager paired with MapController's location methods to show and track the user's own position, plus required platform permission declarations"
---
# Flutter — Location & Permissions
Showing the user's own position on the map takes two objects working together: `PermissionManager` (requests/checks OS location permission) and the location methods on [`MapController`](./controller#user-location) (actually show/track the puck). Neither works alone — `enableLocation()` will fail if permission hasn't been granted, and granting permission does nothing to the map by itself.
`PermissionManager` cannot be used on web.
## `PermissionManager`
```dart
abstract interface class PermissionManager {
factory PermissionManager();
bool get backgroundLocationPermissionGranted;
bool get locationPermissionsGranted;
bool get runtimePermissionsRequired;
Future requestLocationPermissions({required String explanation});
}
```
| Member | Description |
|---|---|
| `locationPermissionsGranted` | `true` if either coarse or fine location access is currently granted. |
| `backgroundLocationPermissionGranted` | `true` if background location access is granted. |
| `runtimePermissionsRequired` | `true` if the OS requires asking for location permission at runtime (i.e. Android 6+/iOS, as opposed to permissions declared only at install time). |
| `requestLocationPermissions({required String explanation})` | Triggers the OS permission prompt (using `explanation` where the platform surfaces a rationale string) and resolves to whether it was granted. |
Construct it with the plain factory constructor — no arguments:
```dart
final permissionManager = PermissionManager();
```
## Platform permission declarations
### Android
```xml
NSLocationWhenInUseUsageDescription
This app needs your location to display your location on the map.
NSLocationAlwaysUsageDescription
This app requires access to your location.
NSLocationAlwaysAndWhenInUseUsageDescription
This app requires access to your location.
```
Without these declarations the runtime permission prompt will not appear (Android) or the app will crash when requesting location (iOS).
## Wiring it together
```dart
import 'package:flutter/material.dart';
import 'package:mapmetrics/mapmetrics.dart';
class UserLocationPage extends StatefulWidget {
const UserLocationPage({super.key});
@override
State createState() => _UserLocationPageState();
}
class _UserLocationPageState extends State {
final _permissionManager = PermissionManager();
MapController? _controller;
Future _showMyLocation() async {
final granted = await _permissionManager.requestLocationPermissions(
explanation: 'Show your location on the map.',
);
if (!granted || _controller == null) return;
await _controller!.enableLocation();
await _controller!.trackLocation(trackBearing: BearingTrackMode.gps);
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('User Location')),
body: Column(
children: [
Padding(
padding: const EdgeInsets.all(8),
child: OutlinedButton(
onPressed: _showMyLocation,
child: const Text('Show my location'),
),
),
Expanded(
child: MapMetricsView(
options: MapOptions(
initCenter: Position(-74.006, 40.7128), // New York: lng, lat
initZoom: 9,
),
onMapCreated: (controller) => _controller = controller,
),
),
],
),
);
}
}
```
## Checking permission state without prompting
Read the getters directly to reflect current state in your UI (e.g. to decide whether to show a "request permission" button at all):
```dart
final manager = PermissionManager();
if (!manager.locationPermissionsGranted) {
// show a prompt / explainer before calling requestLocationPermissions
}
```
## Related `MapController` methods
Once permission is granted, these live on `MapController` (full reference: [MapController — User location](./controller#user-location)):
- `enableLocation({...})` — start showing the location puck
- `trackLocation({trackLocation, trackBearing})` — re-center the camera on the user as it moves
- `showUserLocationPuck({show})` — toggle puck visibility
- `setLocationDraggable({draggable})` — allow the user to drag the puck to a new position
- `setNavigationRoute(List)` / `clearNavigationRoute()` — snap the puck to a route line while navigating
## See also
- [MapController reference](./controller) — full method signatures
- [Getting Started](./getting-started) — platform setup for a first map
---
# Flutter — MapOptions
https://docs.mapatlas.xyz/overview/sdk/flutter/map-options
---
title: "Flutter — MapOptions"
description: "Every real MapOptions field on MapMetricsView: type, default, and what it does, including the longitude-first initCenter coordinate order"
---
# Flutter — `MapOptions`
`MapOptions` is the immutable configuration object passed to `MapMetricsView(options: ...)`. It sets the initial camera, style, zoom/pitch limits, and gesture configuration.
::: danger Coordinate order: longitude first
`initCenter` takes a `Position(longitude, latitude)` from the `geotypes` package — **not** `LatLng(latitude, longitude)`. Getting the argument order backwards silently places the map somewhere else on Earth; nothing throws or errors.
```dart
// Correct — Amsterdam is lng 4.8952, lat 52.3702:
MapOptions(initCenter: Position(4.8952, 52.3702))
// WRONG — this is lat-first and puts the map in the wrong place:
MapOptions(initCenter: Position(52.3702, 4.8952))
```
Sanity-check every coordinate you write: is the first number a plausible **longitude** (−180..180) for the place you mean, and the second a plausible **latitude** (−90..90)?
:::
## Constructor
```dart
const MapOptions({
this.initStyle = 'https://demotiles.maplibre.org/style.json',
this.initZoom = 0,
this.initCenter,
double initPitch = 0,
this.initBearing = 0,
this.minZoom = 0,
this.maxZoom = 22,
this.minPitch = 0,
this.maxPitch = 60,
this.maxBounds,
this.gestures = const MapGestures.all(),
this.androidTextureMode = true,
this.androidMode = AndroidPlatformViewMode.tlhc_vd,
})
```
## Fields
| Field | Type | Default | Description |
|---|---|---|---|
| `initStyle` | `String` | `'https://demotiles.maplibre.org/style.json'` | The style URL loaded on map creation. **Override this in real apps** — see below for the MapMetrics gateway URL shape. |
| `initZoom` | `double` | `0` | The initial zoom level. |
| `initCenter` | `Position?` | `null` | The initial map center, **longitude first**: `Position(lng, lat)`. |
| `initPitch` | `double` | `0` | The initial camera pitch/tilt. 0–85 on web, 0–60 on other platforms. (A deprecated `pitch` named parameter exists for backwards compatibility; use `initPitch`.) |
| `initBearing` | `double` | `0` | The initial map bearing (rotation). `0` is north-up; `360` is one full loop. |
| `minZoom` | `double` | `0` | The minimum allowed zoom level (0–24). |
| `maxZoom` | `double` | `22` | The maximum allowed zoom level (0–24). |
| `minPitch` | `double` | `0` | The minimum allowed camera pitch. |
| `maxPitch` | `double` | `60` | The maximum allowed camera pitch (0–85 on web, 0–60 elsewhere; larger values are ignored on native). |
| `maxBounds` | `LngLatBounds?` | `null` | Restricts the camera to this bounding box. `null` means no restriction. |
| `gestures` | `MapGestures` | `const MapGestures.all()` | Enables/disables individual gesture types (see below). |
| `androidTextureMode` | `bool` | `true` | Toggles Android texture mode for the platform view. Comes at a performance cost when enabled. |
| `androidMode` | `AndroidPlatformViewMode` | `AndroidPlatformViewMode.tlhc_vd` | The Android platform view type used to embed the native map (see [Flutter platform views](https://docs.flutter.dev/platform-integration/android/platform-views)). |
There is **no** `styleUrl`, `initialCameraPosition`, `myLocationEnabled`, `myLocationTrackingMode`, `compassEnabled`, or `trackCameraPosition` field — those belong to a different, non-existent API.
## Real style URL
Never ship `https://demotiles.maplibre.org/style.json` (the MapLibre upstream default) in a production app — it's unbranded and unversioned. Use the MapMetrics Atlas gateway:
```
https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY
```
```dart
MapOptions(
initStyle:
'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
initCenter: Position(4.8952, 52.3702), // Amsterdam: lng, lat
initZoom: 12,
)
```
## `MapGestures`
`gestures` takes a `MapGestures` value, which toggles four independent gesture categories:
```dart
class MapGestures {
const MapGestures({
required this.rotate,
required this.pan,
required this.zoom,
required this.pitch,
});
const MapGestures.all({ // every gesture enabled — the MapOptions default
this.rotate = true,
this.pan = true,
this.zoom = true,
this.pitch = true,
});
const MapGestures.none({ // every gesture disabled
this.rotate = false,
this.pan = false,
this.zoom = false,
this.pitch = false,
});
}
```
Example — a static, non-interactive map (e.g. for a thumbnail or preview card):
```dart
MapOptions(
initCenter: Position(4.8952, 52.3702),
initZoom: 14,
gestures: const MapGestures.none(),
)
```
Or disable just rotation while keeping pan/zoom/pitch:
```dart
MapOptions(
gestures: const MapGestures(rotate: false, pan: true, zoom: true, pitch: true),
)
```
## Restricting the camera to an area
`maxBounds` takes a `LngLatBounds`, whose fields are also longitude/latitude — but named explicitly, so there's no ordering ambiguity:
```dart
MapOptions(
initCenter: Position(9.717795, 47.504100), // Bregenz
initZoom: 12,
maxBounds: const LngLatBounds(
longitudeWest: 9.589786,
longitudeEast: 9.766498,
latitudeSouth: 47.446159,
latitudeNorth: 47.574776,
),
)
```
## See also
- [MapController reference](./controller) — the object handed to `onMapCreated`, used to move the camera and query the map after it's created
- [Getting Started](./getting-started) — a full runnable app using `MapOptions`
---
# Flutter — Offline Maps
https://docs.mapatlas.xyz/overview/sdk/flutter/offline
---
title: "Flutter — Offline Maps"
description: "OfflineManager, OfflineRegion and DownloadProgress — downloading a bounded map region for offline use"
---
# Flutter — Offline Maps
The offline package lets you download a bounded, zoom-limited slice of a style (tiles + glyphs/sprites) to the device so the map keeps working without a network connection. It is exposed through three types: `OfflineManager` (the entry point), `OfflineRegion` (a downloaded region's metadata), and `DownloadProgress` (streamed download state).
`OfflineManager` cannot be used on web.
This is a thin wrapper over MapLibre Native's offline storage — the API surface below is everything it exposes; there is no additional region-management UI or background-download scheduling built in.
## Creating the manager
```dart
abstract interface class OfflineManager {
static Future createInstance();
void dispose();
}
```
```dart
final manager = await OfflineManager.createInstance();
// ...
manager.dispose(); // free native resources when no longer needed, e.g. in State.dispose()
```
## Downloading a region
```dart
Stream downloadRegion({
required String mapStyleUrl,
required LngLatBounds bounds,
required double minZoom,
required double maxZoom,
required double pixelDensity,
Map metadata = const {},
});
```
`downloadRegion` returns a `Stream` — listen to it to drive a progress indicator and detect completion:
```dart
final bregenz = const LngLatBounds(
longitudeWest: 9.589786,
longitudeEast: 9.766498,
latitudeSouth: 47.446159,
latitudeNorth: 47.574776,
);
final stream = manager.downloadRegion(
mapStyleUrl:
'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
bounds: bregenz,
minZoom: 10,
maxZoom: 14,
pixelDensity: 1,
);
await for (final update in stream) {
if (update.downloadCompleted) {
print('done: ${update.region}');
break;
}
print('${update.loadedTiles}/${update.totalTiles} '
'(${((update.progress ?? 0) * 100).toStringAsFixed(0)}%)');
}
```
## `DownloadProgress`
```dart
class DownloadProgress {
final int loadedBytes;
final int loadedTiles;
final int totalTiles;
final bool totalTilesEstimated;
final OfflineRegion region;
final bool downloadCompleted;
double? get progress; // loadedTiles / totalTiles, or null if totalTilesEstimated
}
```
`totalTiles` is a lower bound while `totalTilesEstimated` is `true` (early in the download, before the style and tile sources are fully resolved); once the precise count is known, `totalTilesEstimated` flips to `false` and `progress` starts returning a real fraction instead of `null`.
## `OfflineRegion`
```dart
class OfflineRegion {
final int id;
final LngLatBounds bounds;
final double minZoom;
final double maxZoom;
final double pixelRatio;
final String styleUrl;
}
```
This is the metadata record for a downloaded region — returned inside `DownloadProgress.region`, and by the lookup/listing calls below.
## Managing downloaded regions
```dart
Future getOfflineRegion({required int regionId});
Future> listOfflineRegions();
Future resetDatabase(); // deletes the existing database and re-initializes it
```
```dart
final region = await manager.getOfflineRegion(regionId: 1);
final all = await manager.listOfflineRegions();
```
Android-only region-database maintenance calls (no-ops to avoid on iOS — check `Platform.isIOS` before calling):
```dart
Future> mergeOfflineRegions({required String path});
Future packDatabase();
void runPackDatabaseAutomatically({required bool enabled}); // enabled by default
```
## Ambient cache
Separate from named offline regions, MapLibre also maintains an ambient tile cache (tiles seen during normal map browsing, evictable, not guaranteed to persist):
```dart
void setOfflineTileCountLimit({required int amount}); // default limit: 6,000 tiles
Future setMaximumAmbientCacheSize({required int bytes});
Future clearAmbientCache();
Future invalidateAmbientCache(); // forces re-validation, doesn't clear
```
## Using a downloaded region
There's no dedicated "load this region offline" call — once tiles for a `LngLatBounds` are downloaded, point `MapOptions.initStyle` at the same style URL and constrain the camera to the same bounds with `MapOptions.maxBounds`; the map will read from the local offline store for any tile already downloaded, and hit the network for anything outside that:
```dart
MapMetricsView(
options: MapOptions(
initStyle: region.styleUrl,
maxBounds: region.bounds,
initCenter: Position(9.717795, 47.5041), // Bregenz: lng, lat
initZoom: 12,
maxZoom: region.maxZoom,
),
)
```
## See also
- [MapOptions reference](./map-options) — `maxBounds` and `initStyle`
- [MapController reference](./controller) — `setStyleUri` to switch to an offline-downloaded style at runtime
---
# Flutter / Dart SDK
https://docs.mapatlas.xyz/overview/sdk/geocoding/flutter
# Flutter / Dart SDK
`mapatlas_geocoder` is a pure-Dart client (no Flutter dependency, sound null
safety, zero runtime dependencies) for the
[v2 geocoding API](../../geocoder/v2/autocomplete.md) — session-based
autocomplete, place retrieval, forward/reverse geocoding, Valhalla-backed
routing, and isochrones. Because the core package is plain Dart, it works
server-side too, not just from a Flutter app.
::: warning Not published yet
`dart pub add mapatlas_geocoder` will work once the package is on pub.dev.
Until then, add it as a git dependency in `pubspec.yaml`:
```yaml
dependencies:
mapatlas_geocoder:
git:
url: https://github.com/MapMetrics/geocoder-sdk
path: Flutter
```
:::
## Install
```bash
dart pub add mapatlas_geocoder
```
## Quickstart
```dart
import 'package:mapatlas_geocoder/mapatlas_geocoder.dart';
Future main() async {
final mapatlas = MapAtlas(token: 'YOUR_API_KEY');
// One session covers a whole search — every keystroke, then the pick.
final session = mapatlas.geocoding.createSession();
// As the user types. Debounced inside the client; suggestions carry no
// coordinates.
final results = await session.suggest('Nieuwezijds');
// When they pick one, hand back the Suggestion — not an id.
final place = await session.retrieve(results.first);
print('${place.center.lat}, ${place.center.lon}');
// Resolving several at once is both fewer round trips and cheaper billing —
// see Sessions & Billing.
final places = await session.retrieveBatch(results.take(3).toList());
// One-shot lookups, when there's no user typing to debounce. Both return GeoJSON.
await mapatlas.geocoding.search('Nieuwezijds Voorburgwal 147', country: 'nl');
await mapatlas.geocoding.reverse(lat: 52.37, lon: 4.89);
mapatlas.close(); // releases the underlying HTTP client
}
```
## Constructing a client
```dart
MapAtlas(
token: 'YOUR_API_KEY', // XOR getToken — exactly one is required
// getToken: () async => await fetchRotatingToken(),
baseUrl: 'https://gateway.mapmetrics-atlas.net', // default
tier: MapAtlasTier.v2, // default; or MapAtlasTier.osm
debounce: Duration(milliseconds: 150), // default; Duration.zero disables
);
```
Use `getToken` instead of `token` for a short-lived or asynchronously
fetched key (secure storage, or a backend-issued rotating credential) — it's
called fresh before every request.
## The reactive layer: `GeocodeSearchController`
`GeocodeSearchController` wires a search box's whole lifecycle — debounced
`suggest()` calls, one session per search, out-of-order response handling,
typed errors — into a single object you drive with `controller.query = ...`
and observe with a `StreamBuilder`. It's the Dart/Flutter analogue of the
`useAutocomplete` React hook in the sibling `@mapmetrics/geocoder` package.
If you want the whole search box — list, history, favourites, category chips
— rather than wiring your own, see
[`MapAtlasSearchField`](./search-ui.md); this controller is the headless
layer beneath it.
::: warning Where the debounce actually lives
The controller does **not** debounce. Coalescing happens one layer down, in
`GeocodeSession.suggest()` inside the client — configured by
`MapAtlas(debounce: …)`, default `Duration(milliseconds: 150)`. Assignments
to `controller.query` fire immediately and the client absorbs the burst.
Do not wrap `controller.query = …` in your own `Timer`. Stacking a second
debounce on the client's only adds lag. If 150 ms is wrong, change
`debounce` on the client.
**One exception:** the OSM tier has no session, so nothing downstream
coalesces and the controller debounces there itself, using the same value.
:::
It's built on `dart:async`'s `Stream`, not `ValueListenable`/
`ChangeNotifier` — those live in `package:flutter/foundation.dart`, which
this package can't import without depending on Flutter. `StreamBuilder`
consumes a `Stream` natively, so nothing extra is needed on the Flutter
side.
```dart
import 'package:flutter/material.dart';
import 'package:mapatlas_geocoder/mapatlas_geocoder.dart';
class AddressField extends StatefulWidget {
const AddressField({super.key, required this.mapatlas});
final MapAtlas mapatlas;
@override
State createState() => _AddressFieldState();
}
class _AddressFieldState extends State {
late final GeocodeSearchController _controller = GeocodeSearchController(
client: widget.mapatlas,
country: 'nl',
);
final _textController = TextEditingController();
@override
void dispose() {
_controller.dispose(); // cancels pending work; safe even mid-request
_textController.dispose();
super.dispose();
}
Future _onSelect(Suggestion suggestion) async {
try {
final place = await _controller.select(suggestion);
_textController.text = suggestion.placeName ?? suggestion.text ?? '';
debugPrint('Selected ${place.center.lat}, ${place.center.lon}');
} on MapAtlasException {
// Already reflected in state.error via the StreamBuilder below.
}
}
@override
Widget build(BuildContext context) {
return Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
TextField(
controller: _textController,
onChanged: (value) => _controller.query = value,
decoration: const InputDecoration(hintText: 'Search an address…'),
),
StreamBuilder(
stream: _controller.states,
initialData: _controller.state,
builder: (context, snapshot) {
final state = snapshot.data!;
if (state.isLoading) {
return const LinearProgressIndicator();
}
if (state.error != null) {
return Text(
state.error!.message,
style: TextStyle(color: Theme.of(context).colorScheme.error),
);
}
return ListView(
shrinkWrap: true,
children: [
for (final suggestion in state.suggestions)
ListTile(
title: Text(suggestion.placeName ?? suggestion.text ?? ''),
subtitle: Text(suggestion.layer),
onTap: () => _onSelect(suggestion),
),
],
);
},
),
],
);
}
}
```
**Behavior:**
- **One session per search.** `GeocodeSession` is created once, in the
constructor, and reused across every `query` assignment; `select()`
retrieves and closes it, and the next `query` assignment transparently
opens a fresh one.
- **Out-of-order responses never win.** Every request carries a
monotonically increasing sequence number; a slow response for an earlier
keystroke arriving after a later one's is discarded.
- **`minLength` (default 2) short-circuits locally** — below it,
`state.suggestions` clears synchronously with no request and no session
activity.
- **Nothing is emitted after `dispose()`.** `states` closes with no error;
a request already in flight when `dispose()` is called resolves harmlessly
in the background.
- **Errors always land as a typed `MapAtlasException`** in `state.error`,
never as an unhandled async error.
If you'd rather work with `ValueListenable` (e.g. to reuse existing
`ValueListenableBuilder` widgets), wrap the stream in three lines of app
code — this needs `package:flutter/foundation.dart`, which is why it isn't
built into the package itself:
```dart
final notifier = ValueNotifier(controller.state);
final sub = controller.states.listen((s) => notifier.value = s);
// Later: sub.cancel(); notifier.dispose();
```
## Routing & isochrones
`mapatlas.routing` covers `directions()`/`directionsSimple()`, `matrix()`,
`mapMatching()`, and `optimization()` (the path is `/optimization/` —
`/optimize/` 404s); `mapatlas.isochrone()` returns reachability contours.
`Costing` and `ShapeMatch` are enums, not raw strings, so a typo like
`'motorscooter'` is a compile error rather than a silent gateway rejection.
Response models are deliberately permissive (a parsed top-level structure
plus `raw`, the full decoded body) since Valhalla's field set is large and
version-dependent. See `example/routing_example.dart` and
`example/isochrone_example.dart` in the package, or the
[README](https://github.com/MapMetrics/geocoder-sdk/tree/main/Flutter#routing-and-isochrones)
for full request/response shapes.
## The OSM tier
`MapAtlasTier.osm` routes `search()`/`reverse()`/`autocomplete()` to
`/osm-geocode/`/`/osm-reverse/`/`/osm-autocomplete/`, using the
`osm-geocode` scope. There's no session or retrieve concept on this tier —
`createSession()` throws `TierUnsupportedException`, and `autocomplete()`
results already carry coordinates. Rate-limited to 10,000 requests/key/day
plus a global monthly cap; `QuotaExceededException` carries a self-host link
once you hit it.
### Self-hosting
The free tier's engine is open source:
[MapMetrics/atlas-osm-geocoder](https://github.com/MapMetrics/atlas-osm-geocoder),
deployable on Cloudflare Workers with a prebuilt planet bundle. Point this
package at your own instance with `MapAtlas.selfHostedOsm()`:
```dart
final mapatlas = MapAtlas.selfHostedOsm(baseUrl: 'https://my-worker.workers.dev');
await mapatlas.geocoding.search('Nieuwezijds Voorburgwal 147');
await mapatlas.geocoding.autocomplete('Nieuwezijds');
await mapatlas.geocoding.reverse(lat: 52.37, lon: 4.89);
```
A self-hosted instance takes no token and uses different paths (`/search`,
`/reverse`, `/autocomplete`, no `token` parameter); this package never sends
a credential to it, even if you pass `token`/`getToken` by mistake — it
throws instead. `createSession()` (and `GeocodeSession.retrieve()` /
`retrieveBatch()`) throw `TierUnsupportedException`, exactly as on
`MapAtlasTier.osm` — this engine has no session concept at all.
## Choosing a key for a Flutter app
Origin restriction is a **browser-only** feature — it checks the `Origin`
header a browser sends, and native mobile/desktop apps never send one. Use
an **unrestricted key** in a Flutter app; an origin-restricted key raises
`OriginRequiredException` on every request, by design. See
[API Keys & Security](../../api-keys.md) for the full model.
## Errors
Every failure is a `MapAtlasException` subtype:
| Exception | Cause |
|---|---|
| `TokenNotFoundException` | Key not provisioned. |
| `TokenInactiveException` | Key exists but is deactivated. |
| `ScopeException` | Key lacks the scope the endpoint requires. |
| `OriginRequiredException` | Key is origin-restricted; request had no `Origin` header. |
| `OriginNotAllowedException` | Key is origin-restricted; request's `Origin` isn't on the allow list. |
| `QuotaExceededException` | OSM-tier quota exhausted; carries `selfHostLink`. |
| `TierUnsupportedException` | Operation not supported on the current tier. |
| `NetworkException` | Connection failure, or a response that didn't match the expected shape. |
```dart
try {
await mapatlas.geocoding.search('Nieuwezijds Voorburgwal 147', country: 'nl');
} on OriginRequiredException {
// ...
} on MapAtlasException catch (e) {
// catches every other documented failure mode
}
```
### Suggestions without an `ord`
`Suggestion` carries **no coordinates** — only `retrieve()`/`retrieveBatch()`
return them. `ord` is nullable: check `suggestion.isRetrievable` (or the
nullability of `ord` itself) before calling `retrieve()` on a row you're not
sure about. Calling `retrieve()` on a non-retrievable suggestion throws a
typed exception explaining why, rather than a silent 404 or a null crash;
`retrieveBatch()` rejects the whole call if any item in the list is
non-retrievable.
In the raw gateway JSON the `ord` key is **absent** on those rows, not
present-and-`null` — this package normalises it to `null` when decoding, so
`ord == null` is a safe test here even though it is not against raw HTTP.
### Don't use `suggestion.id` as a widget key
::: danger `id` is not unique within one response
`q=amsterdam&country=nl` returns two rows sharing `"id": "place.0"`. Two
widgets with the same `ValueKey` in one list make Flutter reuse element
state between unrelated rows, and in a `ListView.builder` with an explicit
`findChildIndexCallback` it can throw outright.
:::
The `for (final suggestion in state.suggestions)` form above is safe — it
keys on position. For stable keys, use `uniquifyRowIds` from
`package:mapatlas_geocoder/ui.dart`, which suffixes repeats (`place.0`,
`place.0#2`) instead of dropping rows. See [Search UI](./search-ui.md).
## Testing your own code against this package
`HttpTransport` is exported so you can inject a fake in your own tests
instead of hitting the network:
```dart
final mapatlas = MapAtlas(token: 't', transport: myFakeTransport);
```
## Endpoint reference
This SDK is a typed wrapper — for the full parameter list, response shape,
and gateway-level gotchas each call is protecting you from, see:
- [Autocomplete (v2)](../../geocoder/v2/autocomplete.md)
- [Retrieve (v2)](../../geocoder/v2/retrieve.md)
- [Forward Geocode (v2)](../../geocoder/v2/forwardgeocode.md)
- [Reverse Geocode (v2)](../../geocoder/v2/reversegeocode.md)
- [Sessions & Billing](./sessions.md)
- [API Keys & Security](../../api-keys.md)
---
# Geocoding SDKs
https://docs.mapatlas.xyz/overview/sdk/geocoding/
# Geocoding SDKs
Four typed client packages wrap the [v2 geocoder](../../geocoder/v2/autocomplete.md)
so you don't hand-roll the autocomplete → retrieve loop, session billing, or
error parsing yourself:
| language | package | source |
|---|---|---|
| TypeScript / JavaScript | [`@mapmetrics/geocoder`](./javascript.md) | `NPM/` |
| Dart / Flutter | [`mapatlas_geocoder`](./flutter.md) | `Flutter/` |
| Swift (iOS / macOS) | [`MapAtlasGeocoder`](./swift.md) | `Swift/` |
| Kotlin (Android / JVM) | [`mapatlas-geocoder`](./kotlin.md) | `Android/` |
::: warning Not published yet
None of these packages are on npm, pub.dev, Swift Package Index, or Maven
Central yet. Each language page shows both the form that will work once they
ship *and* a form that works today. Don't expect `npm install`/`dart pub add`
to resolve against a public registry right now.
All four live in **subdirectories of one monorepo**, which is what makes the
interim install awkward — and what breaks the two shortcuts people reach for
first. Neither of these works:
- `npm install github:MapMetrics/geocoder-sdk#path:NPM` — `#path:` is pnpm
syntax; npm reads it as a git ref and fails. See
[JavaScript → Installing before publication](./javascript.md#installing-before-publication).
- `.package(url: ".../geocoder-sdk", branch: "main")` — SwiftPM only reads
the repository root, and there is no root `Package.swift`. See
[Swift → Install](./swift.md#install).
:::
## Why use an SDK instead of calling the gateway directly
The raw HTTP API (documented under [Geocoder v2](../../geocoder/v2/autocomplete.md))
has a handful of sharp edges that are easy to get wrong once and then debug
for an hour, because most of them fail silently — HTTP 200 with an empty or
subtly wrong result, not an error:
- **Sessions are billed, not requests.** Autocomplete is billed per search
session. Forgetting to carry a stable `session_token` across keystrokes
doesn't error — it just charges roughly 5x more, silently. Every SDK here
manages the token for you: one session per search box interaction,
automatically.
- **Debounce is your job otherwise.** Without it, a fast typist fires a
request per keystroke. All four SDKs debounce `suggest()` calls (150ms by
default) — inside the **client**, not the controller. See
[Where the debounce lives](#where-the-debounce-lives) below before you add
a timer of your own.
- **Retrieval is keyed on `ord`, not `id`.** Retrieving by `id` 404s on
every layer. Every SDK takes the suggestion object straight from
`suggest()` and reads `ord` off it for you — there's no id to get wrong.
- **Some suggestions can't be retrieved at all.** The gateway injects
locality rows (e.g. two of the fifteen results for `q=amsterdam`) that
carry no `ord` — the key is *absent* from the JSON, not `null`, so naive
property access on a strict decoder throws. Every SDK normalises this and
exposes `isRetrievable` on a suggestion so you can filter or disable those
rows before the user taps one.
- **`id` is not unique and must never be a list key.** Two rows in one
response can share an `id` (`place.0` twice for `q=amsterdam`). This
crashes a Compose `LazyColumn` outright and silently corrupts row state in
React and SwiftUI. The [search UI layers](./search-ui.md) de-collide ids
for you.
- **`hn` is a house number string, not a boolean.** It reads like a flag,
and sending `hn=true` to `/v2/retrieve/` is silently ignored — you get the
street centroid instead of the building, ~146 m off. Every SDK passes the
suggestion's own value through.
- **Batch retrieval has one specific encoding.** `/v2/retrieve-batch/`
accepts exactly one URL-encoded JSON `items` parameter — repeated
`ord=`/`ords=`/`ids=` params silently return `count: 0`. The SDKs build
that payload for you from an array of suggestion objects.
- **Errors come back as HTTP status + a code string**, not an exception
hierarchy. Each SDK turns them into typed errors/exceptions — a distinct
type per failure (`ScopeError`, `OriginRequiredError`,
`QuotaExceededError`, …) — so you can `catch`/`switch` on what actually
went wrong instead of parsing `error.status` and `error.code` yourself.
- **Response shape is easy to get wrong.** Forward/reverse geocode return a
different, flat shape unless you pass `format=pelias`. Every SDK forces
the GeoJSON envelope on every search/reverse call — you always get a
`FeatureCollection`.
None of this is exotic — it's mechanical, and it's exactly the kind of thing
worth doing once, in a typed client, instead of every app re-deriving it
from the endpoint docs.
## What's the same across all four
- A `MapAtlas` client constructed with an API key (or a `getToken` callback,
for rotating credentials).
- `client.geocoding.createSession()` → `session.suggest(query)` →
`session.retrieve(suggestion)` / `session.retrieveBatch(suggestions)`.
- A reactive controller for the common "search box" UI shape — see the
per-language page for its name and idiom (React hook, Dart `Stream`,
Swift `@Observable`, Kotlin `StateFlow`).
- A **drop-in search UI** on top of that controller — a rendered search box
with history, favourites, category chips and keyboard navigation. See
[Search UI](./search-ui.md).
- One-shot `search()` / `reverse()` calls for when there's no user typing to
debounce.
- A free `tier: 'osm'` (naming varies per language) backed by the
`osm-geocode` scope, and a dedicated self-hosted constructor for
[MapMetrics/atlas-osm-geocoder](https://github.com/MapMetrics/atlas-osm-geocoder) —
see each page's "OSM tier" section.
- Typed errors/exceptions for every documented gateway failure mode —
see [API Keys & Security](../../api-keys.md) for what each one means.
## What differs
- **Routing, matrix, and isochrones** are implemented in the TypeScript and
Dart packages only. Swift and Kotlin are geocoding-only for now — see
their pages for exactly what's covered.
- Native platforms (Swift, Kotlin, Flutter) need an **unrestricted** API
key. Origin restriction only works for browsers — see
[Choosing a key for a native app](#choosing-a-key-for-native-apps) below.
## Where the debounce lives
All four SDKs debounce as-you-type `suggest()` calls at **150 ms by
default**, but it is worth knowing exactly which layer does it, because
adding a second one is a common and invisible mistake.
The debounce lives in the **client**, configured at construction:
| SDK | Option | Default |
|---|---|---|
| TypeScript | `new MapAtlas({ debounceMs })` | `150` |
| Dart | `MapAtlas(debounce: …)` | `Duration(milliseconds: 150)` |
| Swift | `MapAtlas(debounceMs:)` | `150` |
| Kotlin | `MapAtlas(debounceMs = …)` | `150` |
The reactive controllers (`useAutocomplete`, `GeocodeSearchController`, …) do
**not** debounce. They pass every keystroke straight down, and
`Session.suggest()` coalesces the burst.
::: warning Don't stack a second timer
Wrapping `setQuery`/`controller.query` in your own `Timer`/`setTimeout`, or
setting the React hook's optional `debounceMs`, adds latency on top of the
client's debounce without reducing request count — the client is already
coalescing underneath. If 150 ms is wrong for your UI, change the client's
value; that is the one knob.
:::
**The one exception:** on the OSM tier there is no `Session`, so there is
nothing downstream to coalesce. On that tier the controller debounces itself,
reusing the same configured value — so the behaviour you observe is the same
and you still shouldn't add your own.
## Choosing a key for native apps
Origin restriction is enforced by checking the browser's `Origin` header —
native apps, and any server-side code, send no `Origin` header at all, so an
origin-restricted key can never satisfy that check. This is the single most
common integration error a mobile developer hits with these SDKs: reuse a
web key in a Flutter/Swift/Kotlin app, and every request throws an
origin-required error.
Use an **unrestricted** key for the Flutter, Swift, and Kotlin SDKs. Origin
restriction is still the right call for a browser key used with the
TypeScript SDK. See [API Keys & Security](../../api-keys.md) for the full
scope and origin model, and [Sessions](./sessions.md) for the billing model
shared by all four SDKs.
## Next
- [Sessions & billing](./sessions.md) — the model every SDK is built around.
- [Search UI](./search-ui.md) — the drop-in search box, in all four languages.
- [JavaScript / TypeScript](./javascript.md)
- [Flutter](./flutter.md)
- [Swift](./swift.md)
- [Kotlin](./kotlin.md)
---
# JavaScript / TypeScript SDK
https://docs.mapatlas.xyz/overview/sdk/geocoding/javascript
# JavaScript / TypeScript SDK
`@mapmetrics/geocoder` is a TypeScript client for the
[v2 geocoding API](../../geocoder/v2/autocomplete.md) — autocomplete, place
retrieval, forward/reverse geocoding, routing, and isochrones. Zero runtime
dependencies, ships ESM + CJS + types, and runs anywhere `fetch` exists:
Node 18+, browsers, and edge runtimes like Cloudflare Workers.
::: warning Not published yet
`npm install @mapmetrics/geocoder` will work once the package ships. Until
then, build it from a clone — see [Installing before
publication](#installing-before-publication).
:::
## Install
```bash
npm install @mapmetrics/geocoder
```
### Installing before publication
::: danger `#path:` is pnpm syntax and does not work with npm
An earlier version of this page suggested:
```bash
npm install github:MapMetrics/geocoder-sdk#path:NPM # ❌ does not work
```
`#path:` is a **pnpm** extension. npm parses everything after `#` as a git
committish, clones the repository **root**, finds no `package.json` there
(the manifest is in `NPM/`), and fails:
```
npm error code ENOENT
npm error enoent Could not read package.json: ENOENT: no such file or
npm error directory, open '…/_cacache/tmp/git-cloneXXXXXX/package.json'
```
Yarn Classic and npm behave the same way. Only pnpm understands `#path:`.
:::
The package is a monorepo subdirectory and its `dist/` is not committed, so
consume it as a **built local dependency**:
```bash
git clone https://github.com/MapMetrics/geocoder-sdk
cd geocoder-sdk/NPM
npm install
npm run build # required — dist/ is gitignored and there is no prepare script
```
Then, from your app:
```bash
npm install /absolute/path/to/geocoder-sdk/NPM
```
or as a `package.json` entry:
```json
{
"dependencies": {
"@mapmetrics/geocoder": "file:../geocoder-sdk/NPM"
}
}
```
The `npm run build` step is not optional. `package.json` lists `dist` under
`files`, but there is no `prepare`/`prepack` script, so nothing builds
automatically on install — skip it and you get a package whose entry points
resolve to files that do not exist.
If your project uses **pnpm**, the one-liner does work there:
```bash
pnpm add "github:MapMetrics/geocoder-sdk#path:/NPM"
```
## Quickstart
```ts
import { MapAtlas } from '@mapmetrics/geocoder';
const mapatlas = new MapAtlas({ token: 'YOUR_API_KEY' });
// One session covers a whole search — every keystroke, then the pick.
const session = mapatlas.geocoding.createSession();
// As the user types. Debounced inside the client (see below); suggestions
// carry no coordinates.
const results = await session.suggest('Nieuwezijds');
// When they pick one, hand back the suggestion object — not an id.
const place = await session.retrieve(results[0]);
console.log(place.latitude, place.longitude);
// Resolving several at once is both fewer round trips and cheaper billing —
// see Sessions & Billing.
const places = await session.retrieveBatch(results.slice(0, 3));
// One-shot lookups, when there's no user typing to debounce. Both return GeoJSON.
await mapatlas.geocoding.search('Nieuwezijds Voorburgwal 147', { country: 'nl' });
await mapatlas.geocoding.reverse(52.37, 4.89);
```
## Constructor options
```ts
new MapAtlas({ token: 'YOUR_API_KEY' });
// or, if you rotate/refresh tokens yourself:
new MapAtlas({ getToken: async () => await fetchFreshToken() });
```
| Option | Default | Notes |
|---|---|---|
| `token` | — | Exactly one of `token` / `getToken` is required. |
| `getToken` | — | Called fresh on every request — never cached by this package. |
| `baseUrl` | `https://gateway.mapmetrics-atlas.net` | Override for testing or a self-hosted gateway. |
| `tier` | `'v2'` | `'osm'` routes to the free, rate-limited OpenStreetMap-only tier. |
| `debounceMs` | `150` | Debounces rapid `suggest()` calls. `0` disables. |
## The reactive layer: `useAutocomplete`
`@mapmetrics/geocoder/react` is a separate subpath export with a headless
`useAutocomplete` hook — it owns the `Session` (and therefore billing),
debouncing, request cancellation, and error handling. Importing the core
`@mapmetrics/geocoder` entry never pulls React into your bundle; `react`
(>=18) is an optional peer dependency, only needed if you import this
subpath.
```bash
npm install react react-dom # if your app doesn't already have them
```
```tsx
import { useMemo, useState } from 'react';
import { MapAtlas } from '@mapmetrics/geocoder';
import { useAutocomplete } from '@mapmetrics/geocoder/react';
import type { Suggestion } from '@mapmetrics/geocoder';
function AddressField() {
const client = useMemo(() => new MapAtlas({ token: 'YOUR_API_KEY' }), []);
const [selecting, setSelecting] = useState(false);
const {
query, setQuery, // controlled input value
suggestions, // Suggestion[] — updates as the user types
isLoading, // a request is in flight
error, // typed MapAtlasError | null
select, // (s: Suggestion) => Promise
selected, // RetrievedPlace | null — last successful selection
reset, // clear query, suggestions, error and selection
} = useAutocomplete({ client, country: 'nl', minLength: 2 });
async function handleSelect(s: Suggestion) {
setSelecting(true);
try {
const place = await select(s);
console.log(place.latitude, place.longitude);
} catch {
// already surfaced via `error` below
} finally {
setSelecting(false);
}
}
return (
setQuery(e.target.value)}
placeholder="Search an address…"
/>
{isLoading &&
Searching… }
{error &&
{error.name}: {error.message} }
{/* Key on index, not on s.ord or s.id — see the warning below. */}
{suggestions.map((s, i) => (
handleSelect(s)}>
{s.placeName ?? s.text}
))}
{selected && (
{selected.latitude}, {selected.longitude}
Clear
)}
);
}
```
**Options:** `client` (required), `country`, `proximity`, `minLength`
(default `2` — below it, no request fires and `suggestions` is cleared),
`debounceMs` (extra debounce stacked on top of the client's own — leave
unset).
::: warning Where the debounce actually lives
The hook does **not** debounce on the `v2` tier. Coalescing happens one layer
down, in `Session.suggest()` inside the client — configured by
`new MapAtlas({ debounceMs })`, default `150`.
The hook's own `debounceMs` option is an *additional* timer on top of that.
Leave it unset. Setting it to, say, `300` gives you 300 ms of extra lag
without reducing request count, because the client is already coalescing
underneath.
**One exception:** the `osm` tier has no `Session`, so nothing downstream
coalesces. There the hook adds a single timer itself, reusing
`client.geocoding.debounceMs` — so the same 150 ms default applies and you
still do not need to configure anything.
:::
::: danger Never key a React list on `ord` or `id`
Neither is a usable React `key`:
- **`ord` is missing entirely** on non-retrievable rows — the key is absent
from the JSON, not `null`. Two of the fifteen rows for `q=amsterdam` have
no `ord`, so `key={s.ord}` renders `key={undefined}` on both, and React
falls back to index while warning.
- **`id` repeats.** `q=amsterdam&country=nl` returns two rows with
`"id": "place.0"`. Duplicate React keys silently swap component state
between rows.
Use the array index, or the `uniquifyRows` helper from
`@mapmetrics/geocoder/react` — see [Search UI](./search-ui.md).
:::
**Session lifecycle** matches the core `Session`: one session per `client`,
reused across every keystroke; `select()` retrieves and closes it, and the
next `setQuery()` reopens one automatically. `suggestCount` and `isOpen` on
the hook's return value mirror `Session.suggestCount` / `Session.isOpen`.
**Safety guarantees:** out-of-order responses are discarded (a slow response
for an earlier keystroke never overwrites a later one); no `setState` fires
after unmount; React 18 ``-safe (no duplicate session, no
duplicate request on double-invoked effects).
## Routing & isochrones
`mapatlas.routing` and the top-level `mapatlas.isochrone()` wrap the
gateway's Valhalla-backed endpoints — directions, matrix, map matching, and
route optimization. `costing` is a strict union
(`'auto' | 'bicycle' | 'bus' | 'truck' | 'taxi' | 'motor_scooter' |
'pedestrian' | 'bikeshare'`), not a bare string, and this client always
hits `/optimization/`, not `/optimize/` (the latter 404s). See the
[README](https://github.com/MapMetrics/geocoder-sdk/tree/main/NPM#routing--isochrones)
for the full request/response shapes.
## The OSM tier
`tier: 'osm'` talks to the free, OpenStreetMap-only endpoints
(`/osm-geocode/`, `/osm-reverse/`, `/osm-autocomplete/`) via the
`osm-geocode` scope. It has no session/retrieve flow — `search()`,
`reverse()`, and `autocomplete()` are the only three operations, results
already carry coordinates, and `createSession()` throws
`TierUnsupportedError`. Rate-limited to 10,000 requests/key/day plus a
global monthly cap; hitting it throws `QuotaExceededError`.
### Self-hosting
The free tier's engine is open source:
[MapMetrics/atlas-osm-geocoder](https://github.com/MapMetrics/atlas-osm-geocoder),
deployable on Cloudflare Workers with a prebuilt planet bundle. Point this
package at your own instance with `MapAtlas.selfHosted()`:
```ts
const mapatlas = MapAtlas.selfHosted({ baseUrl: 'https://my-worker.workers.dev' });
await mapatlas.geocoding.search('Nieuwezijds Voorburgwal 147');
await mapatlas.geocoding.autocomplete('Nieuwezijds');
await mapatlas.geocoding.reverse(52.37, 4.89);
```
A self-hosted instance takes no token and uses different paths
(`/search`, `/reverse`, `/autocomplete` — no `/osm-` prefix, no `token`
parameter); `selfHosted()` never sends a credential to it, even if you pass
one by mistake. `createSession()` and session-based retrieval are
unavailable on a self-hosted client, same as on `tier: 'osm'` — there's no
session concept on this engine.
## Errors
All errors extend `MapAtlasError`:
- `TokenNotFoundError` — key was never provisioned.
- `TokenInactiveError` — key exists but is deactivated.
- `ScopeError` — key lacks the scope this operation requires.
- `OriginRequiredError` — key is origin-restricted, request sent no `Origin`
header. Native/server clients can never satisfy this — see
[Choosing a key for native apps](./index.md#choosing-a-key-for-native-apps).
- `OriginNotAllowedError` — request's `Origin` isn't on the key's allow-list.
- `QuotaExceededError` — OSM tier cap exhausted; carries `selfHostUrl`.
- `TierUnsupportedError` — thrown by `createSession()` on the `osm` tier and
on `selfHosted()` clients, and by `autocomplete()` on the `v2` tier.
- `NetworkError` — the request never completed, or the response wasn't
parseable JSON.
```ts
import { MapAtlasError, ScopeError } from '@mapmetrics/geocoder';
try {
await mapatlas.geocoding.search('Nieuwezijds Voorburgwal 147', { country: 'nl' });
} catch (e) {
if (e instanceof ScopeError) {
// ...
} else if (e instanceof MapAtlasError) {
// catches every other documented failure mode
} else {
throw e;
}
}
```
Prefer `e.code` / `e.name` (plain strings) over `instanceof` if your app
might load this package as both ESM and CJS in the same dependency tree —
that produces two distinct class objects for the same error, and
`instanceof` won't match across them.
::: tip Not every suggestion can be resolved
The gateway returns some rows — injected locality entries, such as the city
itself when you type "Amsterdam" — with no retrieve handle. They are still
returned so you can show them in a list, but they cannot be turned into
coordinates.
`suggestion.isRetrievable` tells you which is which. In the raw gateway JSON
the `ord` key is **absent** on those rows rather than `null`; this package
normalises it to `null` (never `NaN`) when decoding, so you can test it
directly:
```ts
const results = await session.suggest('Amsterdam', { country: 'nl' });
const usable = results.filter((s) => s.isRetrievable);
```
Calling `retrieve()` on a non-retrievable suggestion throws
`NotRetrievableError`. `retrieveBatch()` rejects the whole call if any item is
non-retrievable, rather than silently returning fewer places than you asked
for. All four SDKs behave identically here.
:::
## Endpoint reference
This SDK is a typed wrapper — for the full parameter list, response shape,
and gateway-level gotchas each call is protecting you from, see:
- [Autocomplete (v2)](../../geocoder/v2/autocomplete.md)
- [Retrieve (v2)](../../geocoder/v2/retrieve.md)
- [Forward Geocode (v2)](../../geocoder/v2/forwardgeocode.md)
- [Reverse Geocode (v2)](../../geocoder/v2/reversegeocode.md)
- [Sessions & Billing](./sessions.md)
- [API Keys & Security](../../api-keys.md)
---
# Kotlin SDK
https://docs.mapatlas.xyz/overview/sdk/geocoding/kotlin
# Kotlin SDK
`mapatlas-geocoder` is a pure Kotlin/JVM client for the
[v2 geocoding API](../../geocoder/v2/autocomplete.md) — autocomplete, place
retrieval, and forward/reverse geocoding. Because it's plain Kotlin/JVM (not
an Android library module), the exact same artifact runs on Android and on
a server-side JVM.
::: warning Not published yet
Not on Maven Central. Consume it as a Gradle composite build or a local
Maven artifact today — see below.
:::
## Install
**As a composite build** (`settings.gradle.kts` in your app):
```kotlin
includeBuild("../Geocoder-SDK/Android") {
dependencySubstitution {
substitute(module("net.mapmetrics:mapatlas-geocoder")).using(project(":"))
}
}
```
```kotlin
// app/build.gradle.kts
dependencies {
implementation("net.mapmetrics:mapatlas-geocoder:1.0.0")
}
```
**As a local Maven artifact:**
```bash
cd Geocoder-SDK/Android
gradle publishToMavenLocal
```
```kotlin
repositories { mavenLocal() }
dependencies {
implementation("net.mapmetrics:mapatlas-geocoder:1.0.0")
}
```
**Why plain Kotlin/JVM, not an Android library module?** It uses the
`kotlin("jvm")` Gradle plugin, not the Android Gradle Plugin — no Android
SDK is required to build or unit test it. Android compatibility comes from
targeting JVM 11 bytecode and from using only APIs that exist in
`android.jar`.
::: danger Do not enable core library desugaring for this
Earlier versions of this page claimed the HTTP layer used `java.net.http`
and that Android's core library desugaring covered it. **That was wrong, and
it failed at runtime.**
`java.net.http` is not in `android.jar` at any API level, and it is not
covered by `desugar_jdk_libs`. Enabling desugaring did not help, and — worse
— D8 emitted **zero warnings**, so the app compiled and installed cleanly and
then died on the first `MapAtlas(...)` construction:
```
java.lang.NoClassDefFoundError: Failed resolution of: Ljava/net/http/HttpClient;
```
This is fixed in the SDK: the HTTP engine is reimplemented on
`java.net.HttpURLConnection`, which is present on every supported API level.
You need **no** desugaring configuration, and adding it will not fix a
`NoClassDefFoundError` if you are pinned to an older build — upgrade instead.
:::
## Quickstart
```kotlin
import net.mapmetrics.geocoder.MapAtlas
import net.mapmetrics.geocoder.SearchOptions
import net.mapmetrics.geocoder.GeocodeSearchResult
val mapatlas = MapAtlas(token = "YOUR_API_KEY")
// One session covers a whole search — every keystroke, then the pick.
val session = mapatlas.geocoding.createSession()
// As the user types. Debounced inside the client (see below); suggestions
// carry no coordinates.
val results = session.suggest("Nieuwezijds")
// When they pick one, hand back the suggestion — not an id.
val place = session.retrieve(results[0])
println("${place.latitude}, ${place.longitude}")
// Resolving several at once is both fewer round trips and cheaper billing —
// see Sessions & Billing.
val places = session.retrieveBatch(results.take(3))
// One-shot lookups, when there's no user typing to debounce.
val fwd = mapatlas.geocoding.search("Nieuwezijds Voorburgwal 147", SearchOptions(country = "nl"))
val rev = mapatlas.geocoding.reverse(latitude = 52.37, longitude = 4.89)
check(fwd is GeocodeSearchResult.Pelias) // always true on the default v2 tier
mapatlas.close() // releases the HTTP engine's threads and the coroutine scope backing Session debouncing
```
## The reactive layer: `GeocodeSearchController`
`GeocodeSearchController` exposes a single `StateFlow` — own it (and a
`MapAtlas`) in a `ViewModel`, collect it in a Compose screen, and you have a
working, correctly-billed, debounced search box. It discards stale
out-of-order responses and turns failures into typed state rather than
thrown exceptions.
::: warning Where the debounce actually lives
The controller does **not** debounce. Coalescing happens one layer down, in
`Session.suggest()` inside the client — configured by
`MapAtlas(debounceMs = …)`, default `150`. `setQuery()` therefore fires
immediately and the client absorbs the burst.
Do not add a second timer around `setQuery()`. Stacking one on top of the
client's produces a laggy field and does not reduce request count further.
If 150 ms is wrong for you, change `debounceMs` on the client — that is the
single knob.
**One exception:** on the OSM tier there is no `Session`, so nothing
downstream coalesces, and the controller debounces there itself using the
same `debounceMs` value.
:::
```kotlin
class AddressSearchViewModel : ViewModel() {
private val mapatlas = MapAtlas(token = "YOUR_API_KEY")
val controller = GeocodeSearchController(
client = mapatlas,
scope = viewModelScope,
country = "nl",
minLength = 2,
)
fun onQueryChanged(text: String) = controller.setQuery(text)
suspend fun onSuggestionPicked(suggestion: Suggestion): RetrievedPlace =
controller.select(suggestion)
override fun onCleared() {
controller.close()
mapatlas.close()
}
}
```
```kotlin
@Composable
fun AddressSearchScreen(viewModel: AddressSearchViewModel = viewModel()) {
val state by viewModel.controller.state.collectAsState()
val scope = rememberCoroutineScope()
Column {
TextField(
value = state.query,
onValueChange = viewModel::onQueryChanged,
placeholder = { Text("Search an address…") },
)
if (state.isLoading) CircularProgressIndicator()
state.error?.let { Text("${it::class.simpleName}: ${it.message}", color = Color.Red) }
LazyColumn {
items(state.suggestions) { suggestion ->
Text(
text = suggestion.placeName ?: suggestion.text.orEmpty(),
modifier = Modifier.clickable {
scope.launch {
val place = viewModel.onSuggestionPicked(suggestion)
// navigate / use place.latitude, place.longitude
}
},
)
}
}
state.selected?.let { place ->
Text("Selected: ${place.latitude}, ${place.longitude}")
}
}
}
```
`GeocodeSearchState` carries `query`, `suggestions`, `isLoading`, `error` (a
typed `MapAtlasException?`), and `selected`. Out-of-order responses are
discarded automatically: type "a" then quickly "ab", and a slow response for
"a" arriving after "ab" is dropped rather than flashing stale results — the
controller lets the older request finish (it doesn't race to cancel it) and
simply ignores its result once superseded.
## The OSM tier
`tier = MapAtlasTier.OSM` talks to the free, OpenStreetMap-only endpoints
via the `osm-geocode` scope. No session/retrieve flow — `search()`,
`reverse()`, and `autocomplete()` are the only three operations, returning
`GeocodeSearchResult.Osm` / `OsmResponse` (a permissive wrapper around the
raw JSON). Calling `createSession()` on this tier throws
`MapAtlasException.TierUnsupported`. Rate-limited to 10,000 requests/key/day
plus a global monthly cap; exhausting it throws
`MapAtlasException.QuotaExceeded` with a `selfHostUrl`.
### Self-hosting
The free tier's engine is open source:
[MapMetrics/atlas-osm-geocoder](https://github.com/MapMetrics/atlas-osm-geocoder),
deployable on Cloudflare Workers with a prebuilt planet bundle. Point this
package at your own instance with `MapAtlas.selfHosted()`:
```kotlin
val mapatlas = MapAtlas.selfHosted(baseUrl = "https://my-worker.workers.dev")
mapatlas.geocoding.search("Nieuwezijds Voorburgwal 147")
mapatlas.geocoding.autocomplete("Nieuwezijds")
mapatlas.geocoding.reverse(latitude = 52.37, longitude = 4.89)
```
A self-hosted instance takes no token and uses different paths (`/search`,
`/reverse`, `/autocomplete`, no `token` parameter) — this package never
sends a credential to it. `createSession()` (and therefore
`Session.retrieve()`/`retrieveBatch()`) throw `TierUnsupported` on a
self-hosted client, exactly as on the hosted `osm` tier — this engine has no
session concept either. `QuotaExceeded` cannot occur self-hosted (no quota).
## Choosing a key for an Android app
Origin restriction is a **browser-only** feature — it works by checking the
`Origin` header a browser sends, and native apps don't send one. **This is
the error an Android developer will hit** if they reuse a browser-restricted
key: an origin-restricted key can never work from Android. Use an
unrestricted key for native/server clients. See
[API Keys & Security](../../api-keys.md) for the full model.
## Errors
All errors extend the sealed `MapAtlasException`. Kotlin's `when` is
exhaustive over a sealed class, so the compiler flags anything you miss:
- `TokenNotFound` — key was never provisioned.
- `TokenInactive` — key exists but is deactivated.
- `ScopeNotAllowed` — key is valid but not scoped for this operation.
- `OriginRequired` — key is origin-restricted, no `Origin` header sent. See
[Choosing a key for an Android app](#choosing-a-key-for-an-android-app).
- `OriginNotAllowed` — request's `Origin` isn't on the key's allow-list.
- `QuotaExceeded` — OSM tier cap exhausted; carries `selfHostUrl`.
- `TierUnsupported` — thrown by `createSession()` on the `osm` tier and on
`MapAtlas.selfHosted()` clients, and by `autocomplete()` on the `v2` tier.
- `NotRetrievable` — thrown by `retrieve()`/`retrieveBatch()` when a
suggestion has no `ord` (see below).
- `NetworkError` — the request never completed.
- `DecodingError` — a response was received but couldn't be parsed.
- `Unknown` — any other non-2xx response this package doesn't have a
specific subclass for; still carries `status`/`code` where available.
```kotlin
try {
mapatlas.geocoding.search("Nieuwezijds Voorburgwal 147", SearchOptions(country = "nl"))
} catch (e: MapAtlasException.ScopeNotAllowed) {
// ...
} catch (e: MapAtlasException) {
// catches every other documented failure mode
}
```
Every exception carries `status: Int?` and `code: String?` alongside
`message`.
### Suggestions without coordinates, or an `ord`
`Suggestion` deliberately carries **no coordinates** — only `retrieve()`/
`retrieveBatch()` return them. Separately, `ord` is nullable: the gateway
returns injected locality rows among ordinary results for some queries (two
of the fifteen rows for `q=amsterdam&country=nl` at last check) that carry
no `ord` at all — the key is **absent from the JSON**, not present-and-null.
This SDK decodes that to `ord == null` for you, so you can test it normally;
raw HTTP callers cannot. Check `suggestion.isRetrievable` before calling
`retrieve()` on a row you're not sure about:
```kotlin
val suggestions = session.suggest("Amsterdam")
val retrievable = suggestions.filter { it.isRetrievable }
val place = session.retrieve(retrievable.first())
```
Calling `retrieve()` on a non-retrievable suggestion throws
`MapAtlasException.NotRetrievable` with a message explaining why, rather
than crashing on a null or silently 404ing. `retrieveBatch()` rejects the
**whole call** if any item in the list is non-retrievable, rather than
silently dropping the offending item(s).
### Never key a `LazyColumn` on `suggestion.id`
::: danger `id` is not unique within one response
`q=amsterdam&country=nl` returns two rows sharing `"id": "place.0"`. Passing
that to `items(state.suggestions, key = { it.id })` throws:
```
IllegalArgumentException: Key "place.0" was already used.
If you are using LazyColumn/LazyRow please make sure you provide a unique key
```
This is a real crash we hit in a Compose demo, not a hypothetical.
:::
The `items(state.suggestions) { … }` form in the sample above is safe — it
keys on index. If you need stable keys across recompositions, derive one
from content, or use the `mapatlas-geocoder-ui` module, whose
`SearchRowKeys.uniquify` suffixes repeats (`place.0`, `place.0#1`) so keys
are unique without dropping rows. See [Search UI](./search-ui.md).
## Not implemented yet
This package covers geocoding only — routing, matrix, map matching,
optimization, and isochrones are **not** implemented here. The TypeScript
and Dart SDKs cover those endpoints; see [JavaScript](./javascript.md) or
[Flutter](./flutter.md) if you need routing from a shared backend or a
cross-platform Dart layer.
## Endpoint reference
This SDK is a typed wrapper — for the full parameter list, response shape,
and gateway-level gotchas each call is protecting you from, see:
- [Autocomplete (v2)](../../geocoder/v2/autocomplete.md)
- [Retrieve (v2)](../../geocoder/v2/retrieve.md)
- [Forward Geocode (v2)](../../geocoder/v2/forwardgeocode.md)
- [Reverse Geocode (v2)](../../geocoder/v2/reversegeocode.md)
- [Sessions & Billing](./sessions.md)
- [API Keys & Security](../../api-keys.md)
---
# Search UI
https://docs.mapatlas.xyz/overview/sdk/geocoding/search-ui
---
title: Search UI
description: A drop-in, themeable search box for all four geocoding SDKs — history, favourites, category chips and keyboard navigation, sharing one vocabulary across Flutter, Swift, Kotlin and React.
---
# Search UI
Every [geocoding SDK](./index.md) ships an optional UI layer on top of its
headless controller: a rendered search box with a results list, recent
searches, favourites, category chips and keyboard navigation.
The headless controllers give you state and leave the markup to you. That is
the right default for a design system, and the wrong default for the ninety
percent of apps that want a search box that works. This layer is that search
box.
::: tip Three layers, pick one
| Layer | Use when |
|---|---|
| `MapAtlas` + `Session` | You're on a server, or building something that isn't a search box. |
| `GeocodeSearchController` / `useAutocomplete` | You want your own markup but not your own session, debounce and race handling. |
| **Search UI** (this page) | You want a search box. |
:::
All four implementations were built against the same specification, so the
concepts below mean the same thing in every language. Only the spelling
changes.
## Shared vocabulary
### One flat row list, four kinds
The panel renders a single flat list of rows, never nested sections. Each row
declares its kind:
| Kind | Meaning |
|---|---|
| `favourite` | A place the user explicitly starred. Persisted. |
| `history` | A place the user previously selected. Persisted, capped. |
| `suggestion` | A live result from the gateway for the current query. |
| `category` | A live result produced by tapping a category chip. |
A flat list is what makes keyboard navigation, screen-reader announcement and
`onPlaceSelected` uniform: "row 3 of 12" is meaningful, and one arrow-key
handler covers every kind.
Rows carry a display `label`, an optional secondary label, the originating
`Suggestion` where there was one, and the `SavedPlace` where there was one.
### `SavedPlace` is a resolved place
`SavedPlace` (`MapAtlasSavedPlace` in Swift) is deliberately **not** a stored
suggestion. It holds real coordinates, captured at the moment the user picked
the place.
This matters because [v2 suggestions carry no
coordinates](/overview/geocoder/v2/autocomplete) and their `ord` handles are
not stable across time or sessions. Persisting a suggestion would give you a
history list that needs a billable network round trip to render, and whose
entries silently rot. Persisting the *resolved* place means history and
favourites render instantly, offline, with no gateway call and no session
billing.
Fields: a display label, an optional secondary label, longitude/latitude, and
optional `layer` / `country` / `locality`, plus a `savedAt` timestamp.
### The store
Persistence sits behind a four-method interface so you can redirect it to
your own backend, a keychain, or an encrypted database:
```
loadHistory() / saveHistory(places)
loadFavourites() / saveFavourites(places)
```
Defaults per platform:
| SDK | Default store |
|---|---|
| Flutter | `SharedPreferencesSearchStore` (namespace `mapatlas.search`) |
| Swift | `MapAtlasUserDefaultsSearchStore` (`UserDefaults.standard`) |
| Kotlin | `DataStoreSearchStore` (Preferences DataStore, `mapatlas_geocoder_ui`) |
| React | `createLocalStorageStore()` (`localStorage`) |
Each also ships an in-memory implementation (`InMemorySearchStore`,
`MapAtlasEphemeralSearchStore`) for tests and for privacy modes where nothing
should be written to disk.
### Deduplication: one identity tuple
The gateway returns near-duplicate rows routinely — the same address indexed
twice, the same POI under two source ids. All four SDKs collapse them using
the **same identity tuple**:
```
(text, placeName, locality, layer, housenumber)
```
Each part is trimmed, lowercased and whitespace-collapsed, then joined.
**First occurrence wins**, and the original ordering is preserved, so
relevance ranking survives deduplication. Rows with no visible text at all opt
out rather than collapsing into each other.
Dedup is pluggable — pass `noDeduplication` to keep everything, or supply
your own key function.
### `id` is not a key — so ids get de-collided
Deduplication is not the same problem as key collision, and the SDKs handle
them separately.
The gateway's `id` field [is not unique within one
response](/overview/geocoder/v2/autocomplete#id-is-not-unique-within-a-response):
`q=amsterdam&country=nl` returns two rows with `"id": "place.0"`, and on the
OSM tier `poi.0` is shared by genuinely different places. Fed into a keyed
list this crashes Compose (`IllegalArgumentException: Key … was already
used`) and quietly corrupts row state in React and SwiftUI.
So after deduplication — which removes *actual* duplicates — a uniquifier
runs over whatever remains and suffixes any repeated id:
| SDK | Helper |
|---|---|
| Flutter | `uniquifyRowIds(rows)` |
| Swift | internal `uniquingIDs(_:)` |
| Kotlin | `SearchRowKeys.uniquify(rows)` |
| React | `uniquifyRows(rows)` |
Two distinct places that happen to share an id both survive, with distinct
row ids. Nothing is dropped to make keys unique.
### Category chips
Six categories ship by default, in this order:
`restaurant` · `fuel` · `hotel` · `parking` · `cafe` · `supermarket`
::: warning The chips work by rewriting the query text
There is **no category parameter** on `/v2/autocomplete/` — `category=` and
friends are [silently
ignored](/overview/geocoder/v2/autocomplete#there-is-no-category-filter-on-this-endpoint)
there. So tapping a chip prepends the category id to the query text
(`amsterdam` → `hotel amsterdam`) and re-runs an ordinary search. Tapping the
active chip again strips the token back out.
This is a **ranking bias, not a filter**. Non-matching rows still appear, and
quality varies by category — `hotel` and `supermarket` rank well, `fuel`
poorly. Do not present chip results to users as an exhaustive list of that
category.
:::
For real filtering — a hard category restriction, proximity-ranked, with
`distance_m` on every feature — supply the `categorySearch` /
`onCategorySearch` override and point it at
[`/v2/category/`](/overview/geocoder/v2/category). Every implementation
accepts a callback of the shape `(category, proximity) -> rows`, and uses it
instead of the query-text trick when present.
### Selection
One callback, everywhere:
```
onPlaceSelected(place, label)
```
The `label` is passed separately because the resolved place carries
coordinates and administrative context but **no display name** — the name the
user actually saw lives on the row. Passing it alongside means you can write
it straight into your UI without re-deriving a label from the place.
Selecting a row also, by default, records it in history.
### Debounce
None of these UI layers debounce. They pass keystrokes straight through and
the client coalesces them — see [Where the debounce
lives](./index.md#where-the-debounce-lives). Do not add a timer around the
text field.
---
## Flutter
Exported from a separate entry point so a non-Flutter Dart app never pulls in
the widget layer:
```dart
import 'package:mapatlas_geocoder/ui.dart';
```
### `MapAtlasSearchField`
The complete search box.
```dart
MapAtlasSearchField(
client: _client,
country: 'nl',
proximity: kAmsterdam,
hintText: 'Search a place in the Netherlands…',
onPlaceSelected: (place, label) {
setState(() { _place = place; _label = label; });
},
)
```
`client` and `onPlaceSelected` are required. Notable optional parameters:
`country`, `proximity`, `minLength` (`2`), `hintText`, `decoration`, `theme`,
`rowBuilder`, `deduplicate`, `labelBuilder`, `store`, `historyLimit` (`8`),
`favouritesLimit` (`20`), `showHistory` / `showFavourites` (both `true`),
`categories`, `onCategorySearch`, `textController`, `focusNode`, `autofocus`.
```dart
typedef MapAtlasPlaceSelected =
FutureOr Function(RetrievedPlace place, String label);
```
### `MapAtlasSearchAnchor`
Bring-your-own-markup. Same options, plus `rememberSelections`; instead of
rendering a field it hands a `MapAtlasSearchScope` to your builder:
```dart
MapAtlasSearchAnchor(
client: _client,
onPlaceSelected: (place, label) { /* … */ },
builder: (context, scope) {
// scope.rows, scope.isLoading, scope.error, scope.setQuery(…),
// scope.select(row), scope.highlightNext(), scope.toggleFavourite(row) …
return MyOwnSearchLayout(scope: scope);
},
)
```
Wrap your layout in `MapAtlasSearchShortcuts(scope: scope, child: …)` to get
Arrow Up/Down, Enter and Escape bound to the scope for free.
### Other exports
`MapAtlasSearchRow` / `MapAtlasSearchRowKind`, `SavedPlace`,
`MapAtlasSearchStore` (+ `SharedPreferencesSearchStore`,
`InMemorySearchStore`), `MapAtlasSearchTheme` / `MapAtlasSearchThemeScope`,
`MapAtlasSearchCategory` + `categoryQueryText`, `uniquifyRowIds`,
`defaultDeduplicateSuggestions` / `noDeduplication` / `suggestionIdentity`.
`MapAtlasSearchTheme` covers colours (`surfaceColor`, `onSurfaceColor`,
`mutedColor`, `errorColor`, `highlightColor`, `accentColor`, `dividerColor`),
`borderRadius`, `elevation`, three text styles, `maxListHeight` (`320`),
`rowMinHeight` (`48`, floored at 44 for touch targets) and `contentPadding`.
---
## Swift
A **separate product** in the same package, so the core client stays usable
below iOS 17:
```swift
.product(name: "MapAtlasGeocoderUI", package: "Swift"),
```
::: warning Requires macOS 14 / iOS 17
The package manifest declares iOS 15 — SwiftPM has no per-target platform, so
that floor applies to every target. Everything in `MapAtlasGeocoderUI` is
annotated `@available(macOS 14, iOS 17, *)` because it is built on
`@Observable`. The manifest's iOS 15 is not a promise that this product runs
there. See [Platform floors](./swift.md#platform-floors).
:::
```swift
import MapAtlasGeocoderUI
MapAtlasSearchField(
client: client,
country: "nl",
proximity: proximity,
configuration: MapAtlasSearchConfiguration()
) { place, label in
selectedPlace = place
selectedLabel = label
}
```
`MapAtlasSearchConfiguration` holds the tuning knobs, all with defaults:
`placeholder`, `minLength` (`2`), `deduplicate`, `showsHistory`,
`showsFavourites`, `allowsFavouriting`, `historyLimit` (`10`), `store`,
`categories`, `categorySearch`, `clearsQueryOnSelect`,
`recordsSelectionsInHistory`.
There are four initialisers: the `onPlaceSelected` form above; an `onSelect`
form receiving a richer `MapAtlasSearchSelection`; a form taking a
pre-built `MapAtlasSearchModel`; and a `@ViewBuilder rowContent` form for
custom row rendering.
`MapAtlasSearchModel` is the `@Observable` state object — construct one
yourself (`try MapAtlasSearchModel(client:country:proximity:configuration:)`)
when you need to drive the search from outside the view.
Theme via the environment:
```swift
MapAtlasSearchField(client: client) { place, label in /* … */ }
.mapAtlasSearchTheme(.system)
```
Category chips use SF Symbols (`fork.knife`, `fuelpump.fill`,
`bed.double.fill`, `parkingsign.circle.fill`, `cup.and.saucer.fill`,
`cart.fill`).
---
## Kotlin / Android
A **new Gradle module**, separate from the pure-JVM core so a server-side JVM
consumer never pulls in Compose:
```kotlin
implementation("net.mapmetrics:mapatlas-geocoder-ui:1.0.0") // brings the core in transitively
```
Compose + Material 3, `minSdk 24`, `compileSdk 35`, Compose BOM
`2024.12.01`. Persistence uses Preferences DataStore.
```kotlin
val client = remember(tier) { MapAtlas(token = TOKEN, tier = tier) }
DisposableEffect(client) { onDispose { client.close() } }
val anchor = rememberMapAtlasSearchAnchor(
client = client,
options = MapAtlasSearchOptions(country = "nl"),
)
MapAtlasSearchField(
anchor = anchor,
onPlaceSelected = { place, label -> selected = place to label },
)
```
`rememberMapAtlasSearchAnchor` wires the DataStore-backed store, picks the
right engine for the client's tier, and disposes the anchor for you. Its
parameters: `client`, `options`, `deduplicate`, `minLength` (`2`),
`maxHistoryEntries` (`10`), `categories`, `categorySearch`, `initialQuery`.
`MapAtlasSearchField` takes `anchor`, `onPlaceSelected`, plus `modifier`,
`strings`, `theme`, `showCategoryChips` (`true`) and an optional `rowContent`
lambda scoped to `MapAtlasSearchScope`.
Lower-level composables are public too, so you can assemble your own layout:
`MapAtlasSearchTextField`, `MapAtlasSearchPanel`, `MapAtlasSearchRowItem`,
`MapAtlasCategoryChips`, and the `MapAtlasSearchTheme` provider.
`MapAtlasSearchAnchor` exposes `state: StateFlow` and
suspending `select`, `toggleFavourite`, `removeFromHistory`, `clearHistory`
— usable directly from a `ViewModel`.
All user-visible strings come from `mapatlas_search_*` string resources via
`rememberMapAtlasSearchStrings()`, so they localise with your app.
::: tip No desugaring needed
This module and the core client use only APIs present in `android.jar`. If
you are carrying `coreLibraryDesugaring` purely for this SDK, you can drop
it — see [the Kotlin page](./kotlin.md#install).
:::
---
## React
Exported from the existing `react` subpath, alongside `useAutocomplete`:
```tsx
import { SearchBox } from '@mapmetrics/geocoder/react';
import '@mapmetrics/geocoder/react/styles.css';
```
The stylesheet is **opt-in** — import it for the default look, or skip it and
style via `classNames`. `react` (>=18) stays an optional peer dependency; the
core entry point never pulls React into your bundle.
### ``
```tsx
const client = useMemo(() => new MapAtlas({ token: TOKEN }), []);
const [place, setPlace] = useState(null);
setPlace(p)}
onError={(error) => console.error(error.name, error.message)}
/>
```
Only `client` is required. It accepts every `useSearchBox` option plus
presentation props: `placeholder`, `className`, `classNames`, `id`, `name`,
`required`, `disabled`, `showClearButton`, `showPinButton`, `emptyMessage`,
`loadingMessage`, and `renderOption` / `renderError` / `renderEmpty` /
`renderPopover` escape hatches.
`classNames` is a per-element map (`root`, `input`, `popover`, `listbox`,
`option`, `optionActive`, `category`, `categoryActive`, `sectionHeader`, …)
for Tailwind or CSS-modules styling without fighting the default stylesheet.
### ``
Wraps your **own existing form fields** rather than rendering a field. It
attaches to the input inside it and fills the surrounding form on selection:
```tsx
{ /* … */ }}>
```
`onRetrieve` receives the resolved `place`, a normalised `components` object
(`addressLine1`, `city`, `region`, `postcode`, `countryCode`, `street`,
`houseNumber`, …) and the `filled` map it applied.
### `useSearchBox`
The headless hook behind both components, when you want the behaviour and
none of the markup. It returns state (`query`, `rows`, `mode`, `isLoading`,
`error`, `isOpen`, `activeIndex`, `selected`, `categories`, `activeCategory`),
actions (`setQuery`, `select`, `clear`, `open`, `close`, `toggleFavourite`,
`selectCategory`), the `history` / `favourites` sub-stores, and three
ready-made ARIA prop bags:
```tsx
const search = useSearchBox({ client, country: 'nl' });
// role=listbox
{search.rows.map((row, i) => (
{rowLabel(row)}
))}
```
Spreading those three keeps the combobox accessible without you hand-writing
the ARIA relationships.
Also exported: `useSearchHistory`, `useFavourites`, `createLocalStorageStore`,
`DEFAULT_CATEGORIES`, `defaultDeduplicate` / `noDeduplication` /
`deduplicateBy`, `rowIdentity`, `rowLabel`, `uniquifyRows`, and the
`SearchRow` / `SavedPlace` / `SelectedPlace` types.
---
## See also
- [Geocoding SDKs](./index.md) — the shared model and the sharp edges this layer hides.
- [Autocomplete (v2)](/overview/geocoder/v2/autocomplete) — including why `id` can't be a key and why `category=` does nothing.
- [Category Search (v2)](/overview/geocoder/v2/category) — the endpoint to wire `categorySearch` to.
- [OSM tier](/overview/geocoder/osm) — the free tier these components also support.
---
# Sessions & Billing
https://docs.mapatlas.xyz/overview/sdk/geocoding/sessions
# Sessions & Billing
All four geocoding SDKs are built around one billing model: the
[v2 autocomplete API](../../geocoder/v2/autocomplete.md) bills by **session**,
not by request. This page is the shared reference the per-language pages
link back to — see [Sessions (v2 Autocomplete Billing)](../../geocoder/v2/sessions.md)
for the underlying HTTP-level rules this section builds on.
## The rule
A session starts on the first `suggest()` call on a fresh session object,
and ends — closing the session — on either `retrieve()` or `retrieveBatch()`.
The next `suggest()` call after that automatically opens a new session. You
never see or manage the `session_token` yourself; every SDK mints, reuses,
and rotates it for you.
## What a session costs
Measured against the gateway (one token, counting session starts):
| sequence | sessions billed |
|---|---|
| 3 `suggest()` calls on one session | **1** |
| `suggest()` → `retrieve()` → `suggest()` | **2** |
| `suggest()` → `retrieveBatch()` → `suggest()` | **2** |
Two consequences follow directly from this table:
**Resolving picks one at a time is expensive.** Three sequential
`retrieve()` calls on three different suggestions cost **three sessions**,
because each `retrieve()` both closes the session it belongs to and — if
none is open — starts one. One `retrieveBatch()` of the same three
suggestions costs **one session**. If you're resolving more than one result
at a time — plotting a set of markers, say — always prefer the batch call.
**Omitting a stable session token costs roughly 5x.** If nothing carries a
consistent token across a search, the gateway mints a fresh session for
every single keystroke instead of one session covering the whole search.
For a typical multi-character search this multiplies cost by roughly 5x.
This is exactly the mistake the SDKs exist to prevent — a hand-rolled
`fetch`/`URLSession` call that constructs a new session (or omits
`session_token` entirely) per keystroke will hit this without any error or
warning; the gateway returns HTTP 200 every time.
## How each SDK prevents it
Every SDK ties one session object to the lifetime of one search-box
interaction:
- **JavaScript/TypeScript** — `client.geocoding.createSession()` returns a
`Session` that owns the token; `select()`/`retrieve()`/`retrieveBatch()`
close it and the next `suggest()` reopens one automatically. The
`useAutocomplete` hook owns one `Session` per component instance.
- **Dart/Flutter** — `mapatlas.geocoding.createSession()` returns a
`GeocodeSession` with the same lifecycle. `GeocodeSearchController`
creates exactly one `GeocodeSession` in its constructor and reuses it for
the controller's whole lifetime.
- **Swift** — `mapatlas.geocoding.createSession()` returns a `Session`.
`GeocodeSearchController` creates one for its lifetime as an `@Observable`
controller.
- **Kotlin** — `mapatlas.geocoding.createSession()` returns a `Session`.
`GeocodeSearchController` owns one internally and exposes it only through
`StateFlow`.
In all four, constructing a **new** session object per keystroke — e.g.
calling `createSession()` inside a text-change handler instead of once, up
front — reintroduces the roughly-5x cost the SDK is meant to prevent. The
reactive controllers exist specifically so you never have to think about
this: bind the controller to the lifetime of the search field, not the
keystroke.
## Retrievability
Not every suggestion can be resolved. The gateway injects locality rows
(e.g. two of the fifteen results for `q=Amsterdam`) alongside ordinary
results; those rows are shown in the suggestion list but carry no `ord`, so
they can't be retrieved. Every SDK exposes an `isRetrievable` check on the
suggestion — use it to disable or filter those rows before the user can tap
one. See the error-handling section of each language page for what happens
if you call `retrieve()` on a non-retrievable suggestion anyway.
## See Also
- [Autocomplete (v2)](../../geocoder/v2/autocomplete.md)
- [Retrieve (v2)](../../geocoder/v2/retrieve.md)
- [Sessions (v2 HTTP billing model)](../../geocoder/v2/sessions.md)
- [API Keys & Security](../../api-keys.md)
---
# Swift SDK
https://docs.mapatlas.xyz/overview/sdk/geocoding/swift
# Swift SDK
`MapAtlasGeocoder` is a Swift client for the
[v2 geocoding API](../../geocoder/v2/autocomplete.md) — autocomplete, place
retrieval, and forward/reverse geocoding — for iOS and macOS. Foundation
only, no third-party dependencies, `async`/`await` throughout.
::: warning Not published yet
Not on the Swift Package Index yet. Add it as a git-based Swift Package
today — see below; the coordinates don't change once it's indexed.
:::
## Install
**Platforms:** macOS 12+, iOS 15+ for `MapAtlasGeocoder`.
The optional [`MapAtlasGeocoderUI`](./search-ui.md) product needs
macOS 14 / iOS 17 — see [Platform floors](#platform-floors) below.
::: danger You cannot add this by URL yet
`geocoder-sdk` is a **monorepo with no root `Package.swift`** — the manifest
lives at `Swift/Package.swift`. SwiftPM only ever looks at the repository
root and has no way to target a subdirectory of a remote repository, so both
of these fail:
```swift
// ❌ "package at 'https://github.com/MapMetrics/geocoder-sdk' has no Package.swift"
.package(url: "https://github.com/MapMetrics/geocoder-sdk", branch: "main"),
// ❌ worse: resolves, and silently gives you no Swift package at all.
.package(url: "https://github.com/MapMetrics/geocoder-sdk", from: "1.0.0"),
```
The second is the nastier one. The repository's only tag, `v1.0.0`, predates
the Swift package entirely — that tree contains `Flutter/`, `NPM/` and
`openapi/` and **no `Swift/` directory**. Pinning it does not error in a way
that points at the cause.
Xcode's *File → Add Package Dependencies…* has the same limitation: there is
no "select a subdirectory" step to perform, despite what this page previously
said.
:::
Until the Swift package is split out or indexed, depend on it **by path**.
### Xcode
Clone the repository, then *File → Add Package Dependencies… → Add Local…*
and select the **`Swift/` directory** (the folder containing `Package.swift`),
not the repository root. Add the **MapAtlasGeocoder** product to your target.
### Package.swift
```swift
dependencies: [
.package(path: "../Geocoder-SDK/Swift"),
],
targets: [
.target(
name: "YourTarget",
dependencies: [
.product(name: "MapAtlasGeocoder", package: "Swift"),
// Optional drop-in search UI — see ./search-ui.md
.product(name: "MapAtlasGeocoderUI", package: "Swift"),
]
),
]
```
With a path dependency the `package:` label is the directory name (`Swift`),
not the repository name. Once the package is published under its own
repository the `.package(url:from:)` form will work and `package:` becomes
the repository name again.
### Platform floors
The package declares `platforms: [.macOS(.v12), .iOS(.v15)]`, and SwiftPM
applies that to **every** target — there is no per-target platform in SPM.
The newer pieces gate themselves with `@available` instead:
| Symbol | Available from |
|---|---|
| `MapAtlas`, `Session`, `Suggestion`, `MapAtlasError` | macOS 12 / iOS 15 |
| `GeocodeSearchController` (`@Observable`) | **macOS 14 / iOS 17** |
| Everything in `MapAtlasGeocoderUI` | **macOS 14 / iOS 17** |
So the manifest advertising iOS 15 does not mean `GeocodeSearchController`
is usable there — `@Observable` requires iOS 17, and the type is annotated
accordingly. Wrap uses in `if #available(iOS 17, *)`, or raise your
deployment target.
## Quickstart
```swift
import MapAtlasGeocoder
let mapatlas = MapAtlas(token: "YOUR_API_KEY")
// One session covers a whole search — every keystroke, then the pick.
let session = try mapatlas.geocoding.createSession()
// As the user types. Debounced inside the client (see below); suggestions
// carry no coordinates.
let results = try await session.suggest("Nieuwezijds")
// When they pick one, hand back the suggestion — not an id.
let place = try await session.retrieve(results[0])
print(place.latitude, place.longitude)
// Resolving several at once is both fewer round trips and cheaper billing —
// see Sessions & Billing.
let places = try await session.retrieveBatch(Array(results.prefix(3)))
// One-shot lookups, when there's no user typing to debounce. Both return GeoJSON.
let forward = try await mapatlas.geocoding.search("Nieuwezijds Voorburgwal 147", country: "nl")
let reverse = try await mapatlas.geocoding.reverse(lat: 52.37, lon: 4.89)
```
## The reactive layer: `GeocodeSearchController`
`GeocodeSearchController` is a headless, `@Observable`, `@MainActor`
controller — bind your own markup to it. Requires macOS 14 / iOS 17 (the
rest of the package works down to macOS 12 / iOS 15 — `@Observable` alone
needs the newer OS; see [Platform floors](#platform-floors)).
If you want the list, keyboard handling, history, favourites and category
chips built for you rather than binding your own markup, use the
[`MapAtlasGeocoderUI`](./search-ui.md) product instead — this controller is
the headless layer underneath it.
```swift
import SwiftUI
import MapAtlasGeocoder
struct AddressField: View {
@State private var controller: GeocodeSearchController
var onSelect: (RetrievedPlace) -> Void
init(client: MapAtlas, onSelect: @escaping (RetrievedPlace) -> Void) {
_controller = State(initialValue: try! GeocodeSearchController(client: client, country: "nl"))
self.onSelect = onSelect
}
var body: some View {
VStack(alignment: .leading, spacing: 8) {
TextField("Search an address…", text: $controller.query)
.textFieldStyle(.roundedBorder)
if controller.isLoading {
ProgressView()
}
if let error = controller.error {
Text(error.message).foregroundStyle(.red).font(.caption)
}
List(controller.suggestions, id: \.text) { suggestion in
Button(suggestion.placeName ?? suggestion.text ?? "") {
Task {
if let place = await controller.select(suggestion) {
onSelect(place)
}
}
}
// Suggestions can be non-retrievable (e.g. a bare "Amsterdam"
// locality row) — still shown, but selecting one surfaces
// `.notRetrievable` into `controller.error` instead of a crash.
.disabled(!suggestion.isRetrievable)
}
}
}
}
```
**Guarantees:** one `Session` is created for the controller's lifetime and
reused across every keystroke; `select(_:)` retrieves and closes it, and the
next `query` change reopens it automatically. `minLength` (default `2`) is
enforced locally — no request, no session activity, below it. Out-of-order
responses are discarded: each search is tagged with a sequence number, and a
slow response for an earlier keystroke arriving after a newer one is never
applied. Errors land in `controller.error`, never thrown into a view.
::: warning Where the debounce actually lives
The controller does **not** debounce. Coalescing happens one layer down, in
`Session.suggest()` inside the client — configured by `MapAtlas(debounceMs:)`,
default `150`. Do not wrap `controller.query` in a second timer; stacking one
on top of the client's only adds lag. If 150 ms is wrong for you, change
`debounceMs` on the client.
**One exception:** the `.osm` tier has no `Session`, so nothing downstream
coalesces and the controller debounces there itself, using the same value.
:::
::: danger Don't use `\.text` or `id` as a SwiftUI list identity
The `List(controller.suggestions, id: \.text)` above is illustrative but
fragile — `text` repeats across rows (two `"Amsterdam"` entries for
`q=amsterdam`), and the gateway's own `id` field repeats too (two rows share
`"place.0"`). Duplicate SwiftUI identities cause rows to reuse each other's
state rather than crashing, so this misbehaves quietly. Prefer
`MapAtlasGeocoderUI`, whose `MapAtlasSearchRow` carries an id already
de-collided for you.
:::
## The OSM tier
`tier: .osm` talks to the free, OpenStreetMap-only endpoints
(`/osm-geocode/`, `/osm-reverse/`, `/osm-autocomplete/`) via the
`osm-geocode` scope. No session/retrieve flow — `search()`, `reverse()`,
and `autocomplete(_:)` are the only three operations. Calling
`createSession()` on this tier throws `.tierUnsupported`. Rate-limited to
10,000 requests/key/day plus a global monthly cap; exhausting it throws
`.quotaExceeded` with a `selfHostURL`.
```swift
let mapatlas = MapAtlas(token: "YOUR_KEY", tier: .osm)
let result = try await mapatlas.geocoding.search("Nieuwezijds Voorburgwal 147")
if case .osm(let raw) = result {
// raw: OsmResponse (= JSONValue) — narrow it yourself at the call site.
}
```
`autocomplete(_:)` on this tier is the opposite of v2 autocomplete: no
session, no `retrieve()` step, results already carry coordinates. It's only
available with `tier: .osm` — on the default `.v2` tier it throws
`.tierUnsupported` and points you at `createSession()` + `suggest(_:)`
instead.
### Self-hosting
The free tier's engine is open source:
[MapMetrics/atlas-osm-geocoder](https://github.com/MapMetrics/atlas-osm-geocoder),
deployable on Cloudflare Workers with a prebuilt planet bundle. Point this
package at your own instance with `MapAtlas.selfHosted(baseURL:)`:
```swift
let mapatlas = MapAtlas.selfHosted(baseURL: URL(string: "https://my-worker.workers.dev")!)
try await mapatlas.geocoding.search("Nieuwezijds Voorburgwal 147")
try await mapatlas.geocoding.autocomplete("Nieuwezijds")
try await mapatlas.geocoding.reverse(lat: 52.37, lon: 4.89)
```
A self-hosted instance takes no token and uses different paths (`/search`,
`/reverse`, `/autocomplete`, no `token` parameter) — there is no
`token`/`getToken` option on this constructor at all, since a self-hosted
instance has no auth and this package never sends one. `createSession()`
(and session-based retrieval) throw `.tierUnsupported` here too — this
engine has no session concept at all.
## Choosing a key for a Swift app
Origin restriction is a **browser-only** feature — it's enforced by
checking the `Origin` header a browser sends, and native apps never send
one. **A native app can never satisfy an origin-restricted key** — this is
the error you'll hit if you reuse a browser-restricted key in an iOS app.
Use an unrestricted key for iOS/macOS instead. See
[API Keys & Security](../../api-keys.md) for the full model.
## Errors
`MapAtlasError` is a Swift `enum` with one case per failure mode. Switch on
it, or read `.message` / `.status` / `.code` / `.name`:
- `.tokenNotFound` — key was never provisioned.
- `.tokenInactive` — key exists but is deactivated.
- `.scopeNotAllowed` — key is valid but not scoped for this operation.
- `.originRequired` — key is origin-restricted, no `Origin` header sent.
See [Choosing a key for a Swift app](#choosing-a-key-for-a-swift-app).
- `.originNotAllowed` — request's `Origin` isn't on the key's allow-list.
- `.quotaExceeded` — OSM tier cap exhausted; carries `selfHostURL`.
- `.tierUnsupported` — thrown by `createSession()` on the `.osm` tier and on
`MapAtlas.selfHosted(baseURL:)` clients, and by `autocomplete(_:)` on the
`.v2` tier.
- `.notRetrievable` — thrown by `retrieve(_:)`/`retrieveBatch(_:)` when a
`Suggestion` has no `ord` (`isRetrievable == false`).
- `.network` — the request never completed, or the response wasn't
parseable JSON.
- `.decoding` — the response was valid JSON but didn't match the expected
shape.
- `.unknown` — any other non-2xx response, not covered above.
```swift
import MapAtlasGeocoder
do {
_ = try await mapatlas.geocoding.search("Nieuwezijds Voorburgwal 147", country: "nl")
} catch let error as MapAtlasError {
switch error {
case .originRequired:
// this key can't be used from a native app — swap it for an unrestricted one
break
case .quotaExceeded(_, _, _, let selfHostURL):
print("quota exceeded, self-host at:", selfHostURL as Any)
default:
print(error.name, error.message)
}
}
```
## Not implemented yet
This package covers geocoding only — routing, matrix, map matching,
optimization, and isochrones are **not** implemented here. The TypeScript
and Dart SDKs cover those endpoints; see [JavaScript](./javascript.md) or
[Flutter](./flutter.md) if you need routing from a shared backend or a
cross-platform Dart layer.
## Endpoint reference
This SDK is a typed wrapper — for the full parameter list, response shape,
and gateway-level gotchas each call is protecting you from, see:
- [Autocomplete (v2)](../../geocoder/v2/autocomplete.md)
- [Retrieve (v2)](../../geocoder/v2/retrieve.md)
- [Forward Geocode (v2)](../../geocoder/v2/forwardgeocode.md)
- [Reverse Geocode (v2)](../../geocoder/v2/reversegeocode.md)
- [Sessions & Billing](./sessions.md)
- [API Keys & Security](../../api-keys.md)
---
# Custom Protocols
https://docs.mapatlas.xyz/overview/sdk/guides/custom-protocols
---
title: "Custom Protocols"
description: "Register custom URL schemes for sources with addProtocol, e.g. for PMTiles"
---
# Custom Protocols
`addProtocol` lets you hook a custom URL scheme (`pmtiles://`, `custom://`,
anything before `://`) so that any source in your style referencing that
scheme is routed through your own loader function instead of a normal HTTP
fetch. This is how PMTiles support is wired in: no scheme-specific code
lives in the map itself, a protocol handler supplies the bytes.
## Registering a protocol
```js
mapmetricsgl.addProtocol('custom', async (params, abortController) => {
const response = await fetch(`https://${params.url.split('://')[1]}`);
if (response.status === 200) {
const buffer = await response.arrayBuffer();
return { data: buffer };
}
throw new Error(`Tile fetch error: ${response.statusText}`);
});
```
Use it in a style source with the matching scheme:
```js
map.addSource('custom-source', {
type: 'vector',
tiles: ['custom://example.com/tiles/{z}/{x}/{y}.pbf'],
});
```
### PMTiles example
The typical use case is serving a single `.pmtiles` archive without a tile
server. A PMTiles-aware loader receives the request, resolves it against the
archive, and returns the tile bytes:
```js
import { PMTiles, Protocol } from 'pmtiles';
const protocol = new Protocol();
mapmetricsgl.addProtocol('pmtiles', protocol.tile);
const p = new PMTiles('https://example.com/data.pmtiles');
protocol.add(p);
map.addSource('pmtiles-source', {
type: 'vector',
url: 'pmtiles://https://example.com/data.pmtiles',
});
```
## The callback contract
```ts
addProtocol(
customProtocol: string,
loadFn: (
requestParameters: RequestParameters,
abortController: AbortController
) => Promise>
): void
```
**Receives:**
- `requestParameters.url` — the full URL from the source (including the
custom scheme), plus optional `headers`, `method`, `body`, `type`
(`'string' | 'json' | 'arrayBuffer' | 'image'`), `credentials`, and
`cache`.
- `abortController` — an `AbortController` you should respect if the
request is cancelled (e.g. the tile scrolls out of view before it
finishes loading).
**Must return** a `Promise` resolving to `{ data, cacheControl?, expires? }`
— `data` is the resource itself (an `ArrayBuffer` for vector/raster tiles,
parsed JSON for a style/TileJSON, etc.), and `cacheControl`/`expires` are
optional cache metadata.
**On failure**, reject the promise or throw — the caller (`addProtocol`'s
built-in error path) treats a thrown error as a failed resource load, the
same as an HTTP error status would be.
## Removing a protocol
```js
mapmetricsgl.removeProtocol('custom');
```
## Advanced: custom source types
`addSourceType(name, SourceClass)` goes a step further than `addProtocol` —
instead of hooking a URL scheme, it registers an entirely custom `Source`
implementation under a new source `type`. It exists in the SDK, but it's a
low-level extension point (you implement the full `Source` interface
yourself); for anything that's really "fetch bytes for this URL scheme",
`addProtocol` is what you want.
---
# Globe Projection
https://docs.mapatlas.xyz/overview/sdk/guides/globe
---
title: "Globe Projection"
description: "Render the map as a 3D globe and add the GlobeControl toggle button"
---
# Globe Projection
MapMetrics GL can render the same vector tiles either as a flat Mercator map
or as a 3D globe. The globe draws the exact same polygons, lines and
symbols — no separate globe-only data is needed — and smoothly transitions
back to Mercator as you zoom in.
## Enabling globe
Set the projection on the map:
```js
const map = new mapmetricsgl.Map({
container: 'map',
style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
center: [0, 20],
zoom: 1.5,
});
map.setProjection({ type: 'globe' });
```
Read the current projection with:
```js
map.getProjection(); // { type: 'globe' } or { type: 'mercator' }
```
Switch back with `map.setProjection({ type: 'mercator' })`.
## Adding the toggle control
`GlobeControl` gives users a button that flips between `mercator` and
`globe`:
```js
map.addControl(new mapmetricsgl.GlobeControl());
```
The control watches the map's `styledata` event and updates its own icon
(`mapmetricsgl-ctrl-globe` / `mapmetricsgl-ctrl-globe-enabled`) to reflect
whichever projection is currently active — including changes made
programmatically via `setProjection`, not just clicks on the button itself.
## Behavior and limitations
- **Automatic Mercator fallback at high zoom.** Globe projection is only
used up to roughly zoom level 12; above that the map transitions smoothly
(and imperceptibly) to Mercator. This is a precision limitation, not a
toggle you control.
- **Terrain, pitch, and camera animations** (`flyTo`, `easeTo`) all work
under globe — panning and zooming keep the cursor's location fixed on the
sphere, the same way Mercator zooming keeps it fixed on the plane.
- **No center constraining.** Globe transform does not currently support
constraining the map's center the way Mercator does.
- **Poles.** The camera can't move directly across a pole to the opposite
hemisphere; MapMetrics GL rotates around instead of cutting through, so
zooming into a point "behind" a pole uses an approximation rather than an
exact zoom path.
- At very low zooms near the edge of the visible globe, cursor-anchored
zooming is faded out in favor of an approximation, to avoid rapid,
unpleasant panning.
---
# RTL Text (Arabic, Hebrew, Persian, Urdu)
https://docs.mapatlas.xyz/overview/sdk/guides/rtl-text
---
title: "RTL Text (Arabic, Hebrew, Persian, Urdu)"
description: "Enable correct shaping and direction for right-to-left scripts with setRTLTextPlugin"
---
# RTL Text
MapMetrics GL renders label text with a general-purpose text shaper. On its
own, that shaper does not perform the glyph joining/reordering that Arabic,
Hebrew, Persian and Urdu need. Without the RTL plugin, labels in those
scripts render as **disconnected, incorrectly-ordered characters** — and the
map does **not throw an error**. Nothing in the console tells you this is
happening; the map just looks wrong for a subset of your users.
If your map (or your users' input) can contain Arabic, Hebrew, Persian or
Urdu text, load the RTL plugin before you create the `Map`.
## Loading the plugin
::: tip The plugin ships separately from the SDK
The SDK bundle contains the *loader*, not the plugin itself — you always pass a
URL. MapMetrics hosts a ready-to-use build on its CDN, so you don't need to
supply your own:
`https://cdn.mapmetrics-atlas.net/basemaps-assets/js/mapmetrics-gl-rtl-text.min.js`
If your deployment can't reach that CDN (an air-gapped network, or a strict
`worker-src`/CSP allowlist), copy that build to your own origin and point
`setRTLTextPlugin` at your copy instead.
:::
```js
mapmetricsgl.setRTLTextPlugin(
'https://cdn.mapmetrics-atlas.net/basemaps-assets/js/mapmetrics-gl-rtl-text.min.js',
false // lazy
);
const map = new mapmetricsgl.Map({
container: 'map',
style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
center: [0, 0],
zoom: 2,
});
```
`setRTLTextPlugin(url, lazy)`:
- `url` — where to fetch the plugin script from. It's loaded from a worker
via `importScripts`, so it must be reachable from your page (a plugin
bundle hosted on a CDN, or one you serve yourself).
- `lazy` — if `false` (or omitted), the plugin is fetched and initialized
immediately. If `true`, loading is deferred until the map actually
encounters a tile that needs RTL shaping.
Call it **once**, before you create your first `Map` instance. Calling it a
second time throws `setRTLTextPlugin cannot be called multiple times.`
## Checking status
```js
mapmetricsgl.getRTLTextPluginStatus();
// 'unavailable' | 'deferred' | 'requested' | 'loading' | 'loaded' | 'error'
```
The statuses:
| Status | Meaning |
|---|---|
| `unavailable` | Not loaded, and `setRTLTextPlugin` hasn't been called. |
| `deferred` | URL is registered, but loading was deferred (`lazy: true`) and hasn't been triggered yet. |
| `requested` | A tile needed RTL shaping before the plugin was set. |
| `loading` | The worker is fetching/initializing the plugin. |
| `loaded` | Ready — RTL scripts will shape correctly. |
| `error` | The plugin failed to load (bad URL, network failure, etc.). |
## Why "lazy" exists
If most of your users never see RTL text, set `lazy: true` so the extra
script isn't fetched on every page load — it's pulled in only the first time
a tile actually needs it. If you know your map will regularly show Arabic,
Hebrew, Persian or Urdu labels, pass `false` so shaping is correct from the
very first render.
---
# SDKs & Softwares
https://docs.mapatlas.xyz/overview/sdk/
# SDKs & Softwares
## Integrating Maps in your project
MapMetrics exposes Vector Tile APIs to work with maps. To display maps, you need to use a Maps SDK.
There are already great OpenSource Maps SDKs, and we'd rather spend our nights optimizing rendering efficiency to give you the fastest maps on the market than putting our name on a brand new Maps SDK which would pretty much do the same as the others.
### Vector Tiles
Vector tiles were created after the raster tiles. These are also squares, which together form a map. This time, these squares only contain the data, so you have to associate a style to it to finally have a map. This allows for more personalization and better interactions with the map.
We would recommend using MapMetrics GL for vector tiles.
# Attribution
Your map must display the following links: © MapMetrics and © OSM contributors. This is a part or our General Terms and Conditions (5.6 Attribution Requirements).
This is our attribution template:
```html
© MapMetrics
|
© OSM contributors
```
---
# Action Journal
https://docs.mapatlas.xyz/overview/sdk/ios-native/ActionJournalExample
# Action Journal
Learn about the `MLNMapView` methods for logging and viewing map actions.
The Action Journal provides functionality for persistent logging of top level map events.
Its primary use case is to assist in debugging problematic sessions and crashes by offering additional insight into the actions performed by the map at the time of failure. Data is stored in human readable format, which is useful for analyzing individual cases, but can also be easily translated and aggregated into a database, allowing for efficient analysis of multiple cases and helping to identify recurring patterns (Google BigQuery, AWS Glue + S3 + Athena, etc).
We are always interested in improving observability, so if you have a special use case, feel free to open an issue or pull request to extend the types of observability methods.
## Logging implementation details
The logging is implemented using rolling files with a size based policy:
- A new file is created when the current log size exceeds `MLNActionJournalOptions.logFileSize`.
- When the maximum number of files exceeds `MLNActionJournalOptions.logFileCount`:
- The oldest one is deleted.
- The remaining files are renamed sequentially to maintain the naming convention `action_journal.0.log` through `action_journal.{logFileCount - 1}.log`.
- Each file contains one event per line.
- All files are stored in an umbrella "action_journal" directory at `MLNActionJournalOptions.path`.
See also: `MLNSettings`, `MLNActionJournalOptions`.
## Event format
Events are stored as JSON objects with the following format:
| Field | Type | Required | Description |
| :---- | :--: | :------: | :---------- |
| name | string | true | event name |
| time | string | true | event time ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) with milliseconds) |
| styleName | string | false | currently loaded style name |
| styleURL | string | false | currently loaded style URL |
| clientName | string | false | |
| clientVersion | string | false | |
| event | object | false | event specific data - consists of encoded values of the parameters passed to their `MLNMapViewDelegate` counterparts
```
{
"name" : "onTileAction",
"time" : "2025-04-17T13:13:13.974Z",
"styleName" : "Streets",
"styleURL" : "maptiler://maps/streets",
"clientName" : "App",
"clientVersion" : "1.0",
"event" : {
"action" : "RequestedFromNetwork",
"tileX" : 0,
"tileY" : 0,
"tileZ" : 0,
"overscaledZ" : 0,
"sourceID" : "openmaptiles"
}
}
```
## Usage
Enabling the action journal.
```swift
let options = MLNMapOptions()
options.actionJournalOptions.enabled = true
options.styleURL = MAP_STYLE
mapView = MLNMapView(frame: view.bounds, options: options)
```
```swift
@objc func printActionJournal() {
print("ActionJournalLog files: \(mapView.getActionJournalLogFiles())")
print("ActionJournalLog : \(mapView.getActionJournalLog())")
// print only the newest events on each call
mapView.clearActionJournalLog()
}
```
## Alternative
The implementation is kept close to the core events to minimize additional locking and avoid platform-specific conversions and calls. As a result customization options and extensibility is limited.
For greater flexibility, consider using the `MLNMapViewDelegate` interface. It provides hooks for most Action Journal events and allows for more customizable querying and storage of map data. However, this comes at the cost of added complexity. See [Observe Low-Level Events](./ObserverExample.md) to learn about the map events that you can listen for, which mirror the events available in the action journal.
---
# Animated Line
https://docs.mapatlas.xyz/overview/sdk/ios-native/AnimatedLineExample
# Animated Line
Add an animated line to a map
> This example uses UIKit.
Demonstrates using `MLNPolyline.polylineWithCoordinates:count:` to update an `MLNPolyline`.
```swift
class AnimatedLineExample: UIViewController, MLNMapViewDelegate {
var mapView: MLNMapView!
var timer: Timer?
var polylineSource: MLNShapeSource?
var currentIndex = 1
var allCoordinates: [CLLocationCoordinate2D]!
override func viewDidLoad() {
super.viewDidLoad()
mapView = MLNMapView(frame: view.bounds, styleURL: MAP_STYLE)
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
mapView.setCenter(
CLLocationCoordinate2D(latitude: 45.5076, longitude: -122.6736),
zoomLevel: 11,
animated: false
)
view.addSubview(mapView)
mapView.delegate = self
allCoordinates = coordinates
}
// Wait until the map is loaded before adding to the map.
func mapViewDidFinishLoadingMap(_ mapView: MLNMapView) {
addPolyline(to: mapView.style!)
animatePolyline()
}
func addPolyline(to style: MLNStyle) {
// Add an empty MLNShapeSource, we'll keep a reference to this and add points to this later.
let source = MLNShapeSource(identifier: "polyline", shape: nil, options: nil)
style.addSource(source)
polylineSource = source
// Add a layer to style our polyline.
let layer = MLNLineStyleLayer(identifier: "polyline", source: source)
layer.lineJoin = NSExpression(forConstantValue: "round")
layer.lineCap = NSExpression(forConstantValue: "round")
layer.lineColor = NSExpression(forConstantValue: UIColor.blue)
// The line width should gradually increase based on the zoom level.
layer.lineWidth = NSExpression(forMLNInterpolating: NSExpression.zoomLevelVariable, curveType: MLNExpressionInterpolationMode.linear, parameters: nil, stops: NSExpression(forConstantValue: [14: 5, 18: 20]))
style.addLayer(layer)
}
func animatePolyline() {
currentIndex = 1
// Start a timer that will simulate adding points to our polyline. This could also represent coordinates being added to our polyline from another source, such as a CLLocationManagerDelegate.
timer = Timer.scheduledTimer(timeInterval: 0.05, target: self, selector: #selector(tick), userInfo: nil, repeats: true)
}
@objc func tick() {
if currentIndex > allCoordinates.count {
timer?.invalidate()
timer = nil
return
}
// Create a subarray of locations up to the current index.
let coordinates = Array(allCoordinates[0 ..< currentIndex])
// Update our MLNShapeSource with the current locations.
updatePolylineWithCoordinates(coordinates: coordinates)
currentIndex += 1
}
func updatePolylineWithCoordinates(coordinates: [CLLocationCoordinate2D]) {
var mutableCoordinates = coordinates
let polyline = MLNPolylineFeature(coordinates: &mutableCoordinates, count: UInt(mutableCoordinates.count))
// Updating the MLNShapeSource's shape will have the map redraw our polyline with the current coordinates.
polylineSource?.shape = polyline
}
let coordinates = [
(-122.63748, 45.52214),
(-122.64855, 45.52218),
(-122.6545, 45.52219),
(-122.65497, 45.52196),
(-122.65631, 45.52104),
(-122.6578, 45.51935),
(-122.65867, 45.51848),
(-122.65872, 45.51293),
(-122.66576, 45.51295),
(-122.66745, 45.51252),
(-122.66813, 45.51244),
(-122.67359, 45.51385),
(-122.67415, 45.51406),
(-122.67481, 45.51484),
(-122.676, 45.51532),
(-122.68106, 45.51668),
(-122.68503, 45.50934),
(-122.68546, 45.50858),
(-122.6852, 45.50783),
(-122.68424, 45.50714),
(-122.68433, 45.50585),
(-122.68429, 45.50521),
(-122.68456, 45.50445),
(-122.68538, 45.50371),
(-122.68653, 45.50311),
(-122.68731, 45.50292),
(-122.68742, 45.50253),
(-122.6867, 45.50239),
(-122.68545, 45.5026),
(-122.68407, 45.50294),
(-122.68357, 45.50271),
(-122.68236, 45.50055),
(-122.68233, 45.49994),
(-122.68267, 45.49955),
(-122.68257, 45.49919),
(-122.68376, 45.49842),
(-122.68428, 45.49821),
(-122.68573, 45.49798),
(-122.68923, 45.49805),
(-122.68926, 45.49857),
(-122.68814, 45.49911),
(-122.68865, 45.49921),
(-122.6897, 45.49905),
(-122.69346, 45.49917),
(-122.69404, 45.49902),
(-122.69438, 45.49796),
(-122.69504, 45.49697),
(-122.69624, 45.49661),
(-122.69781, 45.4955),
(-122.69803, 45.49517),
(-122.69711, 45.49508),
(-122.69688, 45.4948),
(-122.69744, 45.49368),
(-122.69702, 45.49311),
(-122.69665, 45.49294),
(-122.69788, 45.49212),
(-122.69771, 45.49264),
(-122.69835, 45.49332),
(-122.7007, 45.49334),
(-122.70167, 45.49358),
(-122.70215, 45.49401),
(-122.70229, 45.49439),
(-122.70185, 45.49566),
(-122.70215, 45.49635),
(-122.70346, 45.49674),
(-122.70517, 45.49758),
(-122.70614, 45.49736),
(-122.70663, 45.49736),
(-122.70807, 45.49767),
(-122.70807, 45.49798),
(-122.70717, 45.49798),
(-122.70713, 45.4984),
(-122.70774, 45.49893),
].map { CLLocationCoordinate2D(latitude: $0.1, longitude: $0.0) }
}
```
---
# Custom Annotation View
https://docs.mapatlas.xyz/overview/sdk/ios-native/AnnotationViewExample
# Custom Annotation View
Add a custom annotation view
This examples shows how you can implement and use a custom `MLNAnnotationView`.
You need to implement `MLNMapViewDelegate.mapView(_:viewForAnnotation:)` of `MLNMapViewDelegate` which will be called when you add an `MLNAnnotation` to the example. In this case, three `MLNPointAnnotation`s are added to the map. When one is selected selected `MLNAnnotationView.setSelected(_:animated:)` will be called.
```swift
class AnnotationViewExample: UIViewController, MLNMapViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
let mapView = MLNMapView(frame: view.bounds)
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
mapView.attributionButton.isHidden = true
mapView.tintColor = .lightGray
mapView.centerCoordinate = CLLocationCoordinate2D(latitude: 0, longitude: 66)
mapView.zoomLevel = 2
mapView.delegate = self
view.addSubview(mapView)
// Specify coordinates for our annotations.
let coordinates = [
CLLocationCoordinate2D(latitude: 0, longitude: 33),
CLLocationCoordinate2D(latitude: 0, longitude: 66),
CLLocationCoordinate2D(latitude: 0, longitude: 99),
]
// Fill an array with point annotations and add it to the map.
var pointAnnotations = [MLNPointAnnotation]()
for coordinate in coordinates {
let point = MLNPointAnnotation()
point.coordinate = coordinate
point.title = "\(coordinate.latitude), \(coordinate.longitude)"
pointAnnotations.append(point)
}
mapView.addAnnotations(pointAnnotations)
}
// MARK: - MLNMapViewDelegate methods
// This delegate method is where you tell the map to load a view for a specific annotation. To load a static MLNAnnotationImage, you would use `-mapView:imageForAnnotation:`.
func mapView(_ mapView: MLNMapView, viewFor annotation: MLNAnnotation) -> MLNAnnotationView? {
// This example is only concerned with point annotations.
guard annotation is MLNPointAnnotation else {
return nil
}
// Use the point annotation’s longitude value (as a string) as the reuse identifier for its view.
let reuseIdentifier = "\(annotation.coordinate.longitude)"
// For better performance, always try to reuse existing annotations.
var annotationView = mapView.dequeueReusableAnnotationView(withIdentifier: reuseIdentifier)
// If there’s no reusable annotation view available, initialize a new one.
if annotationView == nil {
annotationView = CustomAnnotationView(reuseIdentifier: reuseIdentifier)
annotationView!.bounds = CGRect(x: 0, y: 0, width: 40, height: 40)
// Set the annotation view’s background color to a value determined by its longitude.
let hue = CGFloat(annotation.coordinate.longitude) / 100
annotationView!.backgroundColor = UIColor(hue: hue, saturation: 0.5, brightness: 1, alpha: 1)
}
return annotationView
}
func mapView(_: MLNMapView, annotationCanShowCallout _: MLNAnnotation) -> Bool {
true
}
}
//
// MLNAnnotationView subclass
class CustomAnnotationView: MLNAnnotationView {
override func layoutSubviews() {
super.layoutSubviews()
// Use CALayer’s corner radius to turn this view into a circle.
layer.cornerRadius = bounds.width / 2
layer.borderWidth = 2
layer.borderColor = UIColor.white.cgColor
}
override func setSelected(_ selected: Bool, animated: Bool) {
super.setSelected(selected, animated: animated)
// Animate the border width in/out, creating an iris effect.
let animation = CABasicAnimation(keyPath: "borderWidth")
animation.duration = 0.1
layer.borderWidth = selected ? bounds.width / 4 : 2
layer.add(animation, forKey: "borderWidth")
}
}
```
---
# Blocking Gestures
https://docs.mapatlas.xyz/overview/sdk/ios-native/BlockingGesturesExample
# Blocking Gestures
Constrain the map to a certain area.
> Note: This example uses SwiftUI.
To constrain the map to a certain area, you need to implement the `MLNMapViewDelegate.mapView(_:shouldChangeFromCamera:toCamera:)` method of `MLNMapViewDelegate`. By returning a boolean you can either allow or disallow a camera change.
```swift
// Denver, Colorado
private let center = CLLocationCoordinate2D(latitude: 39.748947, longitude: -104.995882)
// Colorado’s bounds
private let colorado = MLNCoordinateBounds(
sw: CLLocationCoordinate2D(latitude: 36.986207, longitude: -109.049896),
ne: CLLocationCoordinate2D(latitude: 40.989329, longitude: -102.062592)
)
struct BlockingGesturesExample: UIViewRepresentable {
class Coordinator: NSObject, MLNMapViewDelegate {
func mapView(_ mapView: MLNMapView, shouldChangeFrom _: MLNMapCamera, to newCamera: MLNMapCamera) -> Bool {
// Get the current camera to restore it after.
let currentCamera = mapView.camera
// From the new camera obtain the center to test if it’s inside the boundaries.
let newCameraCenter = newCamera.centerCoordinate
// Set the map’s visible bounds to newCamera.
mapView.camera = newCamera
let newVisibleCoordinates = mapView.visibleCoordinateBounds
// Revert the camera.
mapView.camera = currentCamera
// Test if the newCameraCenter and newVisibleCoordinates are inside self.colorado.
let inside = MLNCoordinateInCoordinateBounds(newCameraCenter, colorado)
let intersects = MLNCoordinateInCoordinateBounds(newVisibleCoordinates.ne, colorado) && MLNCoordinateInCoordinateBounds(newVisibleCoordinates.sw, colorado)
return inside && intersects
}
}
func makeUIView(context: Context) -> MLNMapView {
let mapView = MLNMapView(frame: .zero, styleURL: MAP_STYLE)
mapView.setCenter(center, zoomLevel: 10, direction: 0, animated: false)
mapView.delegate = context.coordinator
return mapView
}
func updateUIView(_: MLNMapView, context _: Context) {}
func makeCoordinator() -> Coordinator {
Coordinator()
}
}
```
The style used in this example can be found here: .
---
# Fill Extrustion Layer
https://docs.mapatlas.xyz/overview/sdk/ios-native/BuildingLightExample
# Fill Extrustion Layer
Add a fill extrustion layer and adjust the light dynamically with a slider.
> Note: This example uses UIKit.
This examples adds a `MLNFillExtrusionStyleLayer`. The to be rendered height of the buildings is read from the vector data.
The global `MLNStyle.light` property is adjusted as the user changes a slider, which affects the fill extrustion layer.
```swift
class BuildingLightExample: UIViewController, MLNMapViewDelegate {
var mapView: MLNMapView!
var light: MLNLight!
var slider: UISlider!
override func viewDidLoad() {
super.viewDidLoad()
mapView = MLNMapView(frame: view.bounds, styleURL: MAP_STYLE)
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
mapView.delegate = self
// Center the map on the Flatiron Building in New York, NY.
mapView.camera = MLNMapCamera(lookingAtCenter: CLLocationCoordinate2D(latitude: 40.7411, longitude: -73.9897), altitude: 1200, pitch: 45, heading: 0)
view.addSubview(mapView)
addSlider()
}
// Add a slider to the map view. This will be used to adjust the map's light object.
func addSlider() {
slider = UISlider()
slider.translatesAutoresizingMaskIntoConstraints = false
slider.autoresizingMask = [.flexibleTopMargin, .flexibleLeftMargin, .flexibleRightMargin]
slider.minimumValue = -180
slider.maximumValue = 180
slider.value = 0
slider.isContinuous = true
slider.addTarget(self, action: #selector(shiftLight), for: .valueChanged)
view.addSubview(slider)
NSLayoutConstraint.activate([
slider.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 40.0),
slider.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -40.0),
slider.bottomAnchor.constraint(equalTo: view.bottomAnchor, constant: -75.0),
])
}
func mapView(_: MLNMapView, didFinishLoading style: MLNStyle) {
// Add a MLNFillExtrusionStyleLayer.
addFillExtrusionLayer(style: style)
// Create an MLNLight object.
light = MLNLight()
// Create an MLNSphericalPosition and set the radial, azimuthal, and polar values.
// Radial : Distance from the center of the base of an object to its light. Takes a CGFloat.
// Azimuthal : Position of the light relative to its anchor. Takes a CLLocationDirection.
// Polar : The height of the light. Takes a CLLocationDirection.
let position = MLNSphericalPositionMake(5, 180, 80)
light.position = NSExpression(forConstantValue: NSValue(mlnSphericalPosition: position))
// Set the light anchor to the map and add the light object to the map view's style. The light anchor can be the viewport (or rotates with the viewport) or the map (rotates with the map). To make the viewport the anchor, replace `map` with `viewport`.
light.anchor = NSExpression(forConstantValue: "map")
style.light = light
}
@objc func shiftLight() {
// Use the slider's value to change the light's polar value.
let position = MLNSphericalPositionMake(5, 180, CLLocationDirection(slider.value))
light.position = NSExpression(forConstantValue: NSValue(mlnSphericalPosition: position))
mapView.style?.light = light
}
func addFillExtrusionLayer(style: MLNStyle) {
// Access the OpenMapTiles source and use it to create a `MLNFillExtrusionStyleLayer`. The source identifier is `openmaptiles`. Use the `sources` property on a style to verify source identifiers.
guard let source = style.source(withIdentifier: "openmaptiles") else {
print("Could not find source openmaptiles")
return
}
let layer = MLNFillExtrusionStyleLayer(identifier: "extrusion-layer", source: source)
layer.sourceLayerIdentifier = "building"
layer.fillExtrusionBase = NSExpression(forKeyPath: "render_min_height")
layer.fillExtrusionHeight = NSExpression(forKeyPath: "render_height")
layer.fillExtrusionOpacity = NSExpression(forConstantValue: 0.8)
layer.fillExtrusionColor = NSExpression(forConstantValue: UIColor.white)
// Access the map's layer with the identifier "poi" and insert the fill extrusion layer below it.
let symbolLayer = style.layer(withIdentifier: "poi")!
style.insertLayer(layer, below: symbolLayer)
}
}
```
---
# Custom Style Layers (Metal API)
https://docs.mapatlas.xyz/overview/sdk/ios-native/CustomStyleLayerExample
# Custom Style Layers (Metal API)
Creating a Custom Style Layer with Metal
Custom style layers allow you to draw directly with Metal, enabling you to render specialized shapes, custom geometry, or apply advanced visual effects that go beyond what is possible with standard style layers.
Below you can find an example of how to create a custom style layer with `MLNCustomStyleLayer`. In this implementation, a SwiftUI view wraps an `MLNMapView` and appends a subclassed custom style layer once the map loads. The layer's `MLNCustomStyleLayer.didMoveToMapView(_:)` method handles initialization, including compiling Metal shaders and creating a [`MTLRenderPipelineState`](https://developer.apple.com/documentation/metal/mtlrenderpipelinestate) for subsequent draw operations. The `MLNCustomStyleLayer.willMoveFromMapView(_:)` method provides a place to release or invalidate resources when the layer is removed from the map, while the `MLNCustomStyleLayer.drawInMapView(_:withContext:)` method encodes the drawing commands using a [`MTLRenderCommandEncoder`](https://developer.apple.com/documentation/metal/mtlrendercommandencoder) and the map's projection matrix. By projecting latitude/longitude coordinates into a normalized 0–1 space and then transforming them into tile coordinates, the layer ensures that rendered geometry aligns correctly with the base map.
```swift
struct CustomStyleLayerExample: UIViewRepresentable {
func makeCoordinator() -> CustomStyleLayerExample.Coordinator {
Coordinator(self)
}
final class Coordinator: NSObject, MLNMapViewDelegate {
var control: CustomStyleLayerExample
init(_ control: CustomStyleLayerExample) {
self.control = control
}
func mapViewDidFinishLoadingMap(_ mapView: MLNMapView) {
let mapOverlay = CustomStyleLayer(identifier: "test-overlay")
let style = mapView.style!
style.layers.append(mapOverlay)
}
}
func makeUIView(context: Context) -> MLNMapView {
let mapView = MLNMapView()
mapView.delegate = context.coordinator
return mapView
}
func updateUIView(_: MLNMapView, context _: Context) {}
}
class CustomStyleLayer: MLNCustomStyleLayer {
private var pipelineState: MTLRenderPipelineState?
private var depthStencilStateWithoutStencil: MTLDepthStencilState?
override func didMove(to mapView: MLNMapView) {
#if MLN_RENDER_BACKEND_METAL
let resource = mapView.backendResource()
let shaderSource = """
#include
using namespace metal;
typedef struct
{
vector_float2 position;
vector_float4 color;
} Vertex;
struct RasterizerData
{
float4 position [[position]];
float4 color;
};
struct Uniforms
{
float4x4 matrix;
};
vertex RasterizerData
vertexShader(uint vertexID [[vertex_id]],
constant Vertex *vertices [[buffer(0)]],
constant Uniforms &uniforms [[buffer(1)]])
{
RasterizerData out;
const float4 position = uniforms.matrix * float4(float2(vertices[vertexID].position.xy), 1, 1);
out.position = position;
out.color = vertices[vertexID].color;
return out;
}
fragment float4 fragmentShader(RasterizerData in [[stage_in]])
{
return in.color;
}
"""
var error: NSError?
let device = resource.device
let library = try? device?.makeLibrary(source: shaderSource, options: nil)
assert(library != nil, "Error compiling shaders: \(String(describing: error))")
let vertexFunction = library?.makeFunction(name: "vertexShader")
let fragmentFunction = library?.makeFunction(name: "fragmentShader")
// Configure a pipeline descriptor that is used to create a pipeline state.
let pipelineStateDescriptor = MTLRenderPipelineDescriptor()
pipelineStateDescriptor.label = "Simple Pipeline"
pipelineStateDescriptor.vertexFunction = vertexFunction
pipelineStateDescriptor.fragmentFunction = fragmentFunction
pipelineStateDescriptor.colorAttachments[0].pixelFormat = resource.mtkView.colorPixelFormat
pipelineStateDescriptor.depthAttachmentPixelFormat = .depth32Float_stencil8
pipelineStateDescriptor.stencilAttachmentPixelFormat = .depth32Float_stencil8
do {
pipelineState = try device?.makeRenderPipelineState(descriptor: pipelineStateDescriptor)
} catch {
assertionFailure("Failed to create pipeline state: \(error)")
}
// Notice that we don't configure the stencilTest property, leaving stencil testing disabled
let depthStencilDescriptor = MTLDepthStencilDescriptor()
depthStencilDescriptor.depthCompareFunction = .always // Or another value as needed
depthStencilDescriptor.isDepthWriteEnabled = false
depthStencilStateWithoutStencil = device!.makeDepthStencilState(descriptor: depthStencilDescriptor)
#endif
}
override func willMove(from _: MLNMapView) {}
override func draw(in _: MLNMapView, with context: MLNStyleLayerDrawingContext) {
#if MLN_RENDER_BACKEND_METAL
guard let renderEncoder else { return }
// Project to 0..1.
let p1 = project(CLLocationCoordinate2D(latitude: 25.0, longitude: 12.5))
let p2 = project(CLLocationCoordinate2D(latitude: 0.0, longitude: 0.0))
let p3 = project(CLLocationCoordinate2D(latitude: 0.0, longitude: 25.0))
// Multiply by the world size so it becomes the tile coordinate system.
let worldSize = 512.0 * pow(2.0, context.zoomLevel)
let p1Tile = CGPoint(x: p1.x * worldSize, y: p1.y * worldSize)
let p2Tile = CGPoint(x: p2.x * worldSize, y: p2.y * worldSize)
let p3Tile = CGPoint(x: p3.x * worldSize, y: p3.y * worldSize)
// Then build a triangle from tile coordinates
struct Vertex { var position: vector_float2; var color: vector_float4 }
let triangleVertices: [Vertex] = [
Vertex(position: vector_float2(Float(p1Tile.x), Float(p1Tile.y)),
color: vector_float4(1, 0, 0, 1)),
Vertex(position: vector_float2(Float(p2Tile.x), Float(p2Tile.y)),
color: vector_float4(0, 1, 0, 1)),
Vertex(position: vector_float2(Float(p3Tile.x), Float(p3Tile.y)),
color: vector_float4(0, 0, 1, 1)),
]
// Use the camera's full projection matrix *unchanged*.
var matrix = convertMatrix(context.projectionMatrix)
// Encode
renderEncoder.setRenderPipelineState(pipelineState!)
renderEncoder.setDepthStencilState(depthStencilStateWithoutStencil)
renderEncoder.setVertexBytes(triangleVertices, length: MemoryLayout.size * triangleVertices.count, index: 0)
renderEncoder.setVertexBytes(&matrix, length: MemoryLayout.size, index: 1)
// Draw the triangle.
renderEncoder.drawPrimitives(type: .triangle, vertexStart: 0, vertexCount: 3)
#endif
}
func project(_ coordinate: CLLocationCoordinate2D) -> CGPoint {
// We project the coordinates into the space 0 to 1 and then scale these when drawing based on the current zoom level
let worldSize = 1.0
let x = (180.0 + coordinate.longitude) / 360.0 * worldSize
let yi = log(tan((45.0 + coordinate.latitude / 2.0) * Double.pi / 180.0))
let y = (180.0 - yi * (180.0 / Double.pi)) / 360.0 * worldSize
return CGPoint(x: x, y: y)
}
struct MLNMatrix4f {
var m00, m01, m02, m03: Float
var m10, m11, m12, m13: Float
var m20, m21, m22, m23: Float
var m30, m31, m32, m33: Float
}
func convertMatrix(_ mat: MLNMatrix4) -> MLNMatrix4f {
MLNMatrix4f(
m00: Float(mat.m00), m01: Float(mat.m01), m02: Float(mat.m02), m03: Float(mat.m03),
m10: Float(mat.m10), m11: Float(mat.m11), m12: Float(mat.m12), m13: Float(mat.m13),
m20: Float(mat.m20), m21: Float(mat.m21), m22: Float(mat.m22), m23: Float(mat.m23),
m30: Float(mat.m30), m31: Float(mat.m31), m32: Float(mat.m32), m33: Float(mat.m33)
)
}
}
```
---
# Customizing Fonts
https://docs.mapatlas.xyz/overview/sdk/ios-native/Customizing_Fonts
# Customizing Fonts
Using custom fonts
MapMetrics Native iOS can render text that is part of an `MLNSymbolStyleLayer` in a font of your choice. The font customization options discussed in this document do not apply to user interface elements such as the scale bar or annotation callout views.
## Server-side fonts
By default, the map renders characters using glyphs downloaded from the server. You apply fonts when building a style with Maputnik, in the `text-font` layout property in style JSON, or in the `MLNSymbolStyleLayer.textFontNames` property at runtime. The values in these properties must be font display names, not font family names or PostScript names.
Each font name in the list must match a font that is present on the server; otherwise, the text will not load, even if one of the fonts is available. Each font name must be included in the `{fontstack}` portion of the JSON stylesheet's `glyphs` property.
Martin can serve fonts directly. You can also generate fonts with font-maker.
## Client-side fonts
By default, Chinese hanzi, Japanese kana, and Korean hangul characters (CJK) are rendered on the client side. Client-side text rendering uses less bandwidth than server-side text rendering, especially when viewing regions of the map that feature a wide variety of CJK characters.
First, the map attempts to apply a font that you specify the same way as you would specify a server-side font: in Maputnik, in the `text-font` layout property in style JSON, or in the `MLNSymbolStyleLayer.textFontNames` property at runtime. Instead of downloading the glyphs, the map tries to find a [system font](https://developer.apple.com/documentation/uikit/uifont) or a font [bundled with your application](https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app) that matches one of these fonts based on its family name (for example, “PingFang TC”), display name (“PingFang TC Ultralight”), or PostScript name (“PingFangTC-Ultralight”).
If the symbol layer does not specify an available font that contains the required glyphs, then the map tries to find a matching font in the `MLNIdeographicFontFamilyName` [Info.plist key](doc:Info.plist_Keys). Like the `MLNSymbolStyleLayer.textFontNames` property, this key can contain a family name, display name, or PostScript name. This key is a global fallback that applies to all layers uniformly. It can either be a single string or an array of strings, which the map tries to apply in order from most preferred to least preferred.
Each character is rendered in the first font you specify that has a glyph for the character. If the entire list of fonts is exhausted, the map uses the system’s font cascade list, which may vary based on the device model and system language.
To disable client-side rendering of CJK characters, set the `MLNIdeographicFontFamilyName` key to the Boolean value `NO`. The map will revert to server-side font rendering.
---
# Vector Tile Sources
https://docs.mapatlas.xyz/overview/sdk/ios-native/DDSCircleLayerExample
# Vector Tile Sources
Add and style a vector tile source
> This example uses UIKit
This example shows how a vector data source can be added and a style for it can be configured dynamically.
The tiles are a set of tiles around Innsbruck, Austria that use the OpenMapTiles schema. We are interested in the POIs that are in the `poi` layer, and filter this further with an `NSPredicate` to only show POIs with a `class` of shop. Each POI has a `rank` which is normally used to reduce label density. In this example, we use it to demonstrate how a numeric attribute can be used for styling with the `step` expression. POIs with a rank between 0 and 10 get a red color, between 10 and 20 green, etc.
```swift
class DDSCircleLayerExample: UIViewController, MLNMapViewDelegate {
var mapView: MLNMapView!
override func viewDidLoad() {
super.viewDidLoad()
mapView = MLNMapView(frame: view.bounds, styleURL: MAP_STYLE)
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
mapView.tintColor = .darkGray
// Set the map’s center coordinate and zoom level.
let innsbruck = CLLocationCoordinate2D(latitude: 47.26497, longitude: 11.4088)
mapView.setCenter(innsbruck, animated: false)
mapView.zoomLevel = 14
mapView.delegate = self
view.addSubview(mapView)
}
// Wait until the style is loaded before modifying the map style.
func mapView(_: MLNMapView, didFinishLoading style: MLNStyle) {
let source = MLNVectorTileSource(identifier: "innsbruck-tiles", configurationURL: URL(string: "https://example.com/tiles/innsbruck-poi.json")!)
style.addSource(source)
let layer = MLNCircleStyleLayer(identifier: "poi-shop-style", source: source)
layer.sourceLayerIdentifier = "poi"
layer.predicate = NSPredicate(format: "class == %@", "shop")
// Style the circle layer color based on the rank
layer.circleColor = NSExpression(mglJSONObject: ["step", ["get", "rank"], 0, "red", 10, "green", 20, "blue", 30, "purple", 40, "yellow"] as [Any])
layer.circleRadius = NSExpression(forConstantValue: 3)
style.addLayer(layer)
}
}
```
---
# Styles in Examples
https://docs.mapatlas.xyz/overview/sdk/ios-native/ExampleStyles
# Styles in Examples
The examples below refer to a style constant. Substitute one of your own
styles — the identifiers here are placeholders, not styles hosted for you.
A style URL has the form
`https://gateway.mapmetrics-atlas.net/styles/?fileName=/
```html
3D Buildings
3D Buildings
Buildings: 0
Status: Loading...
```
```jsx
import React, { useEffect, useRef, useState } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const Building3D = () => {
const mapContainerRef = useRef(null);
const mapRef = useRef(null);
const [buildingCount, setBuildingCount] = useState(0);
const [status, setStatus] = useState('Loading...');
useEffect(() => {
if (!mapContainerRef.current || mapRef.current) return;
const token = '';
const map = new mapmetricsgl.Map({
container: mapContainerRef.current,
style: `${token}`,
center: [5.47, 51.49],
zoom: 16,
pitch: 60,
bearing: -30
});
map.on('load', () => {
console.log('Map loaded');
setStatus('Map loaded');
// Add the 3D buildings source
map.addSource('buildings', {
type: 'vector',
tiles: ['https://building.mapmetrics-atlas.net/data/buildings/{z}/{x}/{y}.pbf'],
minzoom: 13,
maxzoom: 16
});
// Add 3D buildings layer
map.addLayer({
id: 'buildings-3d',
type: 'fill-extrusion',
source: 'buildings',
'source-layer': 'building',
paint: {
'fill-extrusion-color': '#aaa',
'fill-extrusion-height': [
'case',
['has', 'height'],
['get', 'height'],
['has', 'estimated_height'],
['get', 'estimated_height'],
['has', 'building:levels'],
['*', ['to-number', ['get', 'building:levels']], 3],
['has', 'floors'],
['*', ['to-number', ['get', 'floors']], 3],
10
],
'fill-extrusion-base': 0,
'fill-extrusion-opacity': 0.9
}
});
updateBuildingCount();
});
const updateBuildingCount = () => {
const features = map.queryRenderedFeatures({ layers: ['buildings-3d'] });
setBuildingCount(features.length);
};
// Update on map movement
map.on('moveend', () => {
updateBuildingCount();
});
// Add popup on click for building info
map.on('click', 'buildings-3d', (e) => {
const coordinates = e.lngLat;
const properties = e.features[0].properties;
const actualHeight = properties.height || properties.estimated_height ||
(properties['building:levels'] ? parseInt(properties['building:levels']) * 3 : null) ||
(properties.floors ? parseInt(properties.floors) * 3 : null) || 10;
const popupContent = `
Building Info:
Buildings: {buildingCount}
Status: {status}
);
};
export default Building3D;
```
---
# 3d-buildingWithShadow
https://docs.mapatlas.xyz/sdk/examples/3d-buildingWithShadow
## 3D Building with Shadow
Shadow Length: 1.0 x
Buildings: 0
Status: Loading...
```html
3D Buildings with Shadows
Shadow Length: 1.0 x
Buildings: 0
Status: Loading...
```
---
# Add a 3D Model using Three.js
https://docs.mapatlas.xyz/sdk/examples/3d-model-threejs
---
title: "Add a 3D Model using Three.js"
category: "3d"
platform: ["web"]
difficulty: "advanced"
apis: ["Map", "addLayer", "custom layer", "triggerRepaint"]
tags: ["3d", "threejs", "gltf", "custom layer", "model", "three.js", "globe", "mercator"]
description: "Use a custom style layer with Three.js to render a 3D GLTF model on the map"
---
# Add a 3D Model using Three.js
Use a **custom style layer** with [Three.js](https://threejs.org/) to load and render a 3D GLTF model directly on the map. The model is georeferenced using the map's own projection matrix, so it stays anchored to a real-world coordinate.
> **Three.js is loaded via CDN** — no build step needed for this example.
Toggle Globe / Mercator
## How It Works
A **custom layer** gives you full access to the map's WebGL context. Three.js shares that context so both the map and your 3D model render on the same canvas.
```javascript
const customLayer = {
id: '3d-model',
type: 'custom',
renderingMode: '3d', // required for correct depth buffer
onAdd(map, gl) {
this.camera = new THREE.Camera();
this.scene = new THREE.Scene();
// Load GLTF model
const loader = new GLTFLoader();
loader.load('path/to/model.gltf', (gltf) => {
this.scene.add(gltf.scene);
});
// Share the map's WebGL canvas and context
this.renderer = new THREE.WebGLRenderer({
canvas: map.getCanvas(),
context: gl,
antialias: true
});
this.renderer.autoClear = false;
},
render(gl, args) {
// Georeference the model using map's projection matrix
const modelMatrix = map.transform.getMatrixForModel([lng, lat], altitude);
const m = new THREE.Matrix4().fromArray(args.defaultProjectionData.mainMatrix);
const l = new THREE.Matrix4().fromArray(modelMatrix).scale(new THREE.Vector3(scale, scale, scale));
this.camera.projectionMatrix = m.multiply(l);
this.renderer.resetState();
this.renderer.render(this.scene, this.camera);
this.map.triggerRepaint(); // keep re-rendering
}
};
map.on('style.load', () => {
map.addLayer(customLayer);
});
```
## Import Three.js
Use an importmap to load Three.js and GLTFLoader from CDN — no npm needed:
```html
```
## Georeference the Model
`map.transform.getMatrixForModel()` converts a `[lng, lat]` coordinate into the correct 4×4 matrix for the current projection (globe or Mercator):
```javascript
const modelMatrix = map.transform.getMatrixForModel(
[148.9819, -35.39847], // [lng, lat]
0 // altitude in meters
);
```
Scale the model up if needed — GLTF models are often designed at real-world scale (meters), but at global zoom you need a large multiplier:
```javascript
.scale(new THREE.Vector3(10_000, 10_000, 10_000))
```
## Toggle Globe vs Mercator
```javascript
const current = map.getProjection();
map.setProjection({
type: current.type === 'globe' ? 'mercator' : 'globe'
});
```
## Complete Example
```html
Toggle Globe / Mercator
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# 3D Terrain
https://docs.mapatlas.xyz/sdk/examples/3d-terrain
---
title: "3D Terrain"
category: "3d"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "terrain", "raster-dem", "TerrainControl", "NavigationControl"]
tags: ["3D", "terrain", "elevation", "DEM", "raster-dem", "exaggeration", "mountain"]
description: "Render a 3D terrain map by adding a raster-dem source and enabling the terrain property"
---
# 3D Terrain
Make your map look like a real landscape by enabling **3D terrain**. The map reads elevation data from a special tile source (`raster-dem`) and pushes mountains up into 3D.
> **No external libraries needed.** This is built directly into MapMetrics GL — no three.js, no plugins.
Drag to pan · Hold right-click and drag to tilt · Use the terrain button (mountain icon) to toggle 3D
## How It Works
3D terrain needs two things:
1. **A `raster-dem` source** — tiles containing elevation data for every point on the map
2. **The `terrain` style property** — tells the map to use that elevation data to push the land surface up into 3D
```javascript
const map = new mapmetricsgl.Map({
container: 'map',
// 1. Your regular base map — here a MapMetrics vector style
style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE.json&token=YOUR_TOKEN',
center: [11.39085, 47.27574],
zoom: 12,
pitch: 70, // Tilt the camera to see the 3D effect
maxPitch: 85,
});
// 2. Wait for the vector style to finish loading, then add elevation
map.on('load', () => {
// Elevation data source (free AWS terrain tiles — no API key needed)
map.addSource('terrainSource', {
type: 'raster-dem',
tiles: ['https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png'],
tileSize: 256,
encoding: 'terrarium',
maxzoom: 15,
});
// 3. Enable 3D terrain
map.setTerrain({ source: 'terrainSource', exaggeration: 1.5 });
});
```
## Exaggeration
`exaggeration` controls how dramatic the 3D effect looks:
| Value | Effect |
|---|---|
| `0` | Flat map (terrain disabled) |
| `1` | Real-world scale |
| `1.5` | Slightly dramatic (good default) |
| `3` | Very exaggerated mountains |
## Add a Terrain Toggle Button
```javascript
map.addControl(new mapmetricsgl.TerrainControl({
source: 'terrainSource',
exaggeration: 1.5,
}), 'top-right');
```
This adds a mountain icon button that toggles 3D terrain on/off.
## Tips
- Set `pitch: 70` or higher to see the 3D effect clearly
- Set `maxPitch: 85` to allow steep camera angles
- Add a `sky` layer for a realistic atmospheric background
- Mountains and valleys look best at zoom 8–14
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
// Replace with your own MapMetrics style URL + token
const STYLE_URL = 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE.json&token=YOUR_TOKEN';
const Terrain3D = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: STYLE_URL,
center: [11.39085, 47.27574],
zoom: 12,
pitch: 70,
maxPitch: 85,
});
map.current.on('load', () => {
map.current.addSource('terrainSource', {
type: 'raster-dem',
tiles: ['https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png'],
tileSize: 256,
encoding: 'terrarium',
maxzoom: 15,
});
map.current.setTerrain({ source: 'terrainSource', exaggeration: 1.5 });
map.current.addLayer({ id: 'sky', type: 'sky', paint: { 'sky-type': 'atmosphere' } });
});
map.current.addControl(new mapmetricsgl.NavigationControl({ visualizePitch: true }), 'top-right');
map.current.addControl(new mapmetricsgl.TerrainControl({ source: 'terrainSource', exaggeration: 1.5 }), 'top-right');
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default Terrain3D;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Create and Style Clusters
https://docs.mapatlas.xyz/sdk/examples/add-a-cluster
---
title: "Create and Style Clusters"
category: "data-visualization"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addSource", "addLayer", "getClusterExpansionZoom", "easeTo"]
tags: ["clustering", "geojson", "data-aggregation", "performance"]
description: "Group multiple markers into clusters for better performance and visualization with large datasets"
---
# Create and style clusters
##
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
// Module-level flag to prevent multiple RTL plugin loads
let rtlPluginLoaded = false;
const AddCluster = () => {
const mapContainerRef = useRef(null);
const mapRef = useRef(null);
useEffect(() => {
if (!mapContainerRef.current || mapRef.current) return;
// Load RTL plugin only once
if (!rtlPluginLoaded) {
mapmetricsgl.setRTLTextPlugin(
"https://cdn.mapmetrics-atlas.net/basemaps-assets/js/mapmetrics-gl-rtl-text.min.js"
);
rtlPluginLoaded = true;
}
const accessToken = "";
const map = new mapmetricsgl.Map({
container: mapContainerRef.current,
style: `${accessToken}`,
center: [-103.59179687498357, 40.66995747013945],
zoom: 3,
});
map.on("load", () => {
map.addSource("earthquakes", {
type: "geojson",
data: "https://cdn.mapmetrics-atlas.net/Images/heatmap.geojson",
cluster: true,
clusterMaxZoom: 14,
clusterRadius: 50,
});
map.addLayer({
id: "clusters",
type: "circle",
source: "earthquakes",
filter: ["has", "point_count"],
paint: {
"circle-color": [
"step",
["get", "point_count"],
"#51bbd6",
100,
"#f1f075",
750,
"#f28cb1",
],
"circle-radius": [
"step",
["get", "point_count"],
20,
100,
30,
750,
40,
],
},
});
map.addLayer({
id: "cluster-count",
type: "symbol",
source: "earthquakes",
filter: ["has", "point_count"],
layout: {
"text-field": "{point_count_abbreviated}",
"text-font": ["Noto Sans Medium"],
"text-size": 12,
},
});
map.addLayer({
id: "unclustered-point",
type: "circle",
source: "earthquakes",
filter: ["!", ["has", "point_count"]],
paint: {
"circle-color": "#11b4da",
"circle-radius": 4,
"circle-stroke-width": 1,
"circle-stroke-color": "#fff",
},
});
map.on("click", "clusters", async (e) => {
const features = map.queryRenderedFeatures(e.point, {
layers: ["clusters"],
});
const clusterId = features[0].properties.cluster_id;
const zoom = await map
.getSource("earthquakes")
.getClusterExpansionZoom(clusterId);
map.easeTo({
center: features[0].geometry.coordinates,
zoom,
});
});
map.on("click", "unclustered-point", (e) => {
const coordinates = e.features[0].geometry.coordinates.slice();
const mag = e.features[0].properties.mag;
let tsunami;
if (e.features[0].properties.tsunami === 1) {
tsunami = "yes";
} else {
tsunami = "no";
}
while (Math.abs(e.lngLat.lng - coordinates[0]) > 180) {
coordinates[0] += e.lngLat.lng > coordinates[0] ? 360 : -360;
}
new mapmetricsgl.Popup()
.setLngLat(coordinates)
.setHTML(`magnitude: ${mag}
);
};
export default AddCluster;
```
---
# Add a Color Relief Layer
https://docs.mapatlas.xyz/sdk/examples/add-a-color-relief-layer
---
title: "Add a Color Relief Layer"
category: "3d"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "raster-dem", "addLayer", "fill-extrusion", "color-relief"]
tags: ["color relief", "terrain", "elevation", "DEM", "raster-dem", "hypsometric", "altitude color"]
description: "Color the map surface by elevation using a raster-dem source and elevation-based color expressions"
---
# Add a Color Relief Layer
**Color relief** (also called hypsometric tinting) paints the map with colors based on elevation — lowlands are green, mid-elevations are brown, mountain peaks are white. This makes elevation immediately visible at a glance.
> **No three.js or external libraries needed.** This uses a standard raster layer with a color expression.
Color Relief
OSM Only
## How Color Relief Works
Color relief paints the terrain surface with colors that represent altitude:
```
🌊 Water / low → Deep blue / dark green
🌿 Plains → Light green
🌄 Hills → Yellow / brown
⛰️ Mountains → Dark brown / grey
🏔️ Peaks → White / light grey
```
The simplest approach is to use a `hillshade` layer with carefully chosen shadow/highlight colors, combined with a semi-transparent base map.
## Adding Color Relief with Hillshade
```javascript
map.addSource('dem', {
type: 'raster-dem',
tiles: ['https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png'],
tileSize: 256,
encoding: 'terrarium',
maxzoom: 15,
});
map.addLayer({
id: 'color-relief',
type: 'hillshade',
source: 'dem',
paint: {
'hillshade-shadow-color': '#2d6a4f', // low elevation → green
'hillshade-highlight-color': '#f8f9fa', // high elevation → white
'hillshade-accent-color': '#8B4513', // steep slopes → brown
'hillshade-exaggeration': 0.8,
'hillshade-illumination-anchor': 'viewport',
},
});
```
## Tweak the Relief Opacity
Adjust how strongly the color relief overlays the base map by changing its `hillshade-exaggeration` or by inserting the layer at a different position with `map.addLayer(..., 'beforeLayerId')`:
```javascript
// Softer relief
map.setPaintProperty('color-relief', 'hillshade-exaggeration', 0.4);
// Stronger relief
map.setPaintProperty('color-relief', 'hillshade-exaggeration', 1);
// Hide / show the relief layer entirely
map.setLayoutProperty('color-relief', 'visibility', 'none');
map.setLayoutProperty('color-relief', 'visibility', 'visible');
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const ColorReliefLayer = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
zoom: 5,
center: [13, 47],
// Replace with your own MapMetrics style URL + token
style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE.json&token=YOUR_TOKEN',
});
map.current.on('load', () => {
map.current.addSource('dem', {
type: 'raster-dem',
tiles: ['https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png'],
tileSize: 256,
encoding: 'terrarium',
maxzoom: 15,
});
map.current.addLayer({
id: 'color-relief',
type: 'hillshade',
source: 'dem',
paint: {
'hillshade-shadow-color': '#2d6a4f',
'hillshade-highlight-color': '#f8f9fa',
'hillshade-accent-color': '#8B4513',
'hillshade-exaggeration': 0.8,
'hillshade-illumination-anchor': 'viewport',
},
});
});
map.current.addControl(new mapmetricsgl.NavigationControl(), 'top-right');
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default ColorReliefLayer;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Add a Geometry
https://docs.mapatlas.xyz/sdk/examples/add-a-geometry
# Add a Geometry
##
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const AddGeometry = () => {
const mapContainerRef = useRef(null);
const mapRef = useRef(null);
useEffect(() => {
if (!mapContainerRef.current || mapRef.current) return;
const accessToken = "";
const geoJsonFeature = {
type: "Feature",
properties: {},
geometry: {
type: "LineString",
coordinates: [
[2.319887, 48.90046],
[2.329981, 48.901163],
[2.38515, 48.902008],
[2.394906, 48.898444],
[2.397627, 48.894578],
[2.398846, 48.887109],
[2.408308, 48.880409],
[2.41327, 48.872892],
[2.413838, 48.864376],
[2.416341, 48.849234],
[2.412246, 48.834539],
[2.422139, 48.835798],
[2.41939, 48.842577],
[2.42813, 48.841528],
[2.447699, 48.844818],
[2.463438, 48.842089],
[2.467426, 48.838891],
[2.467582, 48.833133],
[2.462696, 48.81906],
[2.458705, 48.81714],
[2.438448, 48.818232],
[2.421462, 48.824054],
[2.406032, 48.827615],
[2.390939, 48.826079],
[2.379296, 48.821214],
[2.363947, 48.816314],
[2.345958, 48.816036],
[2.331898, 48.817011],
[2.332461, 48.818247],
[2.292196, 48.827142],
[2.279052, 48.83249],
[2.272793, 48.82792],
[2.263174, 48.83398],
[2.255144, 48.83481],
[2.251709, 48.838822],
[2.250612, 48.845555],
[2.239978, 48.849702],
[2.224219, 48.853517],
[2.228225, 48.865183],
[2.231736, 48.869069],
[2.245678, 48.876435],
[2.25541, 48.874264],
[2.258467, 48.880387],
[2.277487, 48.877968],
[2.282327, 48.883923],
[2.291507, 48.889472],
[2.319887, 48.90046],
],
},
};
const map = new mapmetricsgl.Map({
container: mapContainerRef.current,
style: `${accessToken}`,
zoom: 11,
center: [2.349902, 48.852966],
});
map.addControl(new mapmetricsgl.NavigationControl(), "top-right");
mapmetricsgl.setRTLTextPlugin(
"https://cdn.mapmetrics-atlas.net/basemaps-assets/js/mapmetrics-gl-rtl-text.min.js"
);
map.on("load", () => {
map.addLayer({
id: "route",
type: "line",
source: {
type: "geojson",
data: geoJsonFeature,
},
layout: {
"line-join": "round",
"line-cap": "round",
},
paint: {
"line-color": "steelblue",
"line-width": 4,
},
});
});
mapRef.current = map;
return () => {
map.remove();
mapRef.current = null;
};
}, []);
return (
);
};
export default AddGeometry;
```
---
# Add a Heatmap Layer
https://docs.mapatlas.xyz/sdk/examples/add-a-heatmap
---
title: "Add a Heatmap Layer"
category: "data-visualization"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addSource", "addLayer"]
tags: ["heatmap", "density", "visualization", "geojson"]
description: "Create heatmap visualizations to show data density and patterns on your map"
---
# Add a Heatmap
##
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const AddHeatmap = () => {
const mapContainerRef = useRef(null);
const mapRef = useRef(null);
useEffect(() => {
if (!mapContainerRef.current || mapRef.current) return;
const accessToken = "";
const map = new mapmetricsgl.Map({
container: mapContainerRef.current,
style: `${accessToken}`,
center: [-120, 50],
zoom: 2,
});
map.addControl(new mapmetricsgl.NavigationControl(), "top-right");
map.on("load", () => {
mapmetricsgl.setRTLTextPlugin(
"https://cdn.mapmetrics-atlas.net/basemaps-assets/js/mapmetrics-gl-rtl-text.min.js"
);
// Add a geojson point source
map.addSource("earthquakes", {
type: "geojson",
data: "https://cdn.mapmetrics-atlas.net/Images/heatmap.geojson",
});
// Add the heatmap layer
map.addLayer(
{
id: "earthquakes-heat",
type: "heatmap",
source: "earthquakes",
maxzoom: 9,
paint: {
"heatmap-weight": [
"interpolate",
["linear"],
["get", "mag"],
0,
0,
6,
1,
],
"heatmap-intensity": 1,
"heatmap-color": [
"interpolate",
["linear"],
["heatmap-density"],
0,
"rgba(33,102,172,0)",
0.2,
"rgb(103,169,207)",
0.4,
"rgb(209,229,240)",
0.6,
"rgb(253, 199, 199)",
0.8,
"rgb(239, 98, 98)",
1,
"rgb(178, 24, 24)",
],
"heatmap-radius": [
"interpolate",
["linear"],
["zoom"],
0,
2,
9,
20,
],
"heatmap-opacity": 1,
},
},
map.getStyle().layers[map.getStyle().layers.length - 1].id
);
// Add the point layer for earthquakes
map.addLayer(
{
id: "earthquakes-point",
type: "circle",
source: "earthquakes",
minzoom: 7,
paint: {
"circle-radius": [
"interpolate",
["linear"],
["zoom"],
7,
["interpolate", ["linear"], ["get", "mag"], 1, 1, 6, 4],
16,
["interpolate", ["linear"], ["get", "mag"], 1, 5, 6, 50],
],
"circle-color": [
"interpolate",
["linear"],
["get", "mag"],
1,
"rgba(33,102,172,0)",
2,
"rgb(103,169,207)",
3,
"rgb(209,229,240)",
4,
"rgb(251, 199, 199)",
5,
"rgb(239, 98, 98)",
6,
"rgb(234, 43, 43)",
],
"circle-stroke-color": "white",
"circle-stroke-width": 1,
"circle-opacity": [
"interpolate",
["linear"],
["zoom"],
7,
0,
8,
1,
],
},
},
map.getStyle().layers[map.getStyle().layers.length - 1].id
);
});
mapRef.current = map;
return () => {
map.remove();
mapRef.current = null;
};
}, []);
return (
);
};
export default AddHeatmap;
```
---
# Add a Hillshade Layer
https://docs.mapatlas.xyz/sdk/examples/add-a-hillshade-layer
---
title: "Add a Hillshade Layer"
category: "3d"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "hillshade", "raster-dem", "addLayer"]
tags: ["hillshade", "terrain", "elevation", "shadow", "DEM", "raster-dem", "shading"]
description: "Add a hillshade layer to show terrain shadows and elevation relief on a flat map"
---
# Add a Hillshade Layer
A **hillshade layer** simulates how sunlight would fall on terrain — mountains cast shadows, valleys stay dark. This makes elevation visible on an otherwise flat 2D map.
> **No three.js or external libraries needed.** Hillshade is a built-in layer type in MapMetrics GL.
Show Hillshade
Hide Hillshade
## What is a Hillshade Layer?
Imagine shining a light from the top-left corner of the map. Mountains facing the light become bright; valleys and north-facing slopes fall into shadow. That's what a hillshade layer does — it gives a flat 2D map a sense of depth and elevation.
## Adding the Hillshade Layer
You need two things:
1. A `raster-dem` source (elevation data tiles)
2. A `hillshade` layer that references it
```javascript
// Step 1: Add the elevation data source (free AWS terrain tiles — no API key needed)
map.addSource('dem', {
type: 'raster-dem',
tiles: ['https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png'],
tileSize: 256,
encoding: 'terrarium',
maxzoom: 15,
});
// Step 2: Add the hillshade layer
map.addLayer({
id: 'hillshade',
type: 'hillshade',
source: 'dem',
paint: {
'hillshade-shadow-color': '#473B24', // shadow color
'hillshade-highlight-color': '#ffffff', // lit color
'hillshade-illumination-direction': 335, // sun angle 0–360°
'hillshade-exaggeration': 0.5, // 0 = flat, 1 = maximum contrast
},
});
```
## Paint Properties
| Property | What it does |
|---|---|
| `hillshade-shadow-color` | Color of shadowed slopes |
| `hillshade-highlight-color` | Color of sunlit slopes |
| `hillshade-accent-color` | Color of very steep slopes |
| `hillshade-illumination-direction` | Direction of the sun (0° = North) |
| `hillshade-exaggeration` | Shadow intensity (0–1) |
## Show/Hide at Runtime
```javascript
// Show
map.setLayoutProperty('hillshade', 'visibility', 'visible');
// Hide
map.setLayoutProperty('hillshade', 'visibility', 'none');
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const HillshadeLayer = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
zoom: 7,
center: [11.39085, 47.27574],
// Replace with your own MapMetrics style URL + token
style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE.json&token=YOUR_TOKEN',
});
map.current.on('load', () => {
map.current.addSource('dem', {
type: 'raster-dem',
tiles: ['https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png'],
tileSize: 256,
encoding: 'terrarium',
maxzoom: 15,
});
map.current.addLayer({
id: 'hillshade',
type: 'hillshade',
source: 'dem',
paint: {
'hillshade-shadow-color': '#473B24',
'hillshade-highlight-color': '#ffffff',
'hillshade-illumination-direction': 335,
'hillshade-exaggeration': 0.5,
},
});
});
map.current.addControl(new mapmetricsgl.NavigationControl(), 'top-right');
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default HillshadeLayer;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Add Markers to Map
https://docs.mapatlas.xyz/sdk/examples/add-a-marker
---
title: "Add Markers to Map"
category: "markers"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "Marker", "setLngLat", "addTo"]
tags: ["markers", "pins", "draggable", "custom-marker"]
description: "Learn how to add interactive markers to your map, including draggable markers"
---
# Adding Markers to Your Map
## The red marker is dragable
This guide demonstrates how to add markers to your MapMetrics map. Follow these steps to get started.
## Prerequisites
Before you begin, ensure you have:
- **Generated a style and API key:** [How to create an API key](./key-creation.md) and [How to create a map style](./style-creation.md).
## Adding a Marker
To add a marker to your map, you can use the `Marker` class provided by MapMetrics-gl. Here's how to do it:
### Example: Adding a Marker
```javascript
const marker = new mapmetricsgl.Marker()
.setLngLat([2.349902, 48.852966]) // Set the marker's position
.addTo(map); // Add the marker to the map
```
### Customizing Markers
You can customize the appearance of markers by setting properties such as color, size, and icon. For example:
```javascript
const marker = new mapmetricsgl.Marker({
color: "#FF0000", // Red color
scale: 1.5, // Increase the size
})
.setLngLat([2.349902, 48.852966])
.addTo(map);
```
### Creating a Draggable Marker with Custom Color
You can create a marker with a custom color and make it draggable by specifying the `color` and `draggable` options in the marker constructor:
```javascript
const marker = new mapmetricsgl.Marker({
color: "#FFFFFF", // White marker
draggable: true // Make the marker draggable
})
.setLngLat([30.5, 50.5])
.addTo(map);
```
You can also listen for drag events to get the marker's new position:
```javascript
marker.on('dragend', function() {
const lngLat = marker.getLngLat();
console.log('Marker dropped at', lngLat);
});
```
## Complete Example
Here's a complete example of how to add a marker to your map:
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const AddMarker = () => {
const mapContainerRef = useRef(null);
const mapRef = useRef(null);
useEffect(() => {
if (!mapContainerRef.current || mapRef.current) return;
const accessToken = "";
const map = new mapmetricsgl.Map({
container: mapContainerRef.current,
style: `${accessToken}`,
zoom: 11,
center: [2.349902, 48.852966],
});
mapRef.current = map;
map.addControl(new mapmetricsgl.NavigationControl(), 'top-right');
// Add a marker with custom icon
new mapmetricsgl.Marker({
icon: "https://cdn.mapmetrics-atlas.net/Images/car.png"
})
.setLngLat([2.349902, 48.852966])
.addTo(map);
// Add a red draggable marker
new mapmetricsgl.Marker({
color: "#FF0000",
draggable: true
})
.setLngLat([2.349902, 48.841066])
.addTo(map);
return () => {
map.remove();
mapRef.current = null;
};
}, []);
return (
);
};
export default AddMarker;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
```
---
# Drawing a Polyline on Your Map
https://docs.mapatlas.xyz/sdk/examples/add-a-polyline
# Drawing a Polyline on Your Map
This guide demonstrates how to display a polyline (LineString) on your MapMetrics map. Polylines are useful for showing routes, paths, or any sequence of connected points.
## Prerequisites
Before you begin, ensure you have:
- **Generated a style and API key:** [How to create an API key](./key-creation.md) and [How to create a map style](./style-creation.md).
## Adding a Polyline
To add a polyline, you need to:
1. Define the coordinates for your line.
2. Add a GeoJSON source to the map.
3. Add a new layer of type `line` that uses this source.
### Example: Adding a Polyline
```javascript
// Define the coordinates for your polyline
const lineCoordinates = [
[
2.3398344221314176,
48.85894283778356
],
[
2.349092133374455,
48.856611153804636
],
[
2.3539379666036098,
48.85466006946356
],
[
2.3610259017737576,
48.85189986905755
],
[
2.3589284515699944,
48.84828282438352
],
[
2.3505386507564197,
48.851566731130646
],
[
2.3433783897170883,
48.85399382812608
],
[
2.3386048823571173,
48.85732494614973
],
[
2.334409981949733,
48.85789597269732
],
[
2.3399067480006295,
48.85899042203965
]
];
// Add the source and layer when the map is loaded
map.on('load', function () {
map.addSource('route', {
'type': 'geojson',
'data': {
'type': 'Feature',
'properties': {},
'geometry': {
'type': 'LineString',
'coordinates': lineCoordinates
}
}
});
map.addLayer({
'id': 'route',
'type': 'line',
'source': 'route',
'layout': {
'line-join': 'round',
'line-cap': 'round'
},
'paint': {
'line-color': '#FF0000',
'line-width': 4
}
});
});
```
## Complete Example
Below is a complete example of how to add a polyline to your map:
```html
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
## Polyline Example (Vue)
Below is a Vue-compatible example that displays a polyline (LineString) on the map:
---
# Add Popup to Marker
https://docs.mapatlas.xyz/sdk/examples/add-a-popup
---
title: "Add Popup to Marker"
category: "popups"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "Marker", "Popup", "setPopup", "setHTML"]
tags: ["popup", "marker", "info-window", "tooltip"]
description: "Display interactive popups on markers with custom HTML content"
---
# Add a Popup
## Click on the marker for a popup
## Prerequisites
Before you begin, ensure you have:
- **Generated a style and API key:** [How to create an API key](./key-creation.md) and [How to create a map style](./style-creation.md).
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const AddPopup = () => {
const mapContainerRef = useRef(null);
const mapRef = useRef(null);
useEffect(() => {
if (!mapContainerRef.current || mapRef.current) return;
const accessToken = "";
const map = new mapmetricsgl.Map({
container: mapContainerRef.current,
style: `${accessToken}`,
zoom: 11,
center: [2.349902, 48.852966],
});
map.addControl(
new mapmetricsgl.NavigationControl(),
'top-right'
);
// Create popup
const popup = new mapmetricsgl.Popup().setHTML(
`Hello Mapmetrics A good coffee shop
`
);
// Add marker with popup
new mapmetricsgl.Marker()
.setLngLat([2.349902, 48.852966])
.setPopup(popup)
.addTo(map);
mapRef.current = map;
return () => {
map.remove();
mapRef.current = null;
};
}, []);
return (
);
};
export default AddPopup;
```
---
# Add an Icon to the Map
https://docs.mapatlas.xyz/sdk/examples/add-an-icon-to-the-map
---
title: "Add an Icon to the Map"
category: "icons-images"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "loadImage", "addImage", "addSource", "addLayer", "icon-image"]
tags: ["icon", "symbol", "image", "marker", "loadImage", "addImage", "sprite", "point"]
description: "Load an external image and use it as a map icon in a symbol layer"
---
# Add an Icon to the Map
Load an image from a URL and display it as an icon on the map using a `symbol` layer.
## Load an Image with `loadImage`
```javascript
map.on('load', () => {
map.loadImage('https://example.com/icon.png', (error, image) => {
if (error) throw error;
// Register the image with a name
map.addImage('my-icon', image);
// Use it in a symbol layer
map.addLayer({
id: 'icon-layer',
type: 'symbol',
source: 'my-source',
layout: {
'icon-image': 'my-icon',
'icon-size': 1.0,
'icon-allow-overlap': true,
}
});
});
});
```
## Symbol Layer Icon Properties
```javascript
map.addLayer({
id: 'icons',
type: 'symbol',
source: 'points',
layout: {
'icon-image': 'my-icon', // name registered with addImage()
'icon-size': 0.5, // scale factor (1.0 = original size)
'icon-anchor': 'center', // 'center', 'top', 'bottom', 'left', 'right'
'icon-allow-overlap': true, // show icon even if it overlaps others
'icon-ignore-placement': true, // don't block other features
'icon-offset': [0, -10], // [x, y] pixel offset
}
});
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const pointsData = {
type: 'FeatureCollection',
features: [
{ type: 'Feature', geometry: { type: 'Point', coordinates: [-74.0, 40.7] }, properties: {} },
{ type: 'Feature', geometry: { type: 'Point', coordinates: [2.35, 48.85] }, properties: {} },
{ type: 'Feature', geometry: { type: 'Point', coordinates: [139.7, 35.7] }, properties: {} },
]
};
const AddIconToMap = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [0, 20],
zoom: 1.5
});
map.current.on('load', () => {
map.current.loadImage('https://example.com/icon.png', (error, image) => {
if (error) throw error;
map.current.addImage('my-icon', image);
map.current.addSource('points', { type: 'geojson', data: pointsData });
map.current.addLayer({
id: 'icon-layer',
type: 'symbol',
source: 'points',
layout: {
'icon-image': 'my-icon',
'icon-size': 0.5,
'icon-allow-overlap': true,
}
});
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default AddIconToMap;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Add an Animated Icon to the Map
https://docs.mapatlas.xyz/sdk/examples/add-animated-icon
---
title: "Add an Animated Icon to the Map"
category: "icons-images"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addImage", "updateImage", "addSource", "addLayer", "requestAnimationFrame"]
tags: ["icon", "animated", "pulse", "canvas", "animation", "requestAnimationFrame", "symbol", "addImage", "updateImage"]
description: "Create a pulsing animated icon using Canvas and requestAnimationFrame"
---
# Add an Animated Icon to the Map
Create a pulsing icon animation by updating a canvas-based image on every animation frame using `map.updateImage()`.
## How It Works
The animation uses three steps:
1. Create a canvas and draw an initial frame
2. Register the image with `map.addImage()`
3. On each `requestAnimationFrame`, redraw and call `map.updateImage()` to push the new frame
## Draw and Register the Animated Icon
```javascript
const size = 80;
const canvas = document.createElement('canvas');
canvas.width = size;
canvas.height = size;
const ctx = canvas.getContext('2d');
let t = 0;
function drawFrame() {
ctx.clearRect(0, 0, size, size);
t += 0.04;
const pulse = (Math.sin(t) + 1) / 2; // oscillates 0 → 1
// Expanding ring
ctx.strokeStyle = `rgba(59, 130, 246, ${1 - pulse})`;
ctx.lineWidth = 3;
ctx.beginPath();
ctx.arc(size / 2, size / 2, 15 + pulse * 20, 0, Math.PI * 2);
ctx.stroke();
// Core dot
ctx.fillStyle = '#3b82f6';
ctx.beginPath();
ctx.arc(size / 2, size / 2, 8, 0, Math.PI * 2);
ctx.fill();
// Push updated frame to the map
if (map.hasImage('pulse-icon')) {
map.updateImage('pulse-icon', ctx.getImageData(0, 0, size, size));
}
requestAnimationFrame(drawFrame);
}
map.on('load', () => {
// Register the initial frame
map.addImage('pulse-icon', ctx.getImageData(0, 0, size, size));
// ... addSource, addLayer with 'icon-image': 'pulse-icon'
drawFrame(); // start animation loop
});
```
## Key APIs
| API | Description |
|-----|-------------|
| `map.addImage(name, data)` | Register the initial image frame |
| `map.updateImage(name, data)` | Update an existing image each frame |
| `map.hasImage(name)` | Check if an image is registered before updating |
| `requestAnimationFrame(fn)` | Browser animation loop (~60fps) |
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const pointsData = {
type: 'FeatureCollection',
features: [
{ type: 'Feature', geometry: { type: 'Point', coordinates: [-74, 40.7] }, properties: {} },
{ type: 'Feature', geometry: { type: 'Point', coordinates: [2.35, 48.85] }, properties: {} },
{ type: 'Feature', geometry: { type: 'Point', coordinates: [139.7, 35.7] }, properties: {} },
]
};
const AddAnimatedIcon = () => {
const mapContainer = useRef(null);
const map = useRef(null);
const animId = useRef(null);
useEffect(() => {
if (map.current) return;
const size = 80;
const canvas = document.createElement('canvas');
canvas.width = size; canvas.height = size;
const ctx = canvas.getContext('2d');
let t = 0;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [0, 20],
zoom: 1.5
});
const drawFrame = () => {
ctx.clearRect(0, 0, size, size);
t += 0.04;
const pulse = (Math.sin(t) + 1) / 2;
ctx.strokeStyle = `rgba(59,130,246,${1 - pulse})`;
ctx.lineWidth = 3;
ctx.beginPath();
ctx.arc(size / 2, size / 2, 15 + pulse * 20, 0, Math.PI * 2);
ctx.stroke();
ctx.fillStyle = '#3b82f6';
ctx.beginPath();
ctx.arc(size / 2, size / 2, 8, 0, Math.PI * 2);
ctx.fill();
if (map.current?.hasImage('pulse')) {
map.current.updateImage('pulse', ctx.getImageData(0, 0, size, size));
}
animId.current = requestAnimationFrame(drawFrame);
};
map.current.on('load', () => {
map.current.addImage('pulse', ctx.getImageData(0, 0, size, size));
map.current.addSource('pts', { type: 'geojson', data: pointsData });
map.current.addLayer({
id: 'pts',
type: 'symbol',
source: 'pts',
layout: { 'icon-image': 'pulse', 'icon-allow-overlap': true }
});
drawFrame();
});
return () => {
if (animId.current) cancelAnimationFrame(animId.current);
map.current?.remove(); map.current = null;
};
}, []);
return
;
};
export default AddAnimatedIcon;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Add Contour Lines
https://docs.mapatlas.xyz/sdk/examples/add-contour-lines
---
title: "Add Contour Lines"
category: "3d"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "addSource", "addLayer", "line", "GeoJSON"]
tags: ["contour", "elevation", "terrain", "lines", "topographic", "altitude", "isoline"]
description: "Draw contour lines on the map to show elevation levels using GeoJSON line features"
---
# Add Contour Lines
**Contour lines** are lines that connect points of the same elevation — like the rings you see on a topographic map. They show you how steep or flat the terrain is without needing 3D.
> **No three.js or external libraries needed.** Contour lines are drawn using a standard GeoJSON `line` layer.
Contour lines with elevation labels — thin lines every 100m, thick lines every 200m
## How Contour Lines Work
Contour lines are just line features in a GeoJSON source. Each line has an `elevation` property. You add two layers:
- **Minor lines** (thin) — every 100m interval
- **Major lines** (thick) — every 200m or 500m interval
```javascript
map.addSource('contours', {
type: 'geojson',
data: {
type: 'FeatureCollection',
features: [
{
type: 'Feature',
properties: { elevation: 500 },
geometry: {
type: 'LineString',
coordinates: [[lng1, lat1], [lng2, lat2], ...]
}
},
// more contour lines...
]
}
});
// Thin lines for all contours
map.addLayer({
id: 'contour-lines',
type: 'line',
source: 'contours',
paint: {
'line-color': '#8B4513',
'line-width': 0.8,
'line-opacity': 0.6,
}
});
// Thick lines for major intervals (every 200m)
map.addLayer({
id: 'contour-major',
type: 'line',
source: 'contours',
filter: ['==', ['%', ['get', 'elevation'], 200], 0],
paint: {
'line-color': '#5c3317',
'line-width': 2,
}
});
```
## Add Elevation Labels
Place labels along the contour lines using `symbol-placement: 'line'`:
```javascript
map.addLayer({
id: 'contour-labels',
type: 'symbol',
source: 'contours',
layout: {
'text-field': ['concat', ['to-string', ['get', 'elevation']], 'm'],
'symbol-placement': 'line', // follow the line path
'text-size': 11,
},
paint: {
'text-color': '#5c3317',
'text-halo-color': '#fff',
'text-halo-width': 1.5,
}
});
```
## Real Contour Data Sources
In production, use a real contour data source:
- **MapTiler Contours** — vector tiles with elevation data
- **OpenTopoData API** — free elevation API
- **Mapbox Terrain** — `contour` source layer in Mapbox terrain tiles
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const contourData = {
type: 'FeatureCollection',
features: [
{ type: 'Feature', properties: { elevation: 800 }, geometry: { type: 'LineString', coordinates: [[11.36,47.26],[11.38,47.275],[11.42,47.26],[11.38,47.248],[11.36,47.26]] } },
{ type: 'Feature', properties: { elevation: 1000 }, geometry: { type: 'LineString', coordinates: [[11.375,47.268],[11.390,47.272],[11.40,47.256],[11.375,47.258],[11.375,47.268]] } },
]
};
const ContourLines = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [11.39085, 47.27574],
zoom: 11,
});
map.current.on('load', () => {
map.current.addSource('contours', { type: 'geojson', data: contourData });
map.current.addLayer({
id: 'contours', type: 'line', source: 'contours',
paint: { 'line-color': '#8B4513', 'line-width': 1, 'line-opacity': 0.7 }
});
map.current.addLayer({
id: 'contour-labels', type: 'symbol', source: 'contours',
layout: {
'text-field': ['concat', ['to-string', ['get', 'elevation']], 'm'],
'symbol-placement': 'line',
'text-size': 11,
'text-font': ['Open Sans Regular', 'Arial Unicode MS Regular'],
},
paint: { 'text-color': '#5c3317', 'text-halo-color': '#fff', 'text-halo-width': 1.5 }
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default ContourLines;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Add Custom Icons with Markers
https://docs.mapatlas.xyz/sdk/examples/add-custom-icons-markers
---
title: "Add Custom Icons with Markers"
category: "icons-images"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "Marker", "setLngLat", "addTo", "getElement"]
tags: ["marker", "custom", "icon", "html", "css", "emoji", "image", "div", "getElement"]
description: "Create Markers with custom HTML elements as icons instead of the default pin"
---
# Add Custom Icons with Markers
Use the `Marker` API with a custom HTML element to display any icon — emoji, SVG, image, or styled div — as a map marker.
## Default vs Custom Marker
```javascript
// Default marker (blue pin)
new mapmetricsgl.Marker()
.setLngLat([lng, lat])
.addTo(map);
// Custom HTML marker
const el = document.createElement('div');
el.innerHTML = '⭐';
el.style.fontSize = '32px';
el.style.cursor = 'pointer';
new mapmetricsgl.Marker({ element: el })
.setLngLat([lng, lat])
.addTo(map);
```
## Create a Styled Div Marker
```javascript
function createCustomMarker(emoji, color) {
const el = document.createElement('div');
el.style.cssText = `
width: 44px;
height: 44px;
background: ${color};
border-radius: 50%;
display: flex;
align-items: center;
justify-content: center;
font-size: 22px;
border: 2px solid #fff;
box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
cursor: pointer;
`;
el.textContent = emoji;
return el;
}
const el = createCustomMarker('🏪', '#3b82f6');
new mapmetricsgl.Marker({ element: el })
.setLngLat([-74, 40.7])
.addTo(map);
```
## Use an Image as the Marker
```javascript
const el = document.createElement('img');
el.src = 'https://example.com/icon.png';
el.style.width = '40px';
el.style.height = '40px';
new mapmetricsgl.Marker({ element: el })
.setLngLat([lng, lat])
.addTo(map);
```
## Marker with Popup
```javascript
const popup = new mapmetricsgl.Popup({ offset: 25 })
.setHTML('My Location Description here
');
new mapmetricsgl.Marker({ element: el })
.setLngLat([lng, lat])
.setPopup(popup)
.addTo(map);
```
## Marker Options
```javascript
new mapmetricsgl.Marker({
element: el, // custom HTML element
anchor: 'center', // 'center', 'top', 'bottom', 'left', 'right', 'top-left', etc.
offset: [0, -20], // [x, y] pixel offset
draggable: true, // allow the user to drag the marker
})
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const places = [
{ coords: [-74, 40.7], emoji: '🗽', color: '#3b82f6', name: 'New York' },
{ coords: [2.35, 48.85], emoji: '🗼', color: '#ef4444', name: 'Paris' },
{ coords: [139.7, 35.7], emoji: '⛩️', color: '#f59e0b', name: 'Tokyo' },
];
const AddCustomIconsMarkers = () => {
const mapContainer = useRef(null);
const map = useRef(null);
const markers = useRef([]);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [10, 30],
zoom: 1.5
});
map.current.on('load', () => {
places.forEach(({ coords, emoji, color, name }) => {
const el = document.createElement('div');
Object.assign(el.style, {
width: '44px', height: '44px',
background: color, borderRadius: '50%',
display: 'flex', alignItems: 'center', justifyContent: 'center',
fontSize: '22px', border: '2px solid #fff',
boxShadow: '0 2px 6px rgba(0,0,0,0.3)', cursor: 'pointer'
});
el.textContent = emoji;
const marker = new mapmetricsgl.Marker({ element: el })
.setLngLat(coords)
.setPopup(new mapmetricsgl.Popup({ offset: 25 }).setHTML(`${name} `))
.addTo(map.current);
markers.current.push(marker);
});
});
return () => {
markers.current.forEach(m => m.remove());
map.current?.remove(); map.current = null;
};
}, []);
return
;
};
export default AddCustomIconsMarkers;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Add a Generated Icon to the Map
https://docs.mapatlas.xyz/sdk/examples/add-generated-icon
---
title: "Add a Generated Icon to the Map"
category: "icons-images"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addImage", "addSource", "addLayer", "icon-image", "Canvas"]
tags: ["icon", "generated", "canvas", "symbol", "programmatic", "custom", "image", "addImage"]
description: "Generate a custom icon programmatically using the Canvas API and add it to the map"
---
# Add a Generated Icon to the Map
Create a custom icon programmatically using the Canvas 2D API and register it with `map.addImage()`.
★ Star
● Dot
📍 Pin
## Generate an Icon with Canvas API
```javascript
function generateIcon(color) {
const size = 48;
const canvas = document.createElement('canvas');
canvas.width = size;
canvas.height = size;
const ctx = canvas.getContext('2d');
// Draw a circle
ctx.fillStyle = color;
ctx.beginPath();
ctx.arc(size / 2, size / 2, size / 2 - 2, 0, Math.PI * 2);
ctx.fill();
// White border
ctx.strokeStyle = '#ffffff';
ctx.lineWidth = 3;
ctx.stroke();
return ctx.getImageData(0, 0, size, size);
}
```
## Register and Use the Icon
```javascript
map.on('load', () => {
const iconData = generateIcon('#3b82f6');
// Register with map
map.addImage('generated-icon', iconData);
// Use in a symbol layer
map.addLayer({
id: 'icons',
type: 'symbol',
source: 'my-source',
layout: {
'icon-image': 'generated-icon',
'icon-size': 1.0,
'icon-allow-overlap': true,
}
});
});
```
## Switch Icon at Runtime
```javascript
// Update which image is used for the layer
map.setLayoutProperty('icons', 'icon-image', 'new-icon-name');
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
function makeCircleIcon(color, size = 40) {
const canvas = document.createElement('canvas');
canvas.width = size; canvas.height = size;
const ctx = canvas.getContext('2d');
ctx.fillStyle = color;
ctx.beginPath();
ctx.arc(size / 2, size / 2, size / 2 - 2, 0, Math.PI * 2);
ctx.fill();
ctx.strokeStyle = '#fff';
ctx.lineWidth = 3;
ctx.stroke();
return ctx.getImageData(0, 0, size, size);
}
const pointsData = {
type: 'FeatureCollection',
features: [
{ type: 'Feature', geometry: { type: 'Point', coordinates: [-74, 40.7] }, properties: {} },
{ type: 'Feature', geometry: { type: 'Point', coordinates: [2.35, 48.85] }, properties: {} },
{ type: 'Feature', geometry: { type: 'Point', coordinates: [139.7, 35.7] }, properties: {} },
]
};
const AddGeneratedIcon = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [10, 30],
zoom: 1.5
});
map.current.on('load', () => {
map.current.addImage('blue-dot', makeCircleIcon('#3b82f6'));
map.current.addSource('points', { type: 'geojson', data: pointsData });
map.current.addLayer({
id: 'icons',
type: 'symbol',
source: 'points',
layout: { 'icon-image': 'blue-dot', 'icon-size': 0.8, 'icon-allow-overlap': true }
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default AddGeneratedIcon;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Add a GeoJSON Line
https://docs.mapatlas.xyz/sdk/examples/add-geojson-line
---
title: "Add a GeoJSON Line"
category: "geometry"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "addSource", "addLayer", "LineString"]
tags: ["line", "geojson", "linestring", "polyline", "route", "path", "layer"]
description: "Add a GeoJSON LineString to the map as a styled line layer"
---
# Add a GeoJSON Line
Add a GeoJSON LineString source and display it as a styled line layer on the map.
## Add a GeoJSON Line
```javascript
map.on('load', () => {
map.addSource('route', {
type: 'geojson',
data: {
type: 'Feature',
geometry: {
type: 'LineString',
coordinates: [
[lng1, lat1],
[lng2, lat2],
[lng3, lat3]
]
}
}
});
map.addLayer({
id: 'route-line',
type: 'line',
source: 'route',
layout: { 'line-join': 'round', 'line-cap': 'round' },
paint: {
'line-color': '#3b82f6',
'line-width': 4,
'line-opacity': 0.9
}
});
});
```
## Line Style Options
```javascript
paint: {
'line-color': '#3b82f6',
'line-width': 4,
'line-opacity': 0.9,
'line-dasharray': [2, 4], // dashed line
'line-blur': 1, // soft edge
'line-gap-width': 2 // gap between double lines
}
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const GeoJSONLine = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.349902, 48.852966],
zoom: 4
});
map.current.addControl(new mapmetricsgl.NavigationControl(), 'top-right');
map.current.on('load', () => {
map.current.addSource('route', {
type: 'geojson',
data: {
type: 'Feature',
geometry: {
type: 'LineString',
coordinates: [[2.349902, 48.852966], [-0.1276, 51.5074], [13.405, 52.52]]
}
}
});
map.current.addLayer({
id: 'route-line',
type: 'line',
source: 'route',
layout: { 'line-join': 'round', 'line-cap': 'round' },
paint: { 'line-color': '#3b82f6', 'line-width': 4 }
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default GeoJSONLine;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Add a GeoJSON Polygon
https://docs.mapatlas.xyz/sdk/examples/add-geojson-polygon
---
title: "Add a GeoJSON Polygon"
category: "geometry"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "addSource", "addLayer", "Polygon", "fill"]
tags: ["polygon", "geojson", "fill", "area", "shape", "layer", "geometry"]
description: "Add a GeoJSON Polygon to the map as a filled area with an outline"
---
# Add a GeoJSON Polygon
Add a GeoJSON Polygon and display it as a filled area with an outline border.
## Add a Polygon
```javascript
map.on('load', () => {
map.addSource('polygon', {
type: 'geojson',
data: {
type: 'Feature',
geometry: {
type: 'Polygon',
coordinates: [[
[lng1, lat1],
[lng2, lat2],
[lng3, lat3],
[lng1, lat1] // close the ring
]]
}
}
});
// Filled area
map.addLayer({
id: 'polygon-fill',
type: 'fill',
source: 'polygon',
paint: { 'fill-color': '#3b82f6', 'fill-opacity': 0.3 }
});
// Border outline
map.addLayer({
id: 'polygon-outline',
type: 'line',
source: 'polygon',
paint: { 'line-color': '#1d4ed8', 'line-width': 2 }
});
});
```
## Polygon with a Hole
```javascript
coordinates: [
// Outer ring
[[-5, 40], [10, 40], [10, 50], [-5, 50], [-5, 40]],
// Inner ring (hole)
[[0, 44], [5, 44], [5, 47], [0, 47], [0, 44]]
]
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const GeoJSONPolygon = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.349902, 48.852966],
zoom: 4
});
map.current.on('load', () => {
map.current.addSource('polygon', {
type: 'geojson',
data: {
type: 'Feature',
geometry: {
type: 'Polygon',
coordinates: [[[-4.5, 48.0], [8.2, 48.0], [7.5, 43.5], [3.0, 42.5], [-1.8, 43.4], [-4.5, 48.0]]]
}
}
});
map.current.addLayer({ id: 'polygon-fill', type: 'fill', source: 'polygon', paint: { 'fill-color': '#3b82f6', 'fill-opacity': 0.3 } });
map.current.addLayer({ id: 'polygon-outline', type: 'line', source: 'polygon', paint: { 'line-color': '#1d4ed8', 'line-width': 2 } });
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default GeoJSONPolygon;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Add a Image as a Marker
https://docs.mapatlas.xyz/sdk/examples/add-image-marker
# Add a Image as a Marker
##
## Prerequisites
Before you begin, ensure you have:
- **Generated a style and API key:** [How to create an API key](./key-creation.md) and [How to create a map style](./style-creation.md).
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const AddImageMarker = () => {
const mapContainerRef = useRef(null);
const mapRef = useRef(null);
useEffect(() => {
if (!mapContainerRef.current || mapRef.current) return;
const accessToken = "";
const geojson = {
'type': 'FeatureCollection',
'features': [
{
'type': 'Feature',
'properties': {
'message': 'Foo',
'iconSize': [60, 60]
},
'geometry': {
'type': 'Point',
'coordinates': [-66.324462890625, -16.024695711685304]
}
},
{
'type': 'Feature',
'properties': {
'message': 'Bar',
'iconSize': [50, 50]
},
'geometry': {
'type': 'Point',
'coordinates': [-61.2158203125, -15.97189158092897]
}
},
{
'type': 'Feature',
'properties': {
'message': 'Baz',
'iconSize': [40, 40]
},
'geometry': {
'type': 'Point',
'coordinates': [-63.29223632812499, -18.28151823530889]
}
}
]
};
const map = new mapmetricsgl.Map({
container: mapContainerRef.current,
style: `${accessToken}`,
center: [-65.017, -16.457],
zoom: 5,
});
map.addControl(new mapmetricsgl.NavigationControl(), "top-right");
mapmetricsgl.setRTLTextPlugin(
"https://cdn.mapmetrics-atlas.net/basemaps-assets/js/mapmetrics-gl-rtl-text.min.js"
);
// Add markers with custom images
geojson.features.forEach((markerData) => {
const el = document.createElement('div');
el.className = 'marker';
// Apply styles using an object for cleaner code
Object.assign(el.style, {
backgroundImage: `url(https://picsum.photos/${markerData.properties.iconSize.join('/')}/)`,
width: `${markerData.properties.iconSize[0]}px`,
height: `${markerData.properties.iconSize[1]}px`,
backgroundSize: 'cover',
borderRadius: '50%',
cursor: 'pointer'
});
el.addEventListener('click', () => {
window.alert(markerData.properties.message);
});
new mapmetricsgl.Marker({ element: el })
.setLngLat(markerData.geometry.coordinates)
.addTo(map);
});
mapRef.current = map;
return () => {
map.remove();
mapRef.current = null;
};
}, []);
return (
);
};
export default AddImageMarker;
```
---
# Add a New Layer Below Labels
https://docs.mapatlas.xyz/sdk/examples/add-layer-below-labels
---
title: "Add a New Layer Below Labels"
category: "styling"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addLayer", "beforeId", "addSource"]
tags: ["layer", "order", "labels", "beforeId", "z-order", "below", "insert"]
description: "Insert a new layer below existing map labels so labels remain visible on top"
---
# Add a New Layer Below Labels
Use the `beforeId` parameter in `addLayer()` to insert layers below map labels so they stay readable.
## Insert a Layer Below Labels
```javascript
map.on('load', () => {
// Find the first symbol (label) layer in the style
const layers = map.getStyle().layers;
let firstSymbolId;
for (const layer of layers) {
if (layer.type === 'symbol') {
firstSymbolId = layer.id;
break;
}
}
map.addSource('my-source', { type: 'geojson', data: myGeoJSON });
// Pass firstSymbolId as the second argument to insert below labels
map.addLayer({
id: 'my-fill',
type: 'fill',
source: 'my-source',
paint: { 'fill-color': '#3b82f6', 'fill-opacity': 0.4 }
}, firstSymbolId);
});
```
## Insert Before a Specific Layer
```javascript
// Insert before a known layer ID
map.addLayer({ id: 'my-layer', type: 'fill', source: 'my-source', paint: {} }, 'road-label');
// Insert at the very bottom (no beforeId = on top)
map.addLayer({ id: 'my-layer', type: 'fill', source: 'my-source', paint: {} });
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const LayerBelowLabels = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({ container: mapContainer.current, style: '', center: [2.35, 48.85], zoom: 4 });
map.current.on('load', () => {
const layers = map.current.getStyle().layers;
const firstSymbolId = layers.find(l => l.type === 'symbol')?.id;
map.current.addSource('polygon', {
type: 'geojson',
data: { type: 'Feature', geometry: { type: 'Polygon', coordinates: [[[-4.5,48],[8.2,48],[7.5,43.5],[3,42.5],[-1.8,43.4],[-4.5,48]]] } }
});
map.current.addLayer({ id: 'polygon-fill', type: 'fill', source: 'polygon', paint: { 'fill-color': '#3b82f6', 'fill-opacity': 0.4 } }, firstSymbolId);
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default LayerBelowLabels;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Add a Pattern to a Polygon
https://docs.mapatlas.xyz/sdk/examples/add-pattern-to-polygon
---
title: "Add a Pattern to a Polygon"
category: "lines-polygons"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addSource", "addLayer", "loadImage", "addImage", "fill-pattern"]
tags: ["pattern", "polygon", "fill", "texture", "image", "fill-pattern", "hatch", "repeat"]
description: "Fill a polygon with a repeating image pattern using fill-pattern and loadImage"
---
# Add a Pattern to a Polygon
Fill a polygon with a repeating image texture using `fill-pattern` and `map.loadImage()`.
Pattern Fill
Solid Fill
## How It Works
1. Load or create an image to use as the tile pattern
2. Register it with `map.addImage('name', imageData)`
3. Apply it using `fill-pattern: 'name'` in the layer paint
## Using a Remote Image
```javascript
map.on('load', () => {
map.loadImage('https://example.com/pattern.png', (error, image) => {
if (error) throw error;
map.addImage('my-pattern', image);
map.addLayer({
id: 'polygon-fill',
type: 'fill',
source: 'polygon',
paint: {
'fill-pattern': 'my-pattern'
}
});
});
});
```
## Using a Canvas-Generated Pattern
```javascript
// Create pattern programmatically with Canvas API
const size = 16;
const canvas = document.createElement('canvas');
canvas.width = size;
canvas.height = size;
const ctx = canvas.getContext('2d');
// Draw diagonal lines
ctx.strokeStyle = '#3b82f6';
ctx.lineWidth = 2;
ctx.beginPath();
ctx.moveTo(0, size);
ctx.lineTo(size, 0);
ctx.stroke();
// Register as a map image
const imageData = ctx.getImageData(0, 0, size, size);
map.addImage('hatch', imageData);
map.addLayer({
id: 'fill',
type: 'fill',
source: 'polygon',
paint: { 'fill-pattern': 'hatch' }
});
```
## Pattern Layer Properties
```javascript
map.addLayer({
id: 'polygon-fill',
type: 'fill',
source: 'polygon',
paint: {
'fill-pattern': 'my-pattern', // image name from addImage()
'fill-opacity': 0.9, // overall opacity
// Note: fill-color is ignored when fill-pattern is set
}
});
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const polygonData = {
type: 'Feature',
geometry: {
type: 'Polygon',
coordinates: [[[0, 44], [12, 44], [12, 54], [0, 54], [0, 44]]]
}
};
const AddPatternToPolygon = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [5, 48],
zoom: 4
});
map.current.on('load', () => {
// Create hatch pattern
const size = 16;
const canvas = document.createElement('canvas');
canvas.width = size; canvas.height = size;
const ctx = canvas.getContext('2d');
ctx.strokeStyle = '#3b82f6';
ctx.lineWidth = 2;
ctx.beginPath(); ctx.moveTo(0, size); ctx.lineTo(size, 0); ctx.stroke();
ctx.beginPath(); ctx.moveTo(-size, size); ctx.lineTo(size, -size); ctx.stroke();
ctx.beginPath(); ctx.moveTo(0, 2 * size); ctx.lineTo(2 * size, 0); ctx.stroke();
map.current.addImage('hatch', ctx.getImageData(0, 0, size, size));
map.current.addSource('polygon', { type: 'geojson', data: polygonData });
map.current.addLayer({
id: 'polygon-fill',
type: 'fill',
source: 'polygon',
paint: { 'fill-pattern': 'hatch', 'fill-opacity': 0.8 }
});
map.current.addLayer({
id: 'polygon-outline',
type: 'line',
source: 'polygon',
paint: { 'line-color': '#1d4ed8', 'line-width': 2 }
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default AddPatternToPolygon;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Add a Stretchable Image to the Map
https://docs.mapatlas.xyz/sdk/examples/add-stretchable-image
---
title: "Add a Stretchable Image to the Map"
category: "icons-images"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addImage", "addSource", "addLayer", "stretchX", "stretchY", "content", "icon-text-fit"]
tags: ["stretchable", "nine-patch", "icon", "image", "addImage", "stretchX", "stretchY", "content", "label", "icon-text-fit"]
description: "Use a stretchable (nine-patch) image as an icon that scales without distortion"
---
# Add a Stretchable Image to the Map
A stretchable image (nine-patch) allows certain regions to stretch while keeping corners and edges crisp. Use `stretchX`, `stretchY`, and `content` in `map.addImage()` to define which parts can stretch and where text is placed.
## What is a Stretchable Image?
A stretchable image is similar to Android's **nine-patch** format. You define:
- `stretchX` — pixel ranges along the X axis that can be stretched
- `stretchY` — pixel ranges along the Y axis that can be stretched
- `content` — the bounding box `[left, top, right, bottom]` where text/icon content is placed
This lets the image scale gracefully without distorting corners or borders.
## Create and Register a Stretchable Image
```javascript
const width = 60, height = 24;
const canvas = document.createElement('canvas');
canvas.width = width; canvas.height = height;
const ctx = canvas.getContext('2d');
// Draw a pill shape (rounded rect)
const r = height / 2;
ctx.fillStyle = '#3b82f6';
ctx.beginPath();
ctx.moveTo(r, 0);
ctx.arcTo(width, 0, width, height, r);
ctx.arcTo(width, height, 0, height, r);
ctx.arcTo(0, height, 0, 0, r);
ctx.arcTo(0, 0, width, 0, r);
ctx.closePath();
ctx.fill();
const imageData = ctx.getImageData(0, 0, width, height);
map.addImage('stretchable-pill', imageData, {
stretchX: [[8, width - 8]], // horizontal stretch zone
stretchY: [[4, height - 4]], // vertical stretch zone
content: [8, 4, width - 8, height - 4], // where text goes
pixelRatio: 1
});
```
## Use with `icon-text-fit`
```javascript
map.addLayer({
id: 'labels',
type: 'symbol',
source: 'points',
layout: {
'icon-image': 'stretchable-pill',
'icon-text-fit': 'both', // 'none' | 'width' | 'height' | 'both'
'icon-text-fit-padding': [4, 8, 4, 8], // padding inside the content box
'icon-allow-overlap': true,
}
});
```
## `stretchX` / `stretchY` Format
```javascript
// Array of [from, to] pixel ranges (0-indexed)
stretchX: [[8, 52]] // pixels 8–52 can stretch horizontally
stretchY: [[4, 20]] // pixels 4–20 can stretch vertically
// Multiple stretch zones
stretchX: [[4, 12], [48, 56]]
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const citiesData = {
type: 'FeatureCollection',
features: [
{ type: 'Feature', geometry: { type: 'Point', coordinates: [-74, 40.7] }, properties: { label: 'New York' } },
{ type: 'Feature', geometry: { type: 'Point', coordinates: [2.35, 48.85] }, properties: { label: 'Paris' } },
{ type: 'Feature', geometry: { type: 'Point', coordinates: [139.7, 35.7] }, properties: { label: 'Tokyo' } },
]
};
const AddStretchableImage = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [10, 30],
zoom: 2
});
map.current.on('load', () => {
const w = 60, h = 24, r = h / 2;
const canvas = document.createElement('canvas');
canvas.width = w; canvas.height = h;
const ctx = canvas.getContext('2d');
ctx.fillStyle = '#3b82f6';
ctx.beginPath();
ctx.moveTo(r, 0);
ctx.arcTo(w, 0, w, h, r); ctx.arcTo(w, h, 0, h, r);
ctx.arcTo(0, h, 0, 0, r); ctx.arcTo(0, 0, w, 0, r);
ctx.closePath(); ctx.fill();
map.current.addImage('pill', ctx.getImageData(0, 0, w, h), {
stretchX: [[8, w - 8]],
stretchY: [[4, h - 4]],
content: [8, 4, w - 8, h - 4]
});
map.current.addSource('cities', { type: 'geojson', data: citiesData });
map.current.addLayer({
id: 'labels',
type: 'symbol',
source: 'cities',
layout: {
'icon-image': 'pill',
'icon-text-fit': 'both',
'icon-text-fit-padding': [4, 8, 4, 8],
'icon-allow-overlap': true
}
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default AddStretchableImage;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Animate a Line
https://docs.mapatlas.xyz/sdk/examples/animate-a-line
---
title: "Animate a Line"
category: "lines-polygons"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addSource", "addLayer", "setData", "requestAnimationFrame"]
tags: ["line", "animate", "animation", "lineString", "draw", "route", "path", "requestAnimationFrame"]
description: "Animate a line being drawn on the map step by step using requestAnimationFrame"
---
# Animate a Line
Draw a line on the map that animates progressively, revealing a path step by step.
▶ Start
↺ Reset
## How It Works
Use `setData()` on a GeoJSON source to progressively add coordinates to a LineString, driven by `requestAnimationFrame` or `setTimeout`.
## Key Pattern
```javascript
// 1. Add source with empty line
map.addSource('route', {
type: 'geojson',
data: { type: 'Feature', geometry: { type: 'LineString', coordinates: [] } }
});
// 2. Add line layer
map.addLayer({
id: 'route-line',
type: 'line',
source: 'route',
paint: { 'line-color': '#3b82f6', 'line-width': 3 }
});
// 3. Animate by adding one coordinate at a time
let step = 0;
const coordinates = [[lng1, lat1], [lng2, lat2], ...];
function animate() {
if (step >= coordinates.length) return;
step++;
map.getSource('route').setData({
type: 'Feature',
geometry: { type: 'LineString', coordinates: coordinates.slice(0, step) }
});
setTimeout(() => requestAnimationFrame(animate), 300);
}
animate();
```
## Smooth Animation with Interpolation
For very smooth animation between two points:
```javascript
const from = [0, 0];
const to = [10, 10];
const steps = 100;
let i = 0;
function animate() {
if (i > steps) return;
const t = i / steps;
const lng = from[0] + (to[0] - from[0]) * t;
const lat = from[1] + (to[1] - from[1]) * t;
map.getSource('route').setData({
type: 'Feature',
geometry: { type: 'LineString', coordinates: [from, [lng, lat]] }
});
i++;
requestAnimationFrame(animate);
}
```
## Complete Example
```html
▶ Animate
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const coordinates = [
[2.349902, 48.852966],
[-0.1276, 51.5074],
[13.405, 52.52],
[16.3738, 48.2082],
[12.4964, 41.9028],
];
const AnimateLine = () => {
const mapContainer = useRef(null);
const map = useRef(null);
const timer = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.349902, 48.852966],
zoom: 4
});
map.current.addControl(new mapmetricsgl.NavigationControl(), 'top-right');
map.current.on('load', () => {
map.current.addSource('route', {
type: 'geojson',
data: { type: 'Feature', geometry: { type: 'LineString', coordinates: [] } }
});
map.current.addLayer({
id: 'route-line',
type: 'line',
source: 'route',
paint: { 'line-color': '#3b82f6', 'line-width': 3 }
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
const startAnimation = () => {
let step = 0;
const animate = () => {
if (step >= coordinates.length) return;
step++;
map.current?.getSource('route')?.setData({
type: 'Feature',
geometry: { type: 'LineString', coordinates: coordinates.slice(0, step) }
});
timer.current = setTimeout(() => requestAnimationFrame(animate), 400);
};
animate();
};
return (
);
};
export default AnimateLine;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Animate Camera Around a Point
https://docs.mapatlas.xyz/sdk/examples/animate-camera-around-point
---
title: "Animate Camera Around a Point"
category: "camera"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "easeTo", "getBearing"]
tags: ["camera", "animation", "rotate", "orbit", "bearing"]
description: "Continuously rotate the map camera around a fixed point to create an orbiting animation"
---
# Animate Camera Around a Point
Continuously rotate the map camera around a fixed point to create a smooth orbiting animation.
▶ Start Rotation
⏹ Stop Rotation
## How It Works
The animation works by repeatedly calling `map.easeTo()` with an incremented bearing on each animation frame using `requestAnimationFrame`.
## Basic Usage
```javascript
let rotating = false;
let animationId = null;
function rotateCamera() {
if (!rotating) return;
// Increment bearing by a small amount each frame
map.easeTo({
bearing: map.getBearing() + 0.3,
duration: 0,
easing: (t) => t
});
// Request next frame
animationId = requestAnimationFrame(rotateCamera);
}
// Start rotation
function startRotation() {
rotating = true;
rotateCamera();
}
// Stop rotation
function stopRotation() {
rotating = false;
if (animationId) cancelAnimationFrame(animationId);
}
```
## Customization
```javascript
// Faster rotation
map.easeTo({ bearing: map.getBearing() + 1.0, duration: 0 });
// Slower rotation
map.easeTo({ bearing: map.getBearing() + 0.1, duration: 0 });
// Rotate AND change pitch for a dynamic effect
map.easeTo({
bearing: map.getBearing() + 0.5,
pitch: 60,
duration: 0
});
```
## Complete Example
```html
▶ Start Rotation
⏹ Stop Rotation
```
```jsx
import React, { useEffect, useRef, useState } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const AnimateCameraAround = () => {
const mapContainer = useRef(null);
const map = useRef(null);
const rotating = useRef(false);
const animationId = useRef(null);
const [isRotating, setIsRotating] = useState(false);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.349902, 48.852966],
zoom: 14,
pitch: 60,
bearing: 0
});
map.current.addControl(new mapmetricsgl.NavigationControl(), 'top-right');
return () => {
rotating.current = false;
if (animationId.current) cancelAnimationFrame(animationId.current);
map.current?.remove();
map.current = null;
};
}, []);
const rotateCamera = () => {
if (!rotating.current) return;
map.current?.easeTo({ bearing: map.current.getBearing() + 0.3, duration: 0, easing: t => t });
animationId.current = requestAnimationFrame(rotateCamera);
};
const startRotation = () => {
rotating.current = true;
setIsRotating(true);
rotateCamera();
};
const stopRotation = () => {
rotating.current = false;
setIsRotating(false);
if (animationId.current) cancelAnimationFrame(animationId.current);
};
return (
{!isRotating ? (
▶ Start Rotation
) : (
⏹ Stop Rotation
)}
);
};
export default AnimateCameraAround;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Animate a Marker
https://docs.mapatlas.xyz/sdk/examples/animate-marker
---
title: "Animate a Marker"
category: "animations"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "Marker", "setLngLat", "requestAnimationFrame"]
tags: ["animate", "marker", "animation", "moving", "requestAnimationFrame", "pulse"]
description: "Animate a marker moving on the map using requestAnimationFrame"
---
# Animate a Marker
Animate a Marker smoothly across the map using `requestAnimationFrame` and `setLngLat()`.
▶ Start
⏹ Stop
## Animate a Marker with requestAnimationFrame
```javascript
const marker = new mapmetricsgl.Marker({ color: '#3b82f6' })
.setLngLat([0, 0])
.addTo(map);
let t = 0;
function animate() {
t += 0.005;
// Move in a sine wave pattern
const lng = (t * 30) % 360 - 180;
const lat = Math.sin(t) * 40;
marker.setLngLat([lng, lat]);
requestAnimationFrame(animate);
}
animate();
```
## Animate Along Waypoints
```javascript
const waypoints = [[2.35, 48.85], [-0.12, 51.50], [13.40, 52.52]];
let step = 0;
const stepsPerSegment = 100;
let subStep = 0;
function animate() {
const from = waypoints[step];
const to = waypoints[(step + 1) % waypoints.length];
const t = subStep / stepsPerSegment;
marker.setLngLat([
from[0] + (to[0] - from[0]) * t,
from[1] + (to[1] - from[1]) * t
]);
subStep++;
if (subStep > stepsPerSegment) {
subStep = 0;
step = (step + 1) % waypoints.length;
}
requestAnimationFrame(animate);
}
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const AnimateMarker = () => {
const mapContainer = useRef(null);
const map = useRef(null);
const animId = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({ container: mapContainer.current, style: '', center: [0, 20], zoom: 1.5 });
const marker = new mapmetricsgl.Marker({ color: '#3b82f6' }).setLngLat([0, 20]).addTo(map.current);
let t = 0;
const animate = () => {
t += 0.005;
marker.setLngLat([(t * 30) % 360 - 180, Math.sin(t) * 40]);
animId.current = requestAnimationFrame(animate);
};
map.current.on('load', animate);
return () => {
if (animId.current) cancelAnimationFrame(animId.current);
map.current?.remove(); map.current = null;
};
}, []);
return
;
};
export default AnimateMarker;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Animate a Point Along a Route
https://docs.mapatlas.xyz/sdk/examples/animate-point-along-route
---
title: "Animate a Point Along a Route"
category: "lines-polygons"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addSource", "addLayer", "setData", "requestAnimationFrame"]
tags: ["animate", "point", "route", "path", "moving-marker", "animation", "lineString", "symbol"]
description: "Animate a point marker moving along a defined route path on the map"
---
# Animate a Point Along a Route
Move a point marker smoothly along a route path using frame-by-frame animation.
▶ Start
⏹ Stop
↺ Reset
## How It Works
1. Add a GeoJSON `Point` source at the starting position
2. Add a `circle` (or `symbol`) layer to display the point
3. On each animation frame, update the point's coordinates using `setData()`
## Key Pattern
```javascript
// 1. Add point source at start position
map.addSource('point', {
type: 'geojson',
data: {
type: 'Feature',
geometry: { type: 'Point', coordinates: route[0] }
}
});
// 2. Display as circle
map.addLayer({
id: 'moving-point',
type: 'circle',
source: 'point',
paint: {
'circle-radius': 10,
'circle-color': '#3b82f6',
'circle-stroke-width': 3,
'circle-stroke-color': '#fff'
}
});
// 3. Animate along route
let step = 0;
function animate() {
if (step >= route.length) return;
map.getSource('point').setData({
type: 'Feature',
geometry: { type: 'Point', coordinates: route[step] }
});
step++;
requestAnimationFrame(animate);
}
animate();
```
## Interpolation for Smooth Movement
Interpolate between waypoints to get smooth frame-by-frame movement:
```javascript
function interpolate(from, to, t) {
return [
from[0] + (to[0] - from[0]) * t,
from[1] + (to[1] - from[1]) * t
];
}
// Generate 60 steps between each pair of waypoints
for (let i = 0; i < waypoints.length - 1; i++) {
for (let s = 0; s < 60; s++) {
const t = s / 60;
points.push(interpolate(waypoints[i], waypoints[i + 1], t));
}
}
```
## Complete Example
```html
▶ Start
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const waypoints = [
[2.349902, 48.852966],
[-0.1276, 51.5074],
[13.405, 52.52],
[12.4964, 41.9028],
];
// Build interpolated route
const route = [];
for (let i = 0; i < waypoints.length - 1; i++) {
for (let s = 0; s < 60; s++) {
const t = s / 60;
route.push([
waypoints[i][0] + (waypoints[i+1][0] - waypoints[i][0]) * t,
waypoints[i][1] + (waypoints[i+1][1] - waypoints[i][1]) * t,
]);
}
}
route.push(waypoints[waypoints.length - 1]);
const AnimatePoint = () => {
const mapContainer = useRef(null);
const map = useRef(null);
const animId = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.349902, 48.852966],
zoom: 4
});
map.current.addControl(new mapmetricsgl.NavigationControl(), 'top-right');
map.current.on('load', () => {
map.current.addSource('route-line', {
type: 'geojson',
data: { type: 'Feature', geometry: { type: 'LineString', coordinates: waypoints } }
});
map.current.addLayer({
id: 'route', type: 'line', source: 'route-line',
paint: { 'line-color': '#94a3b8', 'line-width': 2, 'line-dasharray': [2, 2] }
});
map.current.addSource('point', {
type: 'geojson',
data: { type: 'Feature', geometry: { type: 'Point', coordinates: waypoints[0] } }
});
map.current.addLayer({
id: 'moving-point', type: 'circle', source: 'point',
paint: { 'circle-radius': 10, 'circle-color': '#3b82f6', 'circle-stroke-width': 3, 'circle-stroke-color': '#fff' }
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
const start = () => {
let step = 0;
const animate = () => {
if (step >= route.length) return;
map.current?.getSource('point')?.setData({
type: 'Feature',
geometry: { type: 'Point', coordinates: route[step++] }
});
animId.current = requestAnimationFrame(animate);
};
animate();
};
return (
);
};
export default AnimatePoint;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Animate a Point
https://docs.mapatlas.xyz/sdk/examples/animate-point
---
title: "Animate a Point"
category: "special"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "addSource", "addLayer", "setData", "requestAnimationFrame"]
tags: ["animate", "point", "circle", "moving", "orbit", "sine", "cosine", "requestAnimationFrame"]
description: "Animate a point on the map using requestAnimationFrame to create smooth movement"
---
# Animate a Point
Move a point continuously on the map using `requestAnimationFrame` for smooth, frame-based animation.
▶ Start
⏹ Stop
## How It Works
Use `requestAnimationFrame` to call a function on every browser repaint (~60fps). On each frame, compute the new position and call `setData()` to move the point.
## Key Pattern
```javascript
// 1. Add point source
map.addSource('point', {
type: 'geojson',
data: {
type: 'Feature',
geometry: { type: 'Point', coordinates: [0, 0] },
properties: {}
}
});
// 2. Display as circle layer
map.addLayer({
id: 'point',
type: 'circle',
source: 'point',
paint: { 'circle-radius': 12, 'circle-color': '#f59e0b' }
});
// 3. Animate position on each frame
let t = 0;
function animate() {
t += 0.01;
const lng = Math.cos(t) * 60;
const lat = Math.sin(t) * 30;
map.getSource('point').setData({
type: 'Feature',
geometry: { type: 'Point', coordinates: [lng, lat] },
properties: {}
});
requestAnimationFrame(animate);
}
animate();
```
## Stop and Resume Animation
```javascript
let animId = null;
let running = false;
function start() {
if (running) return;
running = true;
function tick() {
if (!running) return;
// update position...
animId = requestAnimationFrame(tick);
}
tick();
}
function stop() {
running = false;
if (animId) cancelAnimationFrame(animId);
}
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const AnimatePoint = () => {
const mapContainer = useRef(null);
const map = useRef(null);
const animId = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [0, 0],
zoom: 1.5
});
map.current.on('load', () => {
map.current.addSource('point', {
type: 'geojson',
data: { type: 'Feature', geometry: { type: 'Point', coordinates: [0, 0] }, properties: {} }
});
map.current.addLayer({
id: 'point',
type: 'circle',
source: 'point',
paint: { 'circle-radius': 12, 'circle-color': '#f59e0b', 'circle-stroke-width': 3, 'circle-stroke-color': '#fff' }
});
let t = 0;
const animate = () => {
t += 0.015;
map.current?.getSource('point')?.setData({
type: 'Feature',
geometry: { type: 'Point', coordinates: [Math.cos(t) * 60, Math.sin(t * 0.7) * 30] },
properties: {}
});
animId.current = requestAnimationFrame(animate);
};
animate();
});
return () => {
if (animId.current) cancelAnimationFrame(animId.current);
map.current?.remove();
map.current = null;
};
}, []);
return
;
};
export default AnimatePoint;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Arc Layer — Flight Routes
https://docs.mapatlas.xyz/sdk/examples/arc-layer
---
title: "Arc Layer — Flight Routes"
category: "data-visualization"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addSource", "addLayer", "setData"]
tags: ["arc", "line", "flow", "animation", "geojson", "flight", "routes", "connections"]
description: "Visualize connections between locations using animated curved arc lines — great for flight routes, migration flows, and network links"
---
# Arc Layer — Flight Routes
Visualize connections between cities using animated curved arcs. Each arc is a bezier curve drawn between an origin and destination, colored by direction and animated with a flowing dash effect.
⏸ Pause
Line width
2px
## How It Works
Each arc is a **quadratic bezier curve** computed in JavaScript between two `[lng, lat]` coordinates. The curve is added as a GeoJSON `LineString` source, then rendered with a `line` layer. A flowing animation is achieved by cycling through `line-dasharray` values each frame using `requestAnimationFrame`.
### Step 1 — Generate bezier arc coordinates
```javascript
function bezierArc(from, to, steps = 80) {
const coords = [];
const midLng = (from[0] + to[0]) / 2;
const midLat = (from[1] + to[1]) / 2;
const dist = Math.sqrt(Math.pow(to[0] - from[0], 2) + Math.pow(to[1] - from[1], 2));
const ctrl = [midLng, midLat + dist * 0.25]; // control point lifted upward
for (let i = 0; i <= steps; i++) {
const t = i / steps;
const lng = (1-t)*(1-t)*from[0] + 2*(1-t)*t*ctrl[0] + t*t*to[0];
const lat = (1-t)*(1-t)*from[1] + 2*(1-t)*t*ctrl[1] + t*t*to[1];
coords.push([lng, lat]);
}
return coords;
}
```
### Step 2 — Add source and layer
```javascript
map.addSource('arc-0', {
type: 'geojson',
data: {
type: 'Feature',
geometry: { type: 'LineString', coordinates: bezierArc(from, to) }
}
});
map.addLayer({
id: 'arc-line-0',
type: 'line',
source: 'arc-0',
paint: {
'line-color': '#ef4444',
'line-width': 2,
'line-opacity': 0.9,
'line-dasharray': [0, 4, 3],
}
});
```
### Step 3 — Animate the dash
```javascript
const dashArraySequence = [
[0, 4, 3], [0.5, 4, 2.5], [1, 4, 2], /* ... */
];
let step = 0;
function animate(timestamp) {
const newStep = Math.floor((timestamp / 80) % dashArraySequence.length);
if (newStep !== step) {
step = newStep;
map.setPaintProperty('arc-line-0', 'line-dasharray', dashArraySequence[step]);
}
requestAnimationFrame(animate);
}
requestAnimationFrame(animate);
```
## Complete Example
```html
⏸ Pause
Width
2px
```
```jsx
import React, { useEffect, useRef, useState } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const routes = [
{ from: [-73.9857, 40.7484], to: [-0.1276, 51.5074], color: '#ef4444', label: 'NYC → London' },
{ from: [-73.9857, 40.7484], to: [2.3490, 48.8530], color: '#f97316', label: 'NYC → Paris' },
{ from: [-73.9857, 40.7484], to: [13.4050, 52.5200], color: '#eab308', label: 'NYC → Berlin' },
{ from: [-73.9857, 40.7484], to: [37.6173, 55.7558], color: '#22c55e', label: 'NYC → Moscow' },
{ from: [-73.9857, 40.7484], to: [139.6917, 35.6895], color: '#06b6d4', label: 'NYC → Tokyo' },
{ from: [-73.9857, 40.7484], to: [103.8198, 1.3521], color: '#8b5cf6', label: 'NYC → Singapore' },
{ from: [-73.9857, 40.7484], to: [151.2093, -33.8688], color: '#ec4899', label: 'NYC → Sydney' },
{ from: [-73.9857, 40.7484], to: [-43.1729, -22.9068], color: '#14b8a6', label: 'NYC → Rio' },
{ from: [-73.9857, 40.7484], to: [18.4241, -33.9249], color: '#a855f7', label: 'NYC → Cape Town' },
{ from: [-73.9857, 40.7484], to: [72.8777, 19.0760], color: '#f59e0b', label: 'NYC → Mumbai' },
];
function bezierArc(from, to, steps = 80) {
const coords = [];
const midLng = (from[0] + to[0]) / 2;
const midLat = (from[1] + to[1]) / 2;
const dist = Math.sqrt(Math.pow(to[0] - from[0], 2) + Math.pow(to[1] - from[1], 2));
const ctrl = [midLng, midLat + dist * 0.25];
for (let i = 0; i <= steps; i++) {
const t = i / steps;
coords.push([
(1-t)*(1-t)*from[0] + 2*(1-t)*t*ctrl[0] + t*t*to[0],
(1-t)*(1-t)*from[1] + 2*(1-t)*t*ctrl[1] + t*t*to[1],
]);
}
return coords;
}
const dashArraySequence = [
[0,4,3],[0.5,4,2.5],[1,4,2],[1.5,4,1.5],[2,4,1],[2.5,4,0.5],[3,4,0],
[0,0.5,3,3.5],[0,1,3,3],[0,1.5,3,2.5],[0,2,3,2],[0,2.5,3,1.5],
[0,3,3,1],[0,3.5,3,0.5],[0,4,3,0],
];
const ArcLayer = () => {
const mapContainer = useRef(null);
const map = useRef(null);
const rafId = useRef(null);
const [running, setRunning] = useState(true);
const runningRef = useRef(true);
const [lineWidth, setLineWidth] = useState(2);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: 'YOUR_STYLE_URL_WITH_TOKEN',
center: [-30, 30],
zoom: 1.5,
});
map.current.addControl(new mapmetricsgl.NavigationControl(), 'top-right');
map.current.on('load', () => {
routes.forEach((route, i) => {
map.current.addSource(`arc-${i}`, {
type: 'geojson',
data: { type: 'Feature', geometry: { type: 'LineString', coordinates: bezierArc(route.from, route.to) } }
});
map.current.addLayer({
id: `arc-glow-${i}`, type: 'line', source: `arc-${i}`,
paint: { 'line-color': route.color, 'line-width': 6, 'line-opacity': 0.15, 'line-blur': 4 }
});
map.current.addLayer({
id: `arc-line-${i}`, type: 'line', source: `arc-${i}`,
paint: { 'line-color': route.color, 'line-width': 2, 'line-opacity': 0.9, 'line-dasharray': [0, 4, 3] }
});
});
new mapmetricsgl.Marker({ color: '#ffffff', scale: 1.2 })
.setLngLat([-73.9857, 40.7484])
.setPopup(new mapmetricsgl.Popup({ offset: 20 }).setHTML('New York City ${route.label} `))
.addTo(map.current);
});
let step = 0;
const animate = (timestamp) => {
if (!runningRef.current) return;
const newStep = Math.floor((timestamp / 80) % dashArraySequence.length);
if (newStep !== step) {
step = newStep;
routes.forEach((_, i) => {
map.current?.setPaintProperty(`arc-line-${i}`, 'line-dasharray', dashArraySequence[step]);
});
}
rafId.current = requestAnimationFrame(animate);
};
rafId.current = requestAnimationFrame(animate);
});
return () => {
if (rafId.current) cancelAnimationFrame(rafId.current);
map.current?.remove();
map.current = null;
};
}, []);
const toggle = () => {
runningRef.current = !runningRef.current;
setRunning(runningRef.current);
if (runningRef.current) rafId.current = requestAnimationFrame(() => {});
};
const handleWidthChange = (e) => {
const w = parseFloat(e.target.value);
setLineWidth(w);
routes.forEach((_, i) => {
map.current?.setPaintProperty(`arc-line-${i}`, 'line-width', w);
map.current?.setPaintProperty(`arc-glow-${i}`, 'line-width', w * 3);
});
};
return (
);
};
export default ArcLayer;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Change Building Color Based on Zoom Level
https://docs.mapatlas.xyz/sdk/examples/building-color-zoom
---
title: "Change Building Color Based on Zoom Level"
category: "labels"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addLayer", "setPaintProperty", "fill-extrusion-color", "interpolate", "zoom"]
tags: ["building", "3D", "zoom", "color", "fill-extrusion", "interpolate", "zoom-based", "style"]
description: "Style 3D buildings with colors that change dynamically based on the current zoom level"
---
# Change Building Color Based on Zoom Level
Use the `interpolate` expression with `zoom` to change 3D building colors as the user zooms in and out.
Zoom in to see building colors transition from grey → blue → gold.
## Zoom-Based Color with `interpolate`
Use the `interpolate` expression with `['zoom']` as the input to smoothly transition colors between zoom levels:
```javascript
// Add your building polygons as a GeoJSON source
map.addSource('buildings', {
type: 'geojson',
data: {
type: 'FeatureCollection',
features: [
{ type: 'Feature', properties: { height: 80 }, geometry: { type: 'Polygon', coordinates: [[[lng1,lat1],[lng2,lat1],[lng2,lat2],[lng1,lat2],[lng1,lat1]]] } },
// ... more building polygons
]
}
});
map.addLayer({
id: 'buildings-3d',
type: 'fill-extrusion',
source: 'buildings',
paint: {
'fill-extrusion-height': ['get', 'height'],
'fill-extrusion-base': 0,
'fill-extrusion-opacity': 0.85,
// Color changes based on zoom
'fill-extrusion-color': [
'interpolate',
['linear'],
['zoom'],
13, '#94a3b8', // grey at zoom 13
15, '#3b82f6', // blue at zoom 15
17, '#f59e0b', // gold at zoom 17+
],
}
});
```
## Step-Based Color (Discrete Jumps)
Use `step` for discrete color jumps instead of smooth transitions:
```javascript
'fill-extrusion-color': [
'step',
['zoom'],
'#94a3b8', // default (zoom < 14)
14, '#3b82f6', // zoom >= 14 → blue
16, '#f59e0b', // zoom >= 16 → gold
18, '#ef4444', // zoom >= 18 → red
]
```
## Update Color at Runtime
```javascript
map.setPaintProperty('buildings-3d', 'fill-extrusion-color', [
'interpolate', ['linear'], ['zoom'],
13, '#e2e8f0',
16, '#22c55e',
]);
```
## Also Apply to Height and Opacity
```javascript
paint: {
// Height from data
'fill-extrusion-height': ['get', 'height'],
'fill-extrusion-base': ['get', 'min_height'],
// Fade in as zoom increases
'fill-extrusion-opacity': [
'interpolate', ['linear'], ['zoom'],
13, 0, // invisible at zoom 13
14, 0.85 // fully visible at zoom 14
],
// Color by zoom
'fill-extrusion-color': [
'interpolate', ['linear'], ['zoom'],
14, '#94a3b8',
17, '#3b82f6',
],
}
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const BuildingColorZoom = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.3522, 48.8566],
zoom: 14,
pitch: 45,
bearing: -17
});
map.current.on('load', () => {
const geojsonBuildings = {
type: 'FeatureCollection',
features: [
{ type: 'Feature', properties: { height: 80 }, geometry: { type: 'Polygon', coordinates: [[[2.348,48.858],[2.350,48.858],[2.350,48.860],[2.348,48.860],[2.348,48.858]]] } },
{ type: 'Feature', properties: { height: 120 }, geometry: { type: 'Polygon', coordinates: [[[2.351,48.857],[2.353,48.857],[2.353,48.860],[2.351,48.860],[2.351,48.857]]] } },
{ type: 'Feature', properties: { height: 200 }, geometry: { type: 'Polygon', coordinates: [[[2.344,48.856],[2.347,48.856],[2.347,48.859],[2.344,48.859],[2.344,48.856]]] } },
{ type: 'Feature', properties: { height: 50 }, geometry: { type: 'Polygon', coordinates: [[[2.354,48.858],[2.356,48.858],[2.356,48.859],[2.354,48.859],[2.354,48.858]]] } },
]
};
map.current.addSource('buildings', { type: 'geojson', data: geojsonBuildings });
map.current.addLayer({
id: 'buildings-3d',
type: 'fill-extrusion',
source: 'buildings',
paint: {
'fill-extrusion-height': ['get', 'height'],
'fill-extrusion-base': 0,
'fill-extrusion-opacity': 0.85,
'fill-extrusion-color': [
'interpolate', ['linear'], ['zoom'],
13, '#94a3b8',
15, '#3b82f6',
17, '#f59e0b',
],
}
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default BuildingColorZoom;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Change the Case of Labels
https://docs.mapatlas.xyz/sdk/examples/change-label-case
---
title: "Change the Case of Labels"
category: "labels"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "setLayoutProperty", "text-transform", "uppercase", "lowercase", "none"]
tags: ["label", "case", "text-transform", "uppercase", "lowercase", "capitalize", "symbol", "text"]
description: "Transform map label text to uppercase, lowercase, or default case using text-transform"
---
# Change the Case of Labels
Use the `text-transform` layout property to render map labels in uppercase, lowercase, or default case.
Default Case
UPPERCASE
lowercase
## `text-transform` Property
Set `text-transform` in a symbol layer's `layout` to control label casing:
```javascript
map.addLayer({
id: 'my-labels',
type: 'symbol',
source: 'my-source',
layout: {
'text-field': ['get', 'name'],
'text-transform': 'uppercase', // 'none' | 'uppercase' | 'lowercase'
}
});
```
## Update at Runtime
```javascript
// Apply to a specific layer
map.setLayoutProperty('my-labels', 'text-transform', 'uppercase');
// Apply to ALL symbol layers in the style
map.getStyle().layers.forEach(layer => {
if (layer.type === 'symbol') {
map.setLayoutProperty(layer.id, 'text-transform', 'uppercase');
}
});
```
## Values
| Value | Effect |
|---|---|
| `'none'` | Use the text as-is from the data (default) |
| `'uppercase'` | Convert all characters to uppercase |
| `'lowercase'` | Convert all characters to lowercase |
## Data-Driven Case (per feature)
```javascript
'text-transform': [
'match',
['get', 'type'],
'highway', 'uppercase',
'suburb', 'lowercase',
'none' // default
]
```
## Complete Example
```html
Default
UPPERCASE
lowercase
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const ChangeLabelCase = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [10, 50],
zoom: 4
});
return () => { map.current?.remove(); map.current = null; };
}, []);
const setCase = (val) => {
if (!map.current) return;
map.current.getStyle().layers.forEach(layer => {
if (layer.type === 'symbol') {
map.current.setLayoutProperty(layer.id, 'text-transform', val);
}
});
};
const btnStyle = (bg) => ({
padding: '8px 14px', background: bg, color: 'white',
border: 'none', borderRadius: 6, cursor: 'pointer'
});
return (
setCase('none')} style={btnStyle('#6b7280')}>Default
setCase('uppercase')} style={btnStyle('#3b82f6')}>UPPERCASE
setCase('lowercase')} style={btnStyle('#8b5cf6')}>lowercase
);
};
export default ChangeLabelCase;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Change a Layer's Color with Buttons
https://docs.mapatlas.xyz/sdk/examples/change-layer-color
---
title: "Change a Layer's Color with Buttons"
category: "styling"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "setPaintProperty", "addLayer", "addSource"]
tags: ["color", "setPaintProperty", "style", "layer", "dynamic", "buttons", "theme"]
description: "Dynamically change a map layer's color at runtime using setPaintProperty"
---
# Change a Layer's Color with Buttons
Use `setPaintProperty()` to update a layer's color dynamically without reloading the map.
Blue
Red
Green
Purple
Orange
## setPaintProperty
```javascript
// Change fill color
map.setPaintProperty('my-layer', 'fill-color', '#ef4444');
// Change line color and width
map.setPaintProperty('my-line-layer', 'line-color', '#22c55e');
map.setPaintProperty('my-line-layer', 'line-width', 5);
// Change circle radius and color
map.setPaintProperty('my-circle-layer', 'circle-color', '#8b5cf6');
map.setPaintProperty('my-circle-layer', 'circle-radius', 15);
// Change opacity
map.setPaintProperty('my-layer', 'fill-opacity', 0.8);
```
## setLayoutProperty
For layout properties (visibility, text, icon):
```javascript
// Toggle layer visibility
map.setLayoutProperty('my-layer', 'visibility', 'none'); // hide
map.setLayoutProperty('my-layer', 'visibility', 'visible'); // show
```
## Complete Example
```html
Blue
Red
Green
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const colors = ['#3b82f6', '#ef4444', '#22c55e', '#8b5cf6', '#f59e0b'];
const ChangeLayerColor = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({ container: mapContainer.current, style: '', center: [2.35, 48.85], zoom: 4 });
map.current.on('load', () => {
map.current.addSource('polygon', { type: 'geojson', data: { type: 'Feature', geometry: { type: 'Polygon', coordinates: [[[-4.5,48],[8.2,48],[7.5,43.5],[3,42.5],[-1.8,43.4],[-4.5,48]]] } } });
map.current.addLayer({ id: 'polygon-fill', type: 'fill', source: 'polygon', paint: { 'fill-color': '#3b82f6', 'fill-opacity': 0.5 } });
});
return () => { map.current?.remove(); map.current = null; };
}, []);
const setColor = (color) => {
map.current?.setPaintProperty('polygon-fill', 'fill-color', color);
};
return (
{colors.map(c => (
setColor(c)} style={{ padding: '8px 16px', background: c, color: 'white', border: 'none', borderRadius: '6px', cursor: 'pointer' }}>
{c}
))}
);
};
export default ChangeLayerColor;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Customize Camera Animations
https://docs.mapatlas.xyz/sdk/examples/customize-camera-animations
---
title: "Customize Camera Animations"
category: "camera"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "flyTo", "easeTo", "jumpTo", "AnimationOptions", "CameraOptions"]
tags: ["camera", "animation", "flyTo", "easeTo", "jumpTo", "duration", "easing", "curve", "speed"]
description: "Control camera animation speed, easing curves, and behavior with flyTo and easeTo options"
---
# Customize Camera Animations
Fine-tune how the map camera moves using animation options like `duration`, `easing`, `curve`, and `speed` with `flyTo()` and `easeTo()`.
Fast Fly
Slow Fly
Ease To
Jump To
Linear Ease
## `flyTo` — Flight Animation
`flyTo` zooms out, pans, and zooms back in, simulating a flight arc.
```javascript
map.flyTo({
center: [lng, lat],
zoom: 12,
speed: 1.2, // how fast to fly (default 1.2)
curve: 1.42, // arc height (higher = more zoom-out)
duration: 3000, // ms (overrides speed if set)
essential: true, // not affected by prefers-reduced-motion
});
```
## `easeTo` — Smooth Pan/Zoom
`easeTo` smoothly transitions all camera properties simultaneously.
```javascript
map.easeTo({
center: [lng, lat],
zoom: 10,
bearing: 45,
pitch: 30,
duration: 2000,
easing: t => t * (2 - t), // ease-out quadratic
});
```
## `jumpTo` — Instant Move
`jumpTo` moves the camera immediately with no animation.
```javascript
map.jumpTo({
center: [lng, lat],
zoom: 12,
bearing: 0,
pitch: 0,
});
```
## Custom Easing Functions
The `easing` option takes a function `(t) => number` where `t` goes from 0 to 1:
```javascript
// Linear (no easing)
easing: t => t
// Ease-in (slow start)
easing: t => t * t
// Ease-out (slow end)
easing: t => t * (2 - t)
// Ease-in-out
easing: t => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t
// Bounce
easing: t => {
if (t < 1 / 2.75) return 7.5625 * t * t;
if (t < 2 / 2.75) { t -= 1.5 / 2.75; return 7.5625 * t * t + 0.75; }
if (t < 2.5 / 2.75) { t -= 2.25 / 2.75; return 7.5625 * t * t + 0.9375; }
t -= 2.625 / 2.75;
return 7.5625 * t * t + 0.984375;
}
```
## Animation Events
```javascript
map.on('movestart', () => console.log('camera started moving'));
map.on('move', () => console.log('camera moving'));
map.on('moveend', () => console.log('camera stopped'));
map.on('zoomend', () => console.log('zoom finished'));
```
## Complete Example
```html
Fast Fly
Slow Fly
Ease To
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const CustomizeCameraAnimations = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.35, 48.85],
zoom: 4
});
return () => { map.current?.remove(); map.current = null; };
}, []);
const flyFast = () => map.current?.flyTo({ center: [-74, 40.7], zoom: 10, speed: 3 });
const flySlow = () => map.current?.flyTo({ center: [139.7, 35.7], zoom: 10, speed: 0.3, duration: 5000 });
const easeTo = () => map.current?.easeTo({
center: [2.35, 48.85], zoom: 10,
duration: 2000,
easing: t => t * (2 - t)
});
const jumpTo = () => map.current?.jumpTo({ center: [-43.2, -22.9], zoom: 10 });
return (
Fast Fly
Slow Fly
Ease To
Jump To
);
};
export default CustomizeCameraAnimations;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Customize the Map Transform Constrain
https://docs.mapatlas.xyz/sdk/examples/customize-map-transform-constrain
---
title: "Customize the Map Transform Constrain"
category: "camera"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "transformRequest", "transformCameraUpdate", "maxBounds", "setMaxBounds", "setMinZoom", "setMaxZoom"]
tags: ["constrain", "transform", "bounds", "zoom", "maxBounds", "transformCameraUpdate", "restrict", "limit"]
description: "Constrain the map camera to specific bounds, zoom levels, and custom transform rules"
---
# Customize the Map Transform Constrain
Control how and where the map camera can move by setting bounds, zoom limits, and using `transformCameraUpdate` to enforce custom constraints.
Lock to Europe
Unlock
Limit Zoom 3–8
Reset Zoom
## Set Max Bounds
Restrict panning so the camera cannot move outside a bounding box:
```javascript
// At initialization
const map = new mapmetricsgl.Map({
container: 'map',
style: '',
maxBounds: [[-25, 34], [45, 72]], // [SW, NE]
});
// At runtime
map.setMaxBounds([[-25, 34], [45, 72]]);
// Remove constraint
map.setMaxBounds(null);
```
## Limit Zoom Levels
```javascript
// At initialization
const map = new mapmetricsgl.Map({
minZoom: 3,
maxZoom: 18,
// ...
});
// At runtime
map.setMinZoom(3);
map.setMaxZoom(12);
// Remove limits
map.setMinZoom(null);
map.setMaxZoom(null);
```
## Limit Pitch and Bearing
```javascript
const map = new mapmetricsgl.Map({
minPitch: 0,
maxPitch: 60, // default 60
// ...
});
```
## `transformCameraUpdate` — Custom Constraints
Use `transformCameraUpdate` to intercept and modify every camera update before it is applied:
```javascript
const map = new mapmetricsgl.Map({
// ...
transformCameraUpdate: ({ center, zoom, pitch, bearing, elevation, padding }) => {
// Example: keep latitude above the equator
return {
center: {
lng: center.lng,
lat: Math.max(0, center.lat), // clamp lat to >= 0
},
zoom,
pitch,
bearing,
};
}
});
```
## Complete Example
```html
Lock to Europe
Unlock
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const europeBounds = [[-25, 34], [45, 72]];
const CustomizeMapTransformConstrain = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [10, 50],
zoom: 4,
minZoom: 2,
});
return () => { map.current?.remove(); map.current = null; };
}, []);
const lock = () => {
map.current?.setMaxBounds(europeBounds);
map.current?.fitBounds(europeBounds, { padding: 20 });
};
const unlock = () => map.current?.setMaxBounds(null);
return (
);
};
export default CustomizeMapTransformConstrain;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Style Lines with a Data-Driven Property
https://docs.mapatlas.xyz/sdk/examples/data-driven-lines
---
title: "Style Lines with a Data-Driven Property"
category: "lines-polygons"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addSource", "addLayer", "line-color", "line-width", "get expression"]
tags: ["line", "data-driven", "style", "expression", "geojson", "layer", "properties", "color", "width"]
description: "Style map lines dynamically based on feature properties using data-driven expressions"
---
# Style Lines with a Data-Driven Property
Change line color and width based on feature data properties using MapMetrics GL expressions.
Lines are styled by speed property: 🔴 fast highway · 🟡 medium road · 🟢 slow street
## How It Works
Use MapMetrics GL **expressions** in layer paint properties to read feature properties and apply styles dynamically.
## Color by Property Value
### `match` expression — exact value matching
```javascript
'line-color': [
'match', ['get', 'type'],
'highway', '#ef4444', // red for highways
'road', '#eab308', // yellow for roads
'street', '#22c55e', // green for streets
'#94a3b8' // default (gray)
]
```
### `step` expression — numeric ranges
```javascript
'line-color': [
'step', ['get', 'speed'],
'#22c55e', // default (speed < 60)
60, '#eab308', // speed >= 60
100, '#ef4444' // speed >= 100
]
```
### `interpolate` expression — smooth gradient
```javascript
'line-color': [
'interpolate', ['linear'], ['get', 'speed'],
0, '#22c55e', // green at 0 km/h
60, '#eab308', // yellow at 60 km/h
130, '#ef4444' // red at 130 km/h
]
```
## Width by Property
```javascript
'line-width': [
'interpolate', ['linear'], ['get', 'speed'],
0, 1, // thin at slow speed
130, 8 // thick at high speed
]
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const roadsData = {
type: 'FeatureCollection',
features: [
{ type: 'Feature', properties: { name: 'Highway', type: 'highway', speed: 130 },
geometry: { type: 'LineString', coordinates: [[2.35, 48.85], [5.0, 47.5]] } },
{ type: 'Feature', properties: { name: 'Road', type: 'road', speed: 80 },
geometry: { type: 'LineString', coordinates: [[2.35, 48.85], [2.5, 47.0]] } },
{ type: 'Feature', properties: { name: 'Street', type: 'street', speed: 30 },
geometry: { type: 'LineString', coordinates: [[2.35, 48.85], [1.0, 49.5]] } },
]
};
const DataDrivenLines = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.349902, 48.852966],
zoom: 5
});
map.current.on('load', () => {
map.current.addSource('roads', { type: 'geojson', data: roadsData });
map.current.addLayer({
id: 'roads-layer',
type: 'line',
source: 'roads',
paint: {
'line-color': ['step', ['get', 'speed'], '#22c55e', 60, '#eab308', 100, '#ef4444'],
'line-width': ['match', ['get', 'type'], 'highway', 5, 'road', 3, 'street', 1.5, 2]
}
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default DataDrivenLines;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Disable Map Rotation
https://docs.mapatlas.xyz/sdk/examples/disable-map-rotation
---
title: "Disable Map Rotation"
category: "controls"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "dragRotate", "touchZoomRotate", "keyboard"]
tags: ["rotation", "disable", "lock", "bearing", "dragRotate", "touchZoomRotate", "controls"]
description: "Disable map rotation from mouse drag, touch gestures, and keyboard shortcuts"
---
# Disable Map Rotation
Prevent users from rotating the map by disabling drag-rotate, touch-rotate, and keyboard rotation.
Try right-click dragging or using the compass — rotation is disabled on this map.
## How to Disable Rotation
Call these three methods after map initialization to fully disable rotation from all input sources:
```javascript
// Disable right-click drag rotation (mouse)
map.dragRotate.disable();
// Disable two-finger rotation (touch devices)
map.touchZoomRotate.disableRotation();
// Disable keyboard rotation (Alt + Arrow keys)
map.keyboard.disable();
```
## Disable at Initialization
You can also disable rotation when creating the map:
```javascript
const map = new mapmetricsgl.Map({
container: 'map',
style: '',
center: [0, 20],
zoom: 2,
dragRotate: false // disable drag rotation at init
});
// Still need to disable touch rotation separately
map.touchZoomRotate.disableRotation();
```
## Re-enable Rotation
```javascript
// Re-enable rotation later if needed
map.dragRotate.enable();
map.touchZoomRotate.enableRotation();
map.keyboard.enable();
```
## Hide the Compass
If rotation is disabled, you can also hide the compass from `NavigationControl`:
```javascript
map.addControl(new mapmetricsgl.NavigationControl({
showCompass: false // hide compass since rotation is disabled
}), 'top-right');
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const DisableRotation = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.349902, 48.852966],
zoom: 5
});
map.current.addControl(new mapmetricsgl.NavigationControl({
showCompass: false
}), 'top-right');
// Disable all rotation
map.current.dragRotate.disable();
map.current.touchZoomRotate.disableRotation();
map.current.keyboard.disable();
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default DisableRotation;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Disable Scroll Zoom
https://docs.mapatlas.xyz/sdk/examples/disable-scroll-zoom
---
title: "Disable Scroll Zoom"
category: "controls"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "scrollZoom", "doubleClickZoom", "touchZoomRotate"]
tags: ["scroll", "zoom", "disable", "scrollZoom", "touch", "interaction", "controls"]
description: "Disable scroll wheel zoom and touch pinch zoom to prevent accidental map zooming"
---
# Disable Scroll Zoom
Disable scroll wheel zooming to prevent the map from accidentally zooming when users scroll the page.
Try scrolling over the map — scroll zoom is disabled. Use the +/− buttons or pinch to zoom.
## Disable Scroll Zoom
```javascript
// Disable scroll wheel zoom
map.scrollZoom.disable();
// Re-enable later if needed
map.scrollZoom.enable();
```
## Disable at Initialization
```javascript
const map = new mapmetricsgl.Map({
container: 'map',
style: '',
center: [0, 20],
zoom: 2,
scrollZoom: false // disable scroll zoom at init
});
```
## Disable All Zoom Interactions
```javascript
// Disable scroll wheel zoom
map.scrollZoom.disable();
// Disable double-click zoom
map.doubleClickZoom.disable();
// Disable touch pinch zoom (keeps rotation)
map.touchZoomRotate.disable();
```
## Common Use Case: Embed in a Scrollable Page
When embedding a map in a long scrollable page, scroll zoom causes a frustrating experience. The recommended pattern is to only enable scroll zoom when the user clicks/focuses the map:
```javascript
map.scrollZoom.disable();
// Enable on map focus
map.getCanvas().addEventListener('focus', () => {
map.scrollZoom.enable();
});
// Disable when leaving map
map.getCanvas().addEventListener('blur', () => {
map.scrollZoom.disable();
});
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const DisableScrollZoom = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.349902, 48.852966],
zoom: 5,
scrollZoom: false
});
map.current.addControl(new mapmetricsgl.NavigationControl(), 'top-right');
const canvas = map.current.getCanvas();
canvas.addEventListener('focus', () => map.current.scrollZoom.enable());
canvas.addEventListener('blur', () => map.current.scrollZoom.disable());
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default DisableScrollZoom;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Display a Popup
https://docs.mapatlas.xyz/sdk/examples/display-popup
---
title: "Display a Popup"
category: "popups"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "Popup", "setLngLat", "setHTML", "addTo", "remove"]
tags: ["popup", "tooltip", "click", "marker", "info", "overlay", "html"]
description: "Display a popup at a specific location on the map with custom HTML content"
---
# Display a Popup
Show a popup with custom HTML at a specific map location, or trigger it from a marker or click event.
Paris
London
Berlin
Close Popup
## Basic Popup
```javascript
const popup = new mapmetricsgl.Popup({ closeButton: true, closeOnClick: true })
.setLngLat([2.3499, 48.853])
.setHTML('Paris Title Description
');
// Set coordinates
popup.setLngLat([lng, lat]);
```
## Attach Popup to Marker
```javascript
const marker = new mapmetricsgl.Marker()
.setLngLat([2.3499, 48.853])
.setPopup(
new mapmetricsgl.Popup().setHTML('Paris ')
)
.addTo(map);
// Open/close programmatically
marker.togglePopup();
```
## Popup on Feature Click
```javascript
map.on('click', 'my-layer', (e) => {
const feature = e.features[0];
new mapmetricsgl.Popup()
.setLngLat(e.lngLat)
.setHTML(`${feature.properties.name} `)
.addTo(map);
});
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const DisplayPopup = () => {
const mapContainer = useRef(null);
const map = useRef(null);
const popup = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.3499, 48.853],
zoom: 5
});
map.current.on('load', () => {
// Show popup at a fixed location
popup.current = new mapmetricsgl.Popup({ closeButton: true })
.setLngLat([2.3499, 48.853])
.setHTML('Paris
;
};
export default DisplayPopup;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Display a Remote SVG Symbol
https://docs.mapatlas.xyz/sdk/examples/display-remote-svg-symbol
---
title: "Display a Remote SVG Symbol"
category: "icons-images"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addImage", "addSource", "addLayer", "fetch", "Image", "icon-image"]
tags: ["svg", "symbol", "remote", "icon", "fetch", "image", "addImage", "url", "external"]
description: "Fetch an SVG from a URL and render it as a map icon using a canvas"
---
# Display a Remote SVG Symbol
Fetch an SVG from a remote URL, render it onto a canvas using an `Image` element, and register it with `map.addImage()` for use in symbol layers.
## Approach: SVG → Blob → Image → Canvas → addImage
SVG images cannot be passed directly to `map.addImage()`. The recommended workflow is:
1. Get the SVG string (inline or fetched)
2. Create a `Blob` and object URL from the SVG
3. Draw it onto a `` via an `Image` element
4. Extract `ImageData` and register with `map.addImage()`
```javascript
function svgToImageData(svgString, size) {
return new Promise((resolve, reject) => {
const blob = new Blob([svgString], { type: 'image/svg+xml' });
const url = URL.createObjectURL(blob);
const img = new Image(size, size);
img.onload = () => {
const canvas = document.createElement('canvas');
canvas.width = size;
canvas.height = size;
canvas.getContext('2d').drawImage(img, 0, 0, size, size);
URL.revokeObjectURL(url);
resolve(canvas.getContext('2d').getImageData(0, 0, size, size));
};
img.onerror = reject;
img.src = url;
});
}
```
## Fetch SVG from a Remote URL
```javascript
async function loadRemoteSvg(url, size) {
const response = await fetch(url);
const svgText = await response.text();
return svgToImageData(svgText, size);
}
map.on('load', async () => {
const imageData = await loadRemoteSvg('https://example.com/pin.svg', 48);
map.addImage('remote-svg', imageData);
// Use in a symbol layer
map.addLayer({
id: 'svg-layer',
type: 'symbol',
source: 'my-source',
layout: {
'icon-image': 'remote-svg',
'icon-size': 1.0,
'icon-allow-overlap': true,
}
});
});
```
## Using an Inline SVG String
```javascript
const svg = `
`;
svgToImageData(svg, 48).then(imageData => {
map.addImage('dot-icon', imageData);
});
```
## CORS Note
When fetching SVGs from external servers, the server must send `Access-Control-Allow-Origin: *`. If CORS is blocked, use an inline SVG string or a data URI instead.
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
function svgToImageData(svgString, size) {
return new Promise((resolve) => {
const blob = new Blob([svgString], { type: 'image/svg+xml' });
const url = URL.createObjectURL(blob);
const img = new Image(size, size);
img.onload = () => {
const canvas = document.createElement('canvas');
canvas.width = size; canvas.height = size;
canvas.getContext('2d').drawImage(img, 0, 0, size, size);
URL.revokeObjectURL(url);
resolve(canvas.getContext('2d').getImageData(0, 0, size, size));
};
img.src = url;
});
}
const svg = `
`;
const pointsData = {
type: 'FeatureCollection',
features: [
{ type: 'Feature', geometry: { type: 'Point', coordinates: [-74, 40.7] }, properties: {} },
{ type: 'Feature', geometry: { type: 'Point', coordinates: [2.35, 48.85] }, properties: {} },
{ type: 'Feature', geometry: { type: 'Point', coordinates: [139.7, 35.7] }, properties: {} },
]
};
const DisplayRemoteSvgSymbol = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [10, 30],
zoom: 1.5
});
map.current.on('load', async () => {
const imageData = await svgToImageData(svg, 48);
map.current.addImage('pin', imageData);
map.current.addSource('pts', { type: 'geojson', data: pointsData });
map.current.addLayer({
id: 'pins',
type: 'symbol',
source: 'pts',
layout: { 'icon-image': 'pin', 'icon-size': 1, 'icon-allow-overlap': true, 'icon-anchor': 'bottom' }
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default DisplayRemoteSvgSymbol;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Display the Globe
https://docs.mapatlas.xyz/sdk/examples/display-whole-world
# Display the Globe
This example demonstrates how to display a 3D globe view with an optional animated starfield background. You can toggle the stars effect on/off using the button below.
## Interactive Demo
---
## Code Implementation
Below are two implementation examples: one with the starfield effect and one without.
### Option 1: Globe with Stars Background (Full Interactive Experience)
This implementation includes:
- Animated starfield background with multiple layers
- Stars that rotate and move with globe interactions
- Parallax mouse effect for depth
- Toggle button to show/hide stars
```html
Hide Stars
```
### Option 2: Simple Globe (No Stars)
This is a basic implementation without the starfield effect - just the globe:
```html
```
---
## Key Features Explained
### Toggle Button
- **Location**: Top-right corner of the map
- **Initial State**: Stars are visible by default
- **Functionality**: Click to show/hide the starfield background
- **Button Text**: Changes between "Hide Stars" and "Show Stars"
### Stars Animation
The starfield includes:
1. **Multiple Star Layers**: Large bright stars, medium stars, and tiny distant stars
2. **Color Variety**: White, blue, yellow, orange, and other star colors for realism
3. **Twinkling Effect**: Stars gently pulse with opacity changes
4. **Interactive Rotation**: Stars rotate as you move the globe
5. **Smooth Transitions**: 0.3s fade effect when toggling visibility
### Globe Projection
- Uses `map.setProjection({ type: "globe" })` to display Earth in 3D
- Interactive rotation, pitch, and zoom
### Customization Options
**Change toggle button position:**
```css
#toggleStars {
top: 20px; /* Distance from top */
right: 20px; /* Distance from right */
}
```
**Adjust star intensity:**
```css
#stars::before {
opacity: 0.8; /* Reduce for dimmer stars */
}
```
---
## Browser Compatibility
This example works in all modern browsers that support:
- CSS animations
- CSS filter effects
- WebGL (for globe rendering)
- ES6 JavaScript
Tested on: Chrome, Firefox, Safari, Edge
---
# Create a Draggable Marker
https://docs.mapatlas.xyz/sdk/examples/draggable-marker
---
title: "Create a Draggable Marker"
category: "interaction"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "Marker", "on('dragend')", "getLngLat"]
tags: ["marker", "draggable", "drag", "dragend", "interaction", "lngLat"]
description: "Create markers that users can drag to new locations, and capture the new position"
---
# Create a Draggable Marker
Create markers that users can drag to any location on the map, and capture the updated coordinates.
🔵 Drag the blue marker to see its new coordinates
## How It Works
Pass `draggable: true` to the `Marker` constructor, then listen to `drag` and `dragend` events to get the new position.
## Basic Draggable Marker
```javascript
const marker = new mapmetricsgl.Marker({
color: '#3b82f6',
draggable: true // Enable dragging
})
.setLngLat([2.349902, 48.852966])
.addTo(map);
// Get new position when drag ends
marker.on('dragend', () => {
const { lng, lat } = marker.getLngLat();
console.log(`Marker dropped at: ${lng}, ${lat}`);
});
```
## Listen to All Drag Events
```javascript
// Fires when drag starts
marker.on('dragstart', () => {
console.log('Started dragging');
});
// Fires continuously while dragging
marker.on('drag', () => {
const pos = marker.getLngLat();
console.log(`Dragging: ${pos.lng}, ${pos.lat}`);
});
// Fires when drag ends
marker.on('dragend', () => {
const pos = marker.getLngLat();
console.log(`Dropped at: ${pos.lng}, ${pos.lat}`);
});
```
## Use Case: Pick-up / Drop-off Points
```javascript
const pickup = new mapmetricsgl.Marker({ color: '#22c55e', draggable: true })
.setLngLat([2.34, 48.85])
.addTo(map);
const dropoff = new mapmetricsgl.Marker({ color: '#ef4444', draggable: true })
.setLngLat([2.36, 48.86])
.addTo(map);
function getRoute() {
const from = pickup.getLngLat();
const to = dropoff.getLngLat();
console.log('From:', from, 'To:', to);
// Call Directions API with these coordinates
}
pickup.on('dragend', getRoute);
dropoff.on('dragend', getRoute);
```
## Complete Example
```html
🔵 Drag the marker to see coordinates
```
```jsx
import React, { useEffect, useRef, useState } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const DraggableMarker = () => {
const mapContainer = useRef(null);
const map = useRef(null);
const [position, setPosition] = useState(null);
const [dragging, setDragging] = useState(false);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.349902, 48.852966],
zoom: 11
});
map.current.addControl(new mapmetricsgl.NavigationControl(), 'top-right');
const marker = new mapmetricsgl.Marker({ color: '#3b82f6', draggable: true })
.setLngLat([2.349902, 48.852966])
.addTo(map.current);
marker.on('dragstart', () => setDragging(true));
marker.on('drag', () => {
const pos = marker.getLngLat();
setPosition({ lng: pos.lng.toFixed(5), lat: pos.lat.toFixed(5) });
});
marker.on('dragend', () => {
setDragging(false);
const pos = marker.getLngLat();
setPosition({ lng: pos.lng.toFixed(5), lat: pos.lat.toFixed(5) });
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return (
{position
? <>{dragging ? '✋ Dragging...' : '📍 Dropped at:'} Lng: {position.lng} | Lat: {position.lat}
: '🔵 Drag the marker to see its coordinates'
}
);
};
export default DraggableMarker;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Create a Draggable Point
https://docs.mapatlas.xyz/sdk/examples/draggable-point
---
title: "Create a Draggable Point"
category: "user-interaction"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addSource", "addLayer", "setData", "mousedown", "mousemove", "mouseup"]
tags: ["drag", "draggable", "point", "geojson", "interactive", "mouse", "move", "edit"]
description: "Create a draggable GeoJSON point that the user can move by clicking and dragging"
---
# Create a Draggable Point
Allow users to drag a GeoJSON point on the map using mouse events.
Click and drag the point to move it
## How It Works
1. Add a GeoJSON `Point` source and display it as a `circle` layer
2. Listen for `mousedown` on the layer to start dragging
3. On `mousemove`, update the point position with `setData()`
4. On `mouseup`, end the drag and re-enable map panning
## Key Pattern
```javascript
let isDragging = false;
// Start drag when user clicks the point
map.on('mousedown', 'my-point', (e) => {
e.preventDefault();
isDragging = true;
map.dragPan.disable(); // prevent map from panning
map.getCanvas().style.cursor = 'grabbing';
});
// Move point while dragging
map.on('mousemove', (e) => {
if (!isDragging) return;
map.getSource('my-point').setData({
type: 'Feature',
geometry: { type: 'Point', coordinates: [e.lngLat.lng, e.lngLat.lat] },
properties: {}
});
});
// End drag
map.on('mouseup', () => {
isDragging = false;
map.dragPan.enable();
map.getCanvas().style.cursor = '';
});
```
## Complete Example
```html
Drag the point
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const DraggablePoint = () => {
const mapContainer = useRef(null);
const map = useRef(null);
const isDragging = useRef(false);
const [coords, setCoords] = React.useState([0, 20]);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [0, 20],
zoom: 2
});
map.current.on('load', () => {
map.current.addSource('point', {
type: 'geojson',
data: { type: 'Feature', geometry: { type: 'Point', coordinates: [0, 20] }, properties: {} }
});
map.current.addLayer({
id: 'point',
type: 'circle',
source: 'point',
paint: { 'circle-radius': 10, 'circle-color': '#3b82f6', 'circle-stroke-width': 3, 'circle-stroke-color': '#fff' }
});
map.current.on('mousedown', 'point', (e) => {
e.preventDefault();
isDragging.current = true;
map.current.dragPan.disable();
map.current.getCanvas().style.cursor = 'grabbing';
});
map.current.on('mousemove', (e) => {
if (!isDragging.current) return;
const newCoords = [e.lngLat.lng, e.lngLat.lat];
map.current.getSource('point').setData({
type: 'Feature',
geometry: { type: 'Point', coordinates: newCoords },
properties: {}
});
setCoords(newCoords);
});
map.current.on('mouseup', () => {
isDragging.current = false;
map.current.dragPan.enable();
map.current.getCanvas().style.cursor = '';
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return (
Position: [{coords[0].toFixed(4)}, {coords[1].toFixed(4)}]
);
};
export default DraggablePoint;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Draw a Circle
https://docs.mapatlas.xyz/sdk/examples/draw-a-circle
---
title: "Draw a Circle"
category: "lines-polygons"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "addSource", "addLayer", "circle-radius", "circle-color", "fill"]
tags: ["circle", "polygon", "draw", "radius", "geojson", "layer", "shape", "area"]
description: "Draw circles and filled areas on the map using circle layers or polygon GeoJSON"
---
# Draw a Circle
Draw circles on the map using the `circle` layer type or as filled polygon areas.
Click the map to add a circle at that location.
## Method 1: Circle Layer (Pixel-based)
The simplest way — uses pixel radius, so the circle size stays constant regardless of zoom level:
```javascript
map.addSource('points', {
type: 'geojson',
data: {
type: 'FeatureCollection',
features: [
{ type: 'Feature', geometry: { type: 'Point', coordinates: [2.35, 48.85] }, properties: {} }
]
}
});
map.addLayer({
id: 'circle-layer',
type: 'circle',
source: 'points',
paint: {
'circle-radius': 20, // pixels
'circle-color': '#3b82f6',
'circle-opacity': 0.5,
'circle-stroke-width': 2,
'circle-stroke-color': '#1d4ed8'
}
});
```
## Method 2: Polygon Circle (Geographic radius)
For a circle with a real-world radius (e.g., 5km), generate polygon coordinates:
```javascript
function createGeoCircle(center, radiusKm, points = 64) {
const coords = [];
for (let i = 0; i < points; i++) {
const angle = (i / points) * 2 * Math.PI;
const dx = radiusKm / 111.32; // degrees longitude
const dy = radiusKm / 110.574; // degrees latitude
coords.push([
center[0] + dx * Math.cos(angle),
center[1] + dy * Math.sin(angle)
]);
}
coords.push(coords[0]); // close the ring
return coords;
}
map.addSource('area', {
type: 'geojson',
data: {
type: 'Feature',
geometry: {
type: 'Polygon',
coordinates: [createGeoCircle([2.35, 48.85], 50)] // 50km radius
}
}
});
map.addLayer({
id: 'area-fill',
type: 'fill',
source: 'area',
paint: {
'fill-color': '#3b82f6',
'fill-opacity': 0.2
}
});
map.addLayer({
id: 'area-outline',
type: 'line',
source: 'area',
paint: {
'line-color': '#3b82f6',
'line-width': 2
}
});
```
## Data-Driven Circle Size
```javascript
map.addLayer({
id: 'circles',
type: 'circle',
source: 'points',
paint: {
'circle-radius': ['get', 'radius'], // from feature property
'circle-color': ['get', 'color'], // from feature property
'circle-opacity': 0.6
}
});
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const DrawCircle = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.349902, 48.852966],
zoom: 5
});
map.current.addControl(new mapmetricsgl.NavigationControl(), 'top-right');
const data = {
type: 'FeatureCollection',
features: [
{ type: 'Feature', properties: {}, geometry: { type: 'Point', coordinates: [2.349902, 48.852966] } },
{ type: 'Feature', properties: {}, geometry: { type: 'Point', coordinates: [-0.1276, 51.5074] } },
]
};
map.current.on('load', () => {
map.current.addSource('points', { type: 'geojson', data });
map.current.addLayer({
id: 'circles',
type: 'circle',
source: 'points',
paint: {
'circle-radius': 20,
'circle-color': '#3b82f6',
'circle-opacity': 0.5,
'circle-stroke-width': 2,
'circle-stroke-color': '#1d4ed8'
}
});
map.current.on('click', (e) => {
data.features.push({
type: 'Feature', properties: {},
geometry: { type: 'Point', coordinates: [e.lngLat.lng, e.lngLat.lat] }
});
map.current.getSource('points').setData({ ...data });
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default DrawCircle;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Draw GeoJSON Points
https://docs.mapatlas.xyz/sdk/examples/draw-geojson-points
---
title: "Draw GeoJSON Points"
category: "geometry"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "addSource", "addLayer", "circle", "Point", "FeatureCollection"]
tags: ["points", "geojson", "circle", "dot", "marker", "layer", "data"]
description: "Draw multiple points on the map from a GeoJSON FeatureCollection using a circle layer"
---
# Draw GeoJSON Points
Render multiple points from a GeoJSON FeatureCollection using a circle layer — efficient for large datasets.
## GeoJSON Points vs Markers
| | GeoJSON + Circle Layer | Marker |
|---|---|---|
| **Performance** | Excellent (WebGL rendered) | Good (DOM elements) |
| **Best for** | Hundreds/thousands of points | Few points with rich HTML |
| **Clustering** | Built-in support | Manual |
| **Custom HTML** | No | Yes |
## Draw Points from GeoJSON
```javascript
map.addSource('points', {
type: 'geojson',
data: {
type: 'FeatureCollection',
features: [
{
type: 'Feature',
properties: { name: 'Paris' },
geometry: { type: 'Point', coordinates: [2.35, 48.85] }
},
{
type: 'Feature',
properties: { name: 'London' },
geometry: { type: 'Point', coordinates: [-0.12, 51.50] }
}
]
}
});
map.addLayer({
id: 'points-layer',
type: 'circle',
source: 'points',
paint: {
'circle-radius': 8,
'circle-color': '#3b82f6',
'circle-stroke-width': 2,
'circle-stroke-color': '#fff'
}
});
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const pointsData = {
type: 'FeatureCollection',
features: [
{ type: 'Feature', properties: { name: 'Paris' }, geometry: { type: 'Point', coordinates: [2.349902, 48.852966] } },
{ type: 'Feature', properties: { name: 'London' }, geometry: { type: 'Point', coordinates: [-0.1276, 51.5074] } },
{ type: 'Feature', properties: { name: 'Berlin' }, geometry: { type: 'Point', coordinates: [13.405, 52.52] } },
]
};
const GeoJSONPoints = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [10, 50],
zoom: 3
});
map.current.on('load', () => {
map.current.addSource('points', { type: 'geojson', data: pointsData });
map.current.addLayer({
id: 'points-layer',
type: 'circle',
source: 'points',
paint: { 'circle-radius': 8, 'circle-color': '#3b82f6', 'circle-stroke-width': 2, 'circle-stroke-color': '#fff' }
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default GeoJSONPoints;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Filter Symbols by Text Input
https://docs.mapatlas.xyz/sdk/examples/filter-by-text-input
---
title: "Filter Symbols by Text Input"
category: "filtering"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "setFilter", "addSource", "addLayer"]
tags: ["filter", "search", "text", "input", "setFilter", "layer", "dynamic"]
description: "Filter map features in real time as the user types in a search input"
---
# Filter Symbols by Text Input
Filter map features dynamically as the user types in a search box using `setFilter()`.
## Filter by Text Input
```javascript
const searchInput = document.getElementById('search');
searchInput.addEventListener('input', (e) => {
const query = e.target.value.trim().toLowerCase();
if (!query) {
map.setFilter('my-layer', null); // show all
return;
}
// Filter: feature name contains the query string
map.setFilter('my-layer', [
'in',
query,
['downcase', ['get', 'name']]
]);
});
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef, useState } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const citiesData = {
type: 'FeatureCollection',
features: [
{ type: 'Feature', properties: { name: 'Paris' }, geometry: { type: 'Point', coordinates: [2.349902, 48.852966] } },
{ type: 'Feature', properties: { name: 'London' }, geometry: { type: 'Point', coordinates: [-0.1276, 51.5074] } },
{ type: 'Feature', properties: { name: 'Berlin' }, geometry: { type: 'Point', coordinates: [13.405, 52.52] } },
]
};
const FilterByText = () => {
const mapContainer = useRef(null);
const map = useRef(null);
const [query, setQuery] = useState('');
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({ container: mapContainer.current, style: '', center: [10, 50], zoom: 3 });
map.current.on('load', () => {
map.current.addSource('cities', { type: 'geojson', data: citiesData });
map.current.addLayer({ id: 'cities-layer', type: 'circle', source: 'cities', paint: { 'circle-radius': 9, 'circle-color': '#3b82f6' } });
});
return () => { map.current?.remove(); map.current = null; };
}, []);
const handleSearch = (e) => {
const q = e.target.value.toLowerCase();
setQuery(q);
if (!map.current) return;
map.current.setFilter('cities-layer', q ? ['in', q, ['downcase', ['get', 'name']]] : null);
};
return (
);
};
export default FilterByText;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Filter Features by Toggle List
https://docs.mapatlas.xyz/sdk/examples/filter-by-toggle-list
---
title: "Filter Features by Toggle List"
category: "user-interaction"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addSource", "addLayer", "setFilter", "filter expression", "in expression"]
tags: ["filter", "toggle", "checkbox", "category", "buttons", "setFilter", "layer", "interactive"]
description: "Filter map features by toggling category buttons that show or hide specific feature types"
---
# Filter Features by Toggle List
Toggle category buttons to show or hide specific feature types on the map using `setFilter()`.
Toggle categories:
🍕 Restaurant
☕ Cafe
🏨 Hotel
🏛️ Museum
🌿 Park
## Filter by Active Categories
Track which categories are selected, then build a filter expression:
```javascript
const activeCategories = new Set(['restaurant', 'cafe', 'hotel']);
function applyFilter() {
const active = [...activeCategories];
if (active.length === 0) {
// Hide everything
map.setFilter('places-layer', ['==', '1', '0']);
} else {
// Show features whose category is in the active list
map.setFilter('places-layer', [
'in',
['get', 'category'],
['literal', active]
]);
}
}
// Toggle a category on/off
function toggleCategory(category) {
if (activeCategories.has(category)) {
activeCategories.delete(category);
} else {
activeCategories.add(category);
}
applyFilter();
}
```
## Filter Expressions
```javascript
// Show only restaurants
map.setFilter('layer', ['==', ['get', 'category'], 'restaurant']);
// Show restaurants OR cafes
map.setFilter('layer', [
'in',
['get', 'category'],
['literal', ['restaurant', 'cafe']]
]);
// Remove filter (show all)
map.setFilter('layer', null);
// Hide all
map.setFilter('layer', ['==', '1', '0']);
```
## Complete Example
```html
Restaurant
Cafe
Hotel
```
```jsx
import React, { useEffect, useRef, useState } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const categories = ['restaurant', 'cafe', 'hotel'];
const placesData = {
type: 'FeatureCollection',
features: [
{ type: 'Feature', properties: { category: 'restaurant' }, geometry: { type: 'Point', coordinates: [2.344, 48.856] } },
{ type: 'Feature', properties: { category: 'cafe' }, geometry: { type: 'Point', coordinates: [2.333, 48.854] } },
{ type: 'Feature', properties: { category: 'hotel' }, geometry: { type: 'Point', coordinates: [2.337, 48.860] } },
]
};
const FilterByToggleList = () => {
const mapContainer = useRef(null);
const map = useRef(null);
const [active, setActive] = useState(new Set(categories));
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.3499, 48.853],
zoom: 13
});
map.current.on('load', () => {
map.current.addSource('places', { type: 'geojson', data: placesData });
map.current.addLayer({
id: 'places-layer', type: 'circle', source: 'places',
paint: { 'circle-radius': 9, 'circle-color': '#3b82f6', 'circle-stroke-width': 2, 'circle-stroke-color': '#fff' }
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
useEffect(() => {
if (!map.current) return;
const list = [...active];
map.current.setFilter?.('places-layer', list.length
? ['in', ['get', 'category'], ['literal', list]]
: ['==', '1', '0']
);
}, [active]);
const toggle = (cat) => {
setActive(prev => {
const next = new Set(prev);
next.has(cat) ? next.delete(cat) : next.add(cat);
return next;
});
};
return (
{categories.map(cat => (
toggle(cat)}
style={{
padding: '6px 12px',
background: active.has(cat) ? '#3b82f6' : 'white',
color: active.has(cat) ? 'white' : '#3b82f6',
border: '2px solid #3b82f6',
borderRadius: '20px',
cursor: 'pointer'
}}
>
{cat}
))}
);
};
export default FilterByToggleList;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Filter Features Within a Layer
https://docs.mapatlas.xyz/sdk/examples/filter-within-layer
---
title: "Filter Features Within a Layer"
category: "lines-polygons"
platform: ["web", "react"]
difficulty: "intermediate"
apis: ["Map", "addSource", "addLayer", "setFilter", "filter"]
tags: ["filter", "layer", "setFilter", "geojson", "expression", "query", "search", "dynamic"]
description: "Dynamically filter which features are displayed in a map layer using setFilter"
---
# Filter Features Within a Layer
Show or hide specific map features dynamically using `setFilter()` without reloading data.
All Cities
Capitals Only
Port Cities
Pop > 1M
## How It Works
`setFilter()` applies a filter expression to a layer — only features that match the expression are displayed. The data stays in the source; only the rendering changes.
## Basic Filter Patterns
```javascript
// Show all features (clear filter)
map.setFilter('my-layer', null);
// Match exact string value
map.setFilter('my-layer', ['==', ['get', 'type'], 'capital']);
// Match boolean property
map.setFilter('my-layer', ['==', ['get', 'port'], true]);
// Numeric comparison
map.setFilter('my-layer', ['>=', ['get', 'population'], 1000000]);
// Multiple conditions (AND)
map.setFilter('my-layer', [
'all',
['==', ['get', 'type'], 'capital'],
['>=', ['get', 'population'], 1000000]
]);
// Multiple conditions (OR)
map.setFilter('my-layer', [
'any',
['==', ['get', 'type'], 'capital'],
['==', ['get', 'port'], true]
]);
```
## Filter by Text Search
```javascript
const searchInput = document.getElementById('search');
searchInput.addEventListener('input', (e) => {
const query = e.target.value.toLowerCase();
if (!query) {
map.setFilter('cities-layer', null);
return;
}
// Filter by name containing the search text
map.setFilter('cities-layer', [
'in',
query,
['downcase', ['get', 'name']]
]);
});
```
## Complete Example
```html
All
Capitals
Cities
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const citiesData = {
type: 'FeatureCollection',
features: [
{ type: 'Feature', properties: { name: 'Paris', type: 'capital' }, geometry: { type: 'Point', coordinates: [2.349902, 48.852966] } },
{ type: 'Feature', properties: { name: 'London', type: 'capital' }, geometry: { type: 'Point', coordinates: [-0.1276, 51.5074] } },
{ type: 'Feature', properties: { name: 'Hamburg', type: 'city' }, geometry: { type: 'Point', coordinates: [9.9937, 53.5511] } },
{ type: 'Feature', properties: { name: 'Lyon', type: 'city' }, geometry: { type: 'Point', coordinates: [4.8357, 45.764] } },
]
};
const FilterLayer = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [5, 48],
zoom: 4
});
map.current.on('load', () => {
map.current.addSource('cities', { type: 'geojson', data: citiesData });
map.current.addLayer({
id: 'cities-layer',
type: 'circle',
source: 'cities',
paint: {
'circle-radius': 10,
'circle-color': ['match', ['get', 'type'], 'capital', '#ef4444', '#3b82f6'],
'circle-stroke-width': 2,
'circle-stroke-color': '#fff'
}
});
});
return () => { map.current?.remove(); map.current = null; };
}, []);
const filterBy = (type) => {
if (!map.current) return;
if (type === 'all') {
map.current.setFilter('cities-layer', null);
} else {
map.current.setFilter('cities-layer', ['==', ['get', 'type'], type]);
}
};
return (
filterBy('all')} style={{ padding: '8px 16px', background: '#3b82f6', color: 'white', border: 'none', borderRadius: '6px', cursor: 'pointer' }}>All
filterBy('capital')} style={{ padding: '8px 16px', background: '#ef4444', color: 'white', border: 'none', borderRadius: '6px', cursor: 'pointer' }}>Capitals
filterBy('city')} style={{ padding: '8px 16px', background: '#22c55e', color: 'white', border: 'none', borderRadius: '6px', cursor: 'pointer' }}>Cities
);
};
export default FilterLayer;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Fit a Map to a Bounding Box
https://docs.mapatlas.xyz/sdk/examples/fit-to-bounding-box
---
title: "Fit a Map to a Bounding Box"
category: "camera"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "fitBounds", "LngLatBounds"]
tags: ["camera", "bounds", "fitBounds", "bounding-box", "zoom"]
description: "Automatically fit the map view to show all markers or a region using fitBounds"
---
# Fit a Map to a Bounding Box
Automatically adjust the map camera to fit any set of coordinates or a region into view using `fitBounds`.
Fit Europe
Fit USA
Fit Paris
## How It Works
Use `map.fitBounds()` to fit the map view to any rectangular area defined by two corners `[southwest, northeast]`.
## Basic Usage
```javascript
// Fit to a bounding box [southwest corner, northeast corner]
map.fitBounds([
[-74.1, 40.6], // Southwest corner [lng, lat]
[-73.9, 40.9] // Northeast corner [lng, lat]
], {
padding: 40 // Padding in pixels around the bounds
});
```
## Fit to a Set of Markers
```javascript
// Calculate bounds from a set of points
const bounds = new mapmetricsgl.LngLatBounds();
const points = [
[-74.006, 40.7128], // New York
[-0.1276, 51.5074], // London
[2.349902, 48.852966] // Paris
];
points.forEach(point => bounds.extend(point));
map.fitBounds(bounds, { padding: 60 });
```
## Options
| Option | Type | Description |
|--------|------|-------------|
| `padding` | `number` or `object` | Padding in pixels. Can be `{ top, bottom, left, right }` |
| `maxZoom` | `number` | Maximum zoom level to use |
| `animate` | `boolean` | Whether to animate (default: `true`) |
| `duration` | `number` | Animation duration in milliseconds |
| `bearing` | `number` | Map bearing after fitting |
| `pitch` | `number` | Map pitch after fitting |
## Complete Example
```html
Fit to All Markers
Fit Europe
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const locations = [
{ center: [-74.006, 40.7128], label: 'New York' },
{ center: [-0.1276, 51.5074], label: 'London' },
{ center: [2.349902, 48.852966], label: 'Paris' },
];
const FitToBounds = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [2.349902, 48.852966],
zoom: 3
});
map.current.addControl(new mapmetricsgl.NavigationControl(), 'top-right');
// Add markers for each location
locations.forEach(loc => {
new mapmetricsgl.Marker()
.setLngLat(loc.center)
.setPopup(new mapmetricsgl.Popup().setHTML(`${loc.label} `))
.addTo(map.current);
});
return () => { map.current?.remove(); map.current = null; };
}, []);
const fitToMarkers = () => {
const bounds = new mapmetricsgl.LngLatBounds();
locations.forEach(loc => bounds.extend(loc.center));
map.current?.fitBounds(bounds, { padding: 60 });
};
const fitEurope = () => {
map.current?.fitBounds([[-10, 35], [30, 70]], { padding: 40 });
};
return (
Fit to All Markers
Fit Europe
);
};
export default FitToBounds;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# Fit Map to a LineString
https://docs.mapatlas.xyz/sdk/examples/fit-to-linestring
---
title: "Fit Map to a LineString"
category: "camera"
platform: ["web", "react"]
difficulty: "beginner"
apis: ["Map", "fitBounds", "addSource", "addLayer", "LngLatBounds"]
tags: ["fitBounds", "linestring", "bounds", "zoom", "camera", "route", "auto-fit", "padding"]
description: "Automatically fit the map view to the bounds of a LineString or any set of coordinates"
---
# Fit Map to a LineString
Automatically zoom and pan to fit a LineString or route using `fitBounds()`.
Europe Route
World Route
Local Route
## Fit to a Set of Coordinates
Use `LngLatBounds` to compute the bounding box, then call `fitBounds()`:
```javascript
const coordinates = [
[2.3499, 48.853], // Paris
[-0.1276, 51.5074], // London
[13.405, 52.52], // Berlin
];
// Build bounds from all coordinates
const bounds = coordinates.reduce(
(bounds, coord) => bounds.extend(coord),
new mapmetricsgl.LngLatBounds(coordinates[0], coordinates[0])
);
// Fit map to bounds
map.fitBounds(bounds, {
padding: 60, // pixels of padding on each side
duration: 1000, // animation duration in ms
});
```
## fitBounds Options
```javascript
map.fitBounds(bounds, {
padding: { top: 50, bottom: 50, left: 50, right: 50 }, // or just a number
maxZoom: 15, // don't zoom in more than this
duration: 1000, // animation ms (0 = instant)
bearing: 0, // target bearing
pitch: 0, // target pitch
});
```
## From a GeoJSON Feature
```javascript
// Given a LineString feature
const feature = {
type: 'Feature',
geometry: {
type: 'LineString',
coordinates: [[lng1, lat1], [lng2, lat2], ...]
}
};
const bounds = feature.geometry.coordinates.reduce(
(b, c) => b.extend(c),
new mapmetricsgl.LngLatBounds(
feature.geometry.coordinates[0],
feature.geometry.coordinates[0]
)
);
map.fitBounds(bounds, { padding: 60 });
```
## Complete Example
```html
```
```jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const route = [
[2.3499, 48.853],
[-0.1276, 51.5074],
[13.405, 52.52],
[16.3738, 48.2082],
[12.4964, 41.9028],
];
const FitToLineString = () => {
const mapContainer = useRef(null);
const map = useRef(null);
useEffect(() => {
if (map.current) return;
map.current = new mapmetricsgl.Map({
container: mapContainer.current,
style: '',
center: [5, 50],
zoom: 2
});
map.current.on('load', () => {
map.current.addSource('route', {
type: 'geojson',
data: { type: 'Feature', geometry: { type: 'LineString', coordinates: route } }
});
map.current.addLayer({
id: 'route',
type: 'line',
source: 'route',
paint: { 'line-color': '#3b82f6', 'line-width': 3 }
});
// Fit the map to the route
const bounds = route.reduce(
(b, c) => b.extend(c),
new mapmetricsgl.LngLatBounds(route[0], route[0])
);
map.current.fitBounds(bounds, { padding: 60 });
});
return () => { map.current?.remove(); map.current = null; };
}, []);
return
;
};
export default FitToLineString;
```
---
For more information, visit the [MapMetrics GitHub repository](https://github.com/MapMetrics/mapmetrics-gl).
---
# 3D Buildings with Shadow in Flutter
https://docs.mapatlas.xyz/sdk/examples/flutter-3d-buildings-with-shadow
# 3D Buildings with Shadow in Flutter
This tutorial shows how to display 3D extruded buildings with a shaded, depth-aware look — adding realism to your map without a live shadow-casting light source.
## Prerequisites
Before you begin, ensure you have:
- Completed the [Flutter Setup Guide](./flutter-setup)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## No Runtime Light API
MapMetrics Flutter doesn't expose a `setLight` (or any other) runtime lighting call — the MapLibre Style Spec's root-level `light` object can only be set in the style JSON itself, not changed live from Dart. There's also no `setPaintProperty`: to change a layer's paint at runtime you `removeLayer` then `addLayer` again with new values.
That still leaves two real, supported ways to get a shadow-like look:
1. **`fill-extrusion-vertical-gradient`** — a real MapLibre paint property (darker at the base, lighter at the top) that you can set directly in a `FillExtrusionStyleLayer`'s `paint` map.
2. **Swap `fill-extrusion-color` by removing/re-adding the layer** — simulate different light conditions (morning/noon/evening) by changing the building color, rather than moving an actual light source.
## 3D Buildings with a Vertical Gradient
```dart
import 'package:flutter/material.dart';
import 'package:mapmetrics/mapmetrics.dart';
class BuildingsWithShadowScreen extends StatefulWidget {
const BuildingsWithShadowScreen({super.key});
@override
State createState() =>
_BuildingsWithShadowScreenState();
}
class _BuildingsWithShadowScreenState
extends State {
MapController? mapController;
StyleController? styleController;
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('3D Buildings with Shadow')),
body: MapMetricsView(
options: MapOptions(
initStyle:
'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
initCenter: Position(2.3376, 48.8606), // Louvre area
initZoom: 16.5,
initPitch: 60,
initBearing: -30,
),
onMapCreated: (controller) => mapController = controller,
onStyleLoaded: (style) async {
styleController = style;
await _addBuildingsWithShadow('#b0b0b0');
},
),
floatingActionButton: Column(
mainAxisAlignment: MainAxisAlignment.end,
children: [
FloatingActionButton.small(
heroTag: 'morning',
onPressed: () => _addBuildingsWithShadow('#c0a060'),
tooltip: 'Morning Light',
child: const Icon(Icons.wb_twilight),
),
const SizedBox(height: 8),
FloatingActionButton.small(
heroTag: 'noon',
onPressed: () => _addBuildingsWithShadow('#b0b0b0'),
tooltip: 'Noon Light',
child: const Icon(Icons.wb_sunny),
),
const SizedBox(height: 8),
FloatingActionButton.small(
heroTag: 'evening',
onPressed: () => _addBuildingsWithShadow('#8b6914'),
tooltip: 'Evening Light',
child: const Icon(Icons.nights_stay),
),
],
),
);
}
Future _addBuildingsWithShadow(String buildingColor) async {
final style = styleController;
if (style == null) return;
// removeLayer is a no-op error if the layer doesn't exist yet on first
// call -- guard it in production code with a try/catch or a "did I add
// this already" flag.
try {
await style.removeLayer('3d-buildings-shadow');
} catch (_) {
// First call: nothing to remove yet.
}
await style.addLayer(
FillExtrusionStyleLayer(
id: '3d-buildings-shadow',
sourceId: 'openmaptiles', // must match a source in your style
paint: {
'fill-extrusion-color': buildingColor,
'fill-extrusion-opacity': 0.85,
'fill-extrusion-height': ['get', 'render_height'],
'fill-extrusion-base': ['get', 'render_min_height'],
// Darker at the base, lighter toward the roofline -- a real
// MapLibre paint property, not a light simulation.
'fill-extrusion-vertical-gradient': true,
},
layout: const {'source-layer': 'building'},
),
);
}
}
```
## Time-of-Day Color Simulation
Since there's no live light source to move, "time of day" here means picking a building color and background feel per hour and re-adding the layer — the closest real equivalent of the original light-angle animation:
```dart
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:mapmetrics/mapmetrics.dart';
class ShadowTimeScreen extends StatefulWidget {
const ShadowTimeScreen({super.key});
@override
State createState() => _ShadowTimeScreenState();
}
class _ShadowTimeScreenState extends State {
MapController? mapController;
StyleController? styleController;
double timeOfDay = 12.0; // 0-24 hours
Timer? animTimer;
bool isAnimating = false;
bool _layerAdded = false;
String _colorForHour(double hour) {
// Building color: warmer tones at golden hour, neutral at midday.
if (hour < 7 || hour > 19) return '#8B6914'; // Dark warm
if (hour < 9 || hour > 17) return '#C0A060'; // Warm
return '#b0b0b0'; // Neutral grey
}
String _hourLabel(double hour) {
final h = hour.toInt();
final m = ((hour - h) * 60).toInt();
final period = h >= 12 ? 'PM' : 'AM';
final displayH = h > 12 ? h - 12 : (h == 0 ? 12 : h);
return '$displayH:${m.toString().padLeft(2, '0')} $period';
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Shadow Time Simulation')),
body: Stack(
children: [
MapMetricsView(
options: MapOptions(
initStyle:
'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
initCenter: Position(2.3376, 48.8606),
initZoom: 16.5,
initPitch: 55,
initBearing: -20,
),
onMapCreated: (controller) => mapController = controller,
onStyleLoaded: (style) async {
styleController = style;
await _updateBuildings();
},
),
// Time controls
Positioned(
bottom: 16,
left: 16,
right: 16,
child: Card(
child: Padding(
padding: const EdgeInsets.all(12),
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
Row(
mainAxisAlignment: MainAxisAlignment.spaceBetween,
children: [
Text(
_hourLabel(timeOfDay),
style: const TextStyle(
fontSize: 20,
fontWeight: FontWeight.bold,
),
),
ElevatedButton.icon(
onPressed:
isAnimating ? _stopAnimation : _startAnimation,
icon: Icon(
isAnimating ? Icons.pause : Icons.play_arrow,
),
label: Text(isAnimating ? 'Pause' : 'Animate'),
),
],
),
Slider(
value: timeOfDay,
min: 5.0,
max: 21.0,
divisions: 64,
label: _hourLabel(timeOfDay),
onChanged: (val) {
setState(() => timeOfDay = val);
_updateBuildings();
},
),
],
),
),
),
),
],
),
);
}
Future _updateBuildings() async {
final style = styleController;
if (style == null) return;
if (_layerAdded) {
await style.removeLayer('3d-buildings');
}
_layerAdded = true;
await style.addLayer(
FillExtrusionStyleLayer(
id: '3d-buildings',
sourceId: 'openmaptiles',
paint: {
'fill-extrusion-color': _colorForHour(timeOfDay),
'fill-extrusion-opacity': 0.85,
'fill-extrusion-height': ['get', 'render_height'],
'fill-extrusion-base': ['get', 'render_min_height'],
'fill-extrusion-vertical-gradient': true,
},
layout: const {'source-layer': 'building'},
),
);
}
void _startAnimation() {
setState(() {
isAnimating = true;
if (timeOfDay >= 21.0) timeOfDay = 5.0;
});
animTimer = Timer.periodic(const Duration(milliseconds: 300), (_) {
if (timeOfDay >= 21.0) {
_stopAnimation();
return;
}
setState(() => timeOfDay += 0.2);
_updateBuildings();
});
}
void _stopAnimation() {
animTimer?.cancel();
setState(() => isAnimating = false);
}
@override
void dispose() {
animTimer?.cancel();
super.dispose();
}
}
```
Removing and re-adding a style layer every animation tick is noticeably heavier than a native paint-property setter would be, so the interval here is deliberately slower (300ms) than a 60fps camera animation — treat this as a "few keyframes over the day" simulation, not a smooth light sweep.
## Fill-Extrusion Paint Properties Used Here
| Property | Type | Description |
|----------|------|-------------|
| `fill-extrusion-color` | `String` | Building wall/roof color |
| `fill-extrusion-opacity` | `double` | Transparency (0.0 - 1.0) |
| `fill-extrusion-vertical-gradient` | `bool` | Darker at base, lighter at top |
| `fill-extrusion-height` / `fill-extrusion-base` | Expression | Building height/base from source properties |
## Next Steps
- [3D Buildings](./flutter-3d-buildings) — Basic 3D building setup
- [Add a Popup](./flutter-add-a-popup) — Show building details on tap
- [Add Animated Icon](./flutter-add-animated-icon) — Animate markers instead of layers
---
**Tip**: Since there's no live `light` setter, reach for `fill-extrusion-vertical-gradient: true` first — it gives buildings a believable sense of depth with zero runtime cost, no layer swapping required.
---
# 3D Building Visualization in Flutter
https://docs.mapatlas.xyz/sdk/examples/flutter-3d-buildings
# 3D Building Visualization in Flutter
This tutorial shows how to display 3D extruded buildings on your MapMetrics Flutter map — great for urban planning, real estate, and city exploration apps.
## Prerequisites
Before you begin, ensure you have:
- Completed the [Flutter Setup Guide](./flutter-setup)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Enable 3D Buildings
3D buildings are a `FillExtrusionStyleLayer` you add on top of a vector source that already has building footprints — most MapMetrics vector styles ship one. Check your style JSON for the source name (it's usually something like `openmaptiles`) and the `building` source-layer, then tilt the camera so the extrusion is visible:
```dart
import 'package:flutter/material.dart';
import 'package:mapmetrics/mapmetrics.dart';
class Buildings3DScreen extends StatefulWidget {
const Buildings3DScreen({super.key});
@override
State createState() => _Buildings3DScreenState();
}
class _Buildings3DScreenState extends State {
MapController? mapController;
static const _buildingsLayer = FillExtrusionStyleLayer(
id: '3d-buildings',
sourceId: 'openmaptiles', // must match a source already in your style
paint: {
// See the MapLibre Style Specification for details on data expressions.
// https://maplibre.org/maplibre-style-spec/expressions/
'fill-extrusion-color': '#aaaaaa',
'fill-extrusion-height': ['get', 'render_height'],
'fill-extrusion-base': ['get', 'render_min_height'],
// Fade the layer in above zoom 14 instead of a hard minZoom cutoff --
// FillExtrusionStyleLayer doesn't expose a minZoom parameter.
'fill-extrusion-opacity': [
'interpolate',
['linear'],
['zoom'],
13,
0,
14,
0.6,
],
},
layout: {'source-layer': 'building'},
);
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('3D Buildings')),
body: MapMetricsView(
options: MapOptions(
initStyle:
'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
initCenter: Position(2.2945, 48.8584), // Eiffel Tower area
initZoom: 16,
initPitch: 60, // Tilt to see buildings in 3D
initBearing: 45, // Rotate for a better perspective
),
onMapCreated: (controller) => mapController = controller,
onStyleLoaded: (style) async {
await style.addLayer(_buildingsLayer);
},
),
floatingActionButton: Column(
mainAxisAlignment: MainAxisAlignment.end,
children: [
FloatingActionButton(
heroTag: 'tilt_up',
onPressed: () => _setPitch(60),
tooltip: '3D View',
child: const Icon(Icons.landscape),
),
const SizedBox(height: 8),
FloatingActionButton(
heroTag: 'tilt_down',
onPressed: () => _setPitch(0),
tooltip: '2D View',
child: const Icon(Icons.map),
),
],
),
);
}
void _setPitch(double pitch) {
final camera = mapController?.camera;
if (camera != null) {
mapController?.animateCamera(
center: camera.center,
zoom: camera.zoom,
bearing: camera.bearing,
pitch: pitch,
);
}
}
}
```
## 3D Buildings with Custom Colors
Color buildings by swapping the layer out — there's no per-property setter, so changing color means `removeLayer` followed by `addLayer` with the new paint values:
```dart
import 'package:flutter/material.dart';
import 'package:mapmetrics/mapmetrics.dart';
class ColoredBuildings3DScreen extends StatefulWidget {
const ColoredBuildings3DScreen({super.key});
@override
State createState() =>
_ColoredBuildings3DScreenState();
}
class _ColoredBuildings3DScreenState extends State {
MapController? mapController;
StyleController? styleController;
String colorScheme = 'height'; // 'height', 'blue', 'warm'
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Colored 3D Buildings')),
body: Column(
children: [
// Color scheme selector
Padding(
padding: const EdgeInsets.all(8),
child: Row(
mainAxisAlignment: MainAxisAlignment.spaceEvenly,
children: [
_schemeChip('Height', 'height'),
_schemeChip('Cool Blue', 'blue'),
_schemeChip('Warm Sunset', 'warm'),
],
),
),
Expanded(
child: MapMetricsView(
options: MapOptions(
initStyle:
'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
initCenter: Position(2.3376, 48.8606), // Louvre area
initZoom: 16,
initPitch: 55,
initBearing: -20,
),
onMapCreated: (controller) => mapController = controller,
onStyleLoaded: (style) async {
styleController = style;
await _applyColorScheme();
},
),
),
],
),
);
}
Widget _schemeChip(String label, String scheme) {
return ChoiceChip(
label: Text(label),
selected: colorScheme == scheme,
onSelected: (selected) {
if (selected) {
setState(() => colorScheme = scheme);
_applyColorScheme();
}
},
);
}
Future _applyColorScheme() async {
final style = styleController;
if (style == null) return;
String color;
switch (colorScheme) {
case 'blue':
color = '#4a90d9';
break;
case 'warm':
color = '#e8775a';
break;
default: // height-based
color = '#8a8a8a';
}
// Layers have no property setters -- remove and re-add with the new paint.
await style.removeLayer('3d-buildings');
await style.addLayer(
FillExtrusionStyleLayer(
id: '3d-buildings',
sourceId: 'openmaptiles',
paint: {
'fill-extrusion-color': color,
'fill-extrusion-opacity': 0.7,
'fill-extrusion-height': ['get', 'render_height'],
'fill-extrusion-base': ['get', 'render_min_height'],
},
layout: const {'source-layer': 'building'},
),
);
}
}
```
## Interactive 3D Building Explorer
Tap landmark buttons to fly the camera between famous spots, and toggle a slow auto-rotation:
```dart
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:mapmetrics/mapmetrics.dart';
class BuildingExplorerScreen extends StatefulWidget {
const BuildingExplorerScreen({super.key});
@override
State createState() =>
_BuildingExplorerScreenState();
}
class _BuildingExplorerScreenState extends State {
MapController? mapController;
Timer? rotationTimer;
double currentBearing = 0;
bool isRotating = false;
final landmarks = const [
(name: 'Eiffel Tower Area', point: Position(2.2945, 48.8584), zoom: 17.0, pitch: 60.0),
(name: 'Louvre Area', point: Position(2.3376, 48.8606), zoom: 16.5, pitch: 55.0),
(name: 'Notre-Dame Area', point: Position(2.3499, 48.8530), zoom: 17.0, pitch: 65.0),
(name: 'Opera Area', point: Position(2.3316, 48.8720), zoom: 16.5, pitch: 55.0),
];
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('3D Explorer')),
body: Stack(
children: [
MapMetricsView(
options: MapOptions(
initStyle:
'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
initCenter: Position(2.2945, 48.8584),
initZoom: 17,
initPitch: 60,
),
onMapCreated: (controller) => mapController = controller,
onStyleLoaded: (style) async {
await style.addLayer(
const FillExtrusionStyleLayer(
id: '3d-buildings',
sourceId: 'openmaptiles',
paint: {
'fill-extrusion-color': '#667799',
'fill-extrusion-opacity': 0.7,
'fill-extrusion-height': ['get', 'render_height'],
'fill-extrusion-base': ['get', 'render_min_height'],
},
layout: {'source-layer': 'building'},
),
);
},
),
// Landmark buttons
Positioned(
bottom: 24,
left: 8,
right: 8,
child: SizedBox(
height: 44,
child: ListView.separated(
scrollDirection: Axis.horizontal,
itemCount: landmarks.length,
separatorBuilder: (_, __) => const SizedBox(width: 8),
itemBuilder: (context, i) {
final lm = landmarks[i];
return ElevatedButton(
onPressed: () {
mapController?.animateCamera(
center: lm.point,
zoom: lm.zoom,
pitch: lm.pitch,
bearing: currentBearing,
);
},
child: Text(lm.name, style: const TextStyle(fontSize: 12)),
);
},
),
),
),
// Rotate toggle
Positioned(
top: 16,
right: 16,
child: FloatingActionButton.small(
onPressed: _toggleRotation,
tooltip: 'Auto Rotate',
child: Icon(isRotating ? Icons.pause : Icons.rotate_right),
),
),
],
),
);
}
void _toggleRotation() {
if (isRotating) {
rotationTimer?.cancel();
setState(() => isRotating = false);
} else {
setState(() => isRotating = true);
rotationTimer = Timer.periodic(const Duration(milliseconds: 50), (_) {
currentBearing = (currentBearing + 0.5) % 360;
final camera = mapController?.camera;
if (camera != null) {
// moveCameraSync avoids the microtask gap that shows up as
// visible stutter in a tight per-frame rotation loop.
mapController?.moveCameraSync(
center: camera.center,
zoom: camera.zoom,
pitch: camera.pitch,
bearing: currentBearing,
);
}
});
}
}
@override
void dispose() {
rotationTimer?.cancel();
super.dispose();
}
}
```
## 3D Building Paint Properties
| Property | Description |
|----------|-------------|
| `fill-extrusion-color` | Building wall/roof color |
| `fill-extrusion-opacity` | Transparency (0.0 - 1.0) |
| `fill-extrusion-height` | Building height in meters (a `['get', ...]` expression reading the source property) |
| `fill-extrusion-base` | Base height (for elevated structures) |
`FillExtrusionStyleLayer` doesn't accept a `minZoom` constructor argument the way some other layer types do — use a `'zoom'` interpolation on `fill-extrusion-opacity` (as in the first example) to fade buildings in instead of hiding them below a hard cutoff.
## Next Steps
- [3D Buildings with Shadow](./flutter-3d-buildings-with-shadow) — Add light-based shading
- [Add a Cluster](./flutter-add-a-cluster) — Group markers at low zoom
- [Add a Popup](./flutter-add-a-popup) — Show details when a building is tapped
---
**Tip**: 3D buildings look best at zoom levels 15-18 with a pitch of 45-65 degrees. Combine with a bearing rotation for dramatic fly-through effects.
---
# 3D Terrain in Flutter
https://docs.mapatlas.xyz/sdk/examples/flutter-3d-terrain
# 3D Terrain in Flutter
::: warning Terrain tile endpoint not confirmed
The terrain/relief tile URLs below are **placeholders**. MapMetrics does not
currently serve `/terrain-rgb/` or `/relief/` on
`gateway.mapmetrics-atlas.net` — both return 404 (checked 2026-08-04).
Substitute a raster-DEM source you actually have access to. The layer and
source wiring shown here is correct regardless of where the tiles come from.
:::
This tutorial covers rendering mountainous terrain on your MapMetrics Flutter map — hillshade relief plus a tilted camera for an immersive, dimensional feel.
## Prerequisites
Before you begin, ensure you have:
- Completed the [Flutter Setup Guide](./flutter-setup)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## No `setTerrain` / Elevation Displacement
MapMetrics Flutter doesn't currently expose a `setTerrain`/elevation-exaggeration API — there's no way to physically displace the map surface by elevation the way some other SDKs do. What the SDK *does* support is a real `RasterDemSource` + `HillshadeStyleLayer` pair, which reads the same terrain-RGB/Terrarium DEM tiles and renders MapLibre's native shaded-relief look. Combined with camera `pitch`, this gets you a convincing sense of mountains and valleys without true 3D displacement.
If you need actual elevation displacement, it isn't available in this SDK today — say so plainly to users rather than faking it with a "terrain exaggeration" slider that doesn't do anything under the hood.
## Enable Hillshade Relief
```dart
import 'package:flutter/material.dart';
import 'package:mapmetrics/mapmetrics.dart';
class TerrainScreen extends StatefulWidget {
const TerrainScreen({super.key});
@override
State createState() => _TerrainScreenState();
}
class _TerrainScreenState extends State {
MapController? mapController;
static const _sourceId = 'terrain-dem';
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Terrain Relief')),
body: MapMetricsView(
options: MapOptions(
initStyle:
'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
initCenter: Position(8.2275, 46.8182), // Swiss Alps
initZoom: 10,
initPitch: 60,
initBearing: 30,
),
onMapCreated: (controller) => mapController = controller,
onStyleLoaded: (style) async {
await style.addSource(
const RasterDemSource(
id: _sourceId,
tiles: [
'https://gateway.mapmetrics-atlas.net/terrain-rgb/{z}/{x}/{y}.png',
],
tileSize: 256,
),
);
await style.addLayer(
const HillshadeStyleLayer(
id: 'hillshade',
sourceId: _sourceId,
paint: {
'hillshade-shadow-color': '#473B24',
'hillshade-exaggeration': 0.6,
},
),
);
},
),
floatingActionButton: Column(
mainAxisAlignment: MainAxisAlignment.end,
children: [
FloatingActionButton(
heroTag: 'tilt',
onPressed: () => _setPitch(60),
tooltip: 'Tilted View',
child: const Icon(Icons.terrain),
),
const SizedBox(height: 8),
FloatingActionButton(
heroTag: 'flat',
onPressed: () => _setPitch(0),
tooltip: 'Top-Down View',
child: const Icon(Icons.map),
),
],
),
);
}
void _setPitch(double pitch) {
final camera = mapController?.camera;
if (camera != null) {
mapController?.animateCamera(
center: camera.center,
zoom: camera.zoom,
bearing: camera.bearing,
pitch: pitch,
);
}
}
}
```
`RasterDemSource.encoding` defaults to Mapbox Terrain-RGB (`RasterDemMapboxEncoding`); pass `RasterDemTerrariumEncoding()` if your tile server serves Mapzen Terrarium PNGs instead.
## Mountain Explorer with Location Buttons
Jump between famous mountain locations by animating pitch, bearing, zoom, and center together:
```dart
import 'package:flutter/material.dart';
import 'package:mapmetrics/mapmetrics.dart';
class MountainExplorerScreen extends StatefulWidget {
const MountainExplorerScreen({super.key});
@override
State createState() =>
_MountainExplorerScreenState();
}
class _MountainExplorerScreenState extends State {
MapController? mapController;
final mountains = const [
(name: 'Swiss Alps', point: Position(8.2275, 46.8182), zoom: 10.0, bearing: 30.0),
(name: 'Mont Blanc', point: Position(6.8652, 45.8326), zoom: 12.0, bearing: 150.0),
(name: 'Matterhorn', point: Position(7.6586, 45.9763), zoom: 13.0, bearing: 220.0),
(name: 'Dolomites', point: Position(11.8440, 46.4102), zoom: 11.0, bearing: 90.0),
(name: 'Pyrenees', point: Position(0.0414, 42.6953), zoom: 10.0, bearing: 45.0),
];
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Mountain Explorer')),
body: Stack(
children: [
MapMetricsView(
options: MapOptions(
initStyle:
'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
initCenter: Position(8.2275, 46.8182),
initZoom: 10,
initPitch: 60,
initBearing: 30,
),
onMapCreated: (controller) => mapController = controller,
onStyleLoaded: (style) async {
await style.addSource(
const RasterDemSource(
id: 'terrain-dem',
tiles: [
'https://gateway.mapmetrics-atlas.net/terrain-rgb/{z}/{x}/{y}.png',
],
tileSize: 256,
),
);
await style.addLayer(
const HillshadeStyleLayer(
id: 'hillshade',
sourceId: 'terrain-dem',
paint: {'hillshade-shadow-color': '#473B24'},
),
);
},
),
// Mountain selector
Positioned(
bottom: 16,
left: 8,
right: 8,
child: SizedBox(
height: 44,
child: ListView.separated(
scrollDirection: Axis.horizontal,
itemCount: mountains.length,
separatorBuilder: (_, __) => const SizedBox(width: 8),
itemBuilder: (context, i) {
final m = mountains[i];
return ElevatedButton.icon(
onPressed: () {
mapController?.animateCamera(
center: m.point,
zoom: m.zoom,
pitch: 60,
bearing: m.bearing,
);
},
icon: const Icon(Icons.terrain, size: 16),
label: Text(m.name, style: const TextStyle(fontSize: 12)),
);
},
),
),
),
],
),
);
}
}
```
## Hillshade Intensity Slider
Instead of a fake "terrain exaggeration" control, expose the real `hillshade-exaggeration` paint property — remembering that, like every other paint property here, changing it means removing and re-adding the layer:
```dart
import 'package:flutter/material.dart';
import 'package:mapmetrics/mapmetrics.dart';
class HillshadeSliderScreen extends StatefulWidget {
const HillshadeSliderScreen({super.key});
@override
State createState() => _HillshadeSliderScreenState();
}
class _HillshadeSliderScreenState extends State {
MapController? mapController;
StyleController? styleController;
double exaggeration = 0.6;
bool _layerAdded = false;
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Hillshade Intensity')),
body: Stack(
children: [
MapMetricsView(
options: MapOptions(
initStyle:
'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
initCenter: Position(8.2275, 46.8182),
initZoom: 10,
initPitch: 60,
),
onMapCreated: (controller) => mapController = controller,
onStyleLoaded: (style) async {
styleController = style;
await style.addSource(
const RasterDemSource(
id: 'terrain-dem',
tiles: [
'https://gateway.mapmetrics-atlas.net/terrain-rgb/{z}/{x}/{y}.png',
],
tileSize: 256,
),
);
await _updateHillshade();
},
),
// Intensity slider
Positioned(
bottom: 24,
left: 16,
right: 16,
child: Card(
child: Padding(
padding: const EdgeInsets.all(12),
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
Text(
'Hillshade exaggeration: ${exaggeration.toStringAsFixed(1)}',
style: const TextStyle(fontWeight: FontWeight.bold),
),
Slider(
value: exaggeration,
min: 0.0,
max: 1.0,
divisions: 10,
label: exaggeration.toStringAsFixed(1),
onChanged: (value) {
setState(() => exaggeration = value);
_updateHillshade();
},
),
const Text(
'0 = flat shading | 1 = strongest relief contrast',
style: TextStyle(color: Colors.grey, fontSize: 11),
),
],
),
),
),
),
],
),
);
}
Future _updateHillshade() async {
final style = styleController;
if (style == null) return;
if (_layerAdded) {
await style.removeLayer('hillshade');
}
_layerAdded = true;
await style.addLayer(
HillshadeStyleLayer(
id: 'hillshade',
sourceId: 'terrain-dem',
paint: {
'hillshade-shadow-color': '#473B24',
'hillshade-exaggeration': exaggeration,
},
),
);
}
}
```
## Terrain Parameters
| Parameter | Range | Description |
|-----------|-------|--------------|
| `hillshade-exaggeration` | 0.0 - 1.0 | Contrast of the shaded relief effect (real MapLibre paint property) |
| `tileSize` | 256 / 512 | Resolution of the DEM tiles |
| `initPitch` | 0 - 60 | Camera tilt angle for a 3D-feeling view |
## Next Steps
- [3D Buildings](./flutter-3d-buildings) — Add extruded buildings
- [Add a Color Relief Layer](./flutter-add-color-relief-layer) — Elevation-tinted terrain coloring
- [3D Buildings with Shadow](./flutter-3d-buildings-with-shadow) — Depth-aware building shading
---
**Tip**: `initPitch` does more for the "3D" feeling here than anything else — combine a 55-65 degree pitch with hillshade rather than chasing a terrain-exaggeration effect the SDK doesn't provide.
---
# Add Clusters in Flutter
https://docs.mapatlas.xyz/sdk/examples/flutter-add-a-cluster
# Add Clusters in Flutter
This tutorial shows how to group nearby markers into clusters for better performance and readability when you have many data points on the map.
## Prerequisites
Before you begin, ensure you have:
- Completed the [Flutter Setup Guide](./flutter-setup)
- A MapMetrics API key and style URL from the [MapMetrics Portal](https://portal.mapmetrics.org)
## Basic Clustering
Clustering is a native `GeoJsonSource` feature — set `cluster: true` and MapLibre groups nearby points into a single feature carrying a `point_count` property. You then render that with three style layers: circles for clusters, text labels for the counts, and circles for the individual (unclustered) points:
```dart
import 'dart:convert';
import 'dart:math';
import 'package:flutter/material.dart';
import 'package:mapmetrics/mapmetrics.dart';
class ClusterExampleScreen extends StatefulWidget {
const ClusterExampleScreen({super.key});
@override
State createState() => _ClusterExampleScreenState();
}
class _ClusterExampleScreenState extends State {
MapController? mapController;
static const _sourceId = 'poi-points';
// Sample data: 100 random points around Paris
late final List