MapMetrics Atlas API Docs

Appearance

Common Errors & Troubleshooting ​

Quick solutions to the most common issues when using MapMetrics Atlas API.

🔴 Map Not Loading (Blank Screen) ​

Symptoms: ​

  • Map container shows blank/white screen
  • Console error: Failed to load map style or 401 Unauthorized
  • Browser developer tools show 401 errors

Cause: ​

Missing or invalid API token (99% of cases)

Solution: ​

Step 1: Check if you have a token

javascript
// ❌ WRONG - Placeholder not replaced
style: 'YOUR_STYLE_URL_WITH_TOKEN'

// ✅ CORRECT - Actual URL from portal
style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=abc-123/style.json&token=eyJhbG...'

Step 2: Get your API token

  1. Visit MapMetrics Portal
  2. Sign up (free)
  3. Copy your complete style URL
  4. Paste it in your code

Step 3: Verify the token is in the URL Your style URL should include &token= parameter at the end.

🔴 Error: 401 Unauthorized ​

For Map Loading: ​

Error Message:

GET https://gateway.mapmetrics-atlas.net/styles/... 401 (Unauthorized)

Cause: Invalid or missing token in style URL

Solution:

javascript
// Make sure your style URL includes the token
const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_ID/style.json&token=YOUR_TOKEN',
  center: [lng, lat],
  zoom: 12
});

For REST API Calls: ​

Error Message:

json
{
  "error": "401 Token required"
}

Cause: Missing token query parameter

Solution:

javascript
// ❌ WRONG - No token
fetch('https://gateway.mapmetrics-atlas.net/directions/', {
  method: 'POST',
  body: JSON.stringify({...})
});

// ✅ CORRECT - Token in query parameter
fetch('https://gateway.mapmetrics-atlas.net/directions/?token=YOUR_TOKEN', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({...})
});

🔴 Map Container Has No Height ​

Symptoms: ​

  • Map container exists but has 0px height
  • Can't see the map

Cause: ​

Missing CSS height on map container

Solution: ​

Add CSS:

html
<style>
  #map {
    height: 500px;  /* or 100vh for full screen */
    width: 100%;
  }
</style>

Or inline:

html
<div id="map" style="height: 500px; width: 100%;"></div>

🔴 React: Map Renders Multiple Times ​

Symptoms: ​

  • Multiple map instances created
  • Memory leaks
  • Map behaves strangely

Cause: ​

Not properly managing map lifecycle in React

Solution: ​

jsx
import { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';

function MapComponent() {
  const mapContainerRef = useRef(null);
  const mapRef = useRef(null); // ✅ Store map instance

  useEffect(() => {
    // ✅ Check if map already exists
    if (mapRef.current) return;

    const map = new mapmetricsgl.Map({
      container: mapContainerRef.current,
      style: 'YOUR_STYLE_URL',
      center: [lng, lat],
      zoom: 12
    });

    mapRef.current = map;

    // ✅ Cleanup on unmount
    return () => {
      map.remove();
      mapRef.current = null;
    };
  }, []); // ✅ Empty dependency array

  return <div ref={mapContainerRef} style={{ height: '500px' }} />;
}

🔴 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"

🔴 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
  • [ ] 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: ​

🎓 Prevention Tips ​

Before You Start: ​

  1. ✅ Sign up at 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! 🔑