Maps API Reference

Create interactive maps and visualize geospatial data

Maps API

Related APIs

Resources

Introduction

The Nexus Maps API allows you to add interactive maps to your web and mobile applications with customizable styles, markers, routing capabilities, and geospatial data visualization.

Our Maps API provides both a JavaScript SDK for web applications and native SDKs for iOS and Android, making it easy to integrate maps into any platform.

Maps

The Maps API allows you to create and customize interactive maps for your applications.

GET /v2/maps/render

Render a static map image

Request Parameters

Parameter Type Required Description
center string Yes Center coordinates in "lat,lng" format
zoom integer Yes Zoom level (0-20)
width integer Yes Width of the map image (max 2048)
height integer Yes Height of the map image (max 2048)
style string No Map style ID (default: "standard")
format string No Image format: "png" or "jpeg" (default: "png")
markers string No Markers to display on the map (format: "lat1,lng1|lat2,lng2")

Example Request

curl -X GET "https://api.nexus-platform.com/v2/maps/render?center=37.7749,-122.4194&zoom=13&width=800&height=600&style=standard" \
    -H "Authorization: Bearer your_api_key"

Example Response

Returns a map image in the requested format.

GET /v2/maps/static

Get a static map URL for embedding

Request Parameters

Parameter Type Required Description
center string Yes Center coordinates in "lat,lng" format
zoom integer Yes Zoom level (0-20)
width integer Yes Width of the map image (max 2048)
height integer Yes Height of the map image (max 2048)
style string No Map style ID (default: "standard")
markers string No Markers to display on the map (format: "lat1,lng1|lat2,lng2")

Example Request

curl -X GET "https://api.nexus-platform.com/v2/maps/static?center=37.7749,-122.4194&zoom=13&width=800&height=600&style=dark" \
    -H "Authorization: Bearer your_api_key"

Example Response

{
  "url": "https://static.nexus-platform.com/maps/static/ABC123/37.7749,-122.4194,13/800x600/dark",
  "html_snippet": "Map",
  "expires_at": "2024-04-15T12:00:00Z"
}

Map Styles

The Maps API offers various pre-defined styles and allows you to create custom styles for your maps.

GET /v2/maps/styles

List available map styles

Example Request

curl -X GET "https://api.nexus-platform.com/v2/maps/styles" \
    -H "Authorization: Bearer your_api_key"

Example Response

{
  "styles": [
    {
      "id": "standard",
      "name": "Standard",
      "description": "Default map style with clear roads and landmarks",
      "preview_url": "https://static.nexus-platform.com/styles/standard/preview.jpg"
    },
    {
      "id": "satellite",
      "name": "Satellite",
      "description": "Satellite imagery of the world",
      "preview_url": "https://static.nexus-platform.com/styles/satellite/preview.jpg"
    },
    {
      "id": "dark",
      "name": "Dark",
      "description": "Dark theme optimized for low light conditions",
      "preview_url": "https://static.nexus-platform.com/styles/dark/preview.jpg"
    },
    {
      "id": "light",
      "name": "Light",
      "description": "Light theme with subtle colors",
      "preview_url": "https://static.nexus-platform.com/styles/light/preview.jpg"
    }
  ]
}
POST /v2/maps/styles/custom

Create a custom map style

Request Body

{
  "name": "My Custom Style",
  "description": "A custom map style for my application",
  "base_style": "standard",
  "elements": [
    {
      "type": "water",
      "color": "#0088cc"
    },
    {
      "type": "park",
      "color": "#33cc66"
    },
    {
      "type": "road",
      "color": "#ffffff",
      "width": 1.2
    }
  ]
}

Example Request

curl -X POST "https://api.nexus-platform.com/v2/maps/styles/custom" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "My Custom Style",
      "description": "A custom map style for my application",
      "base_style": "standard",
      "elements": [
        {
          "type": "water",
          "color": "#0088cc"
        },
        {
          "type": "park",
          "color": "#33cc66"
        },
        {
          "type": "road",
          "color": "#ffffff",
          "width": 1.2
        }
      ]
    }'

Example Response

{
  "style_id": "custom_abc123",
  "name": "My Custom Style",
  "description": "A custom map style for my application",
  "preview_url": "https://static.nexus-platform.com/styles/custom_abc123/preview.jpg",
  "created_at": "2024-04-01T10:30:00Z"
}

Markers

Add markers to your maps to indicate points of interest, vehicle locations, or other important locations.

POST /v2/maps/markers

Create a new marker or set of markers

Request Body

{
  "markers": [
    {
      "position": {
        "lat": 37.7749,
        "lng": -122.4194
      },
      "title": "San Francisco",
      "icon": "pin",
      "color": "#FF5500",
      "metadata": {
        "population": 874961,
        "state": "California"
      }
    },
    {
      "position": {
        "lat": 40.7128,
        "lng": -74.0060
      },
      "title": "New York",
      "icon": "pin",
      "color": "#0055FF",
      "metadata": {
        "population": 8804190,
        "state": "New York"
      }
    }
  ]
}

Example Request

curl -X POST "https://api.nexus-platform.com/v2/maps/markers" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "markers": [
        {
          "position": {
            "lat": 37.7749,
            "lng": -122.4194
          },
          "title": "San Francisco",
          "icon": "pin",
          "color": "#FF5500",
          "metadata": {
            "population": 874961,
            "state": "California"
          }
        },
        {
          "position": {
            "lat": 40.7128,
            "lng": -74.0060
          },
          "title": "New York",
          "icon": "pin",
          "color": "#0055FF",
          "metadata": {
            "population": 8804190,
            "state": "New York"
          }
        }
      ]
    }'

Example Response

{
  "marker_set_id": "ms_123abc",
  "markers": [
    {
      "id": "m_abc1",
      "position": {
        "lat": 37.7749,
        "lng": -122.4194
      },
      "title": "San Francisco"
    },
    {
      "id": "m_abc2",
      "position": {
        "lat": 40.7128,
        "lng": -74.0060
      },
      "title": "New York"
    }
  ],
  "created_at": "2024-04-01T10:35:00Z"
}

Polygons & Polylines

Create polygons and polylines to represent areas, routes, and boundaries on your maps.

POST /v2/maps/polygons

Create a polygon on the map

Request Body

{
  "paths": [
    {"lat": 37.7858, "lng": -122.4064},
    {"lat": 37.7958, "lng": -122.4364},
    {"lat": 37.7758, "lng": -122.4464},
    {"lat": 37.7658, "lng": -122.4164}
  ],
  "fill_color": "#FF550055",
  "stroke_color": "#FF5500",
  "stroke_weight": 2,
  "metadata": {
    "name": "Downtown Area",
    "type": "business-district"
  }
}

Example Request

curl -X POST "https://api.nexus-platform.com/v2/maps/polygons" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "paths": [
        {"lat": 37.7858, "lng": -122.4064},
        {"lat": 37.7958, "lng": -122.4364},
        {"lat": 37.7758, "lng": -122.4464},
        {"lat": 37.7658, "lng": -122.4164}
      ],
      "fill_color": "#FF550055",
      "stroke_color": "#FF5500",
      "stroke_weight": 2,
      "metadata": {
        "name": "Downtown Area",
        "type": "business-district"
      }
    }'

Example Response

{
  "polygon_id": "poly_123abc",
  "paths": [
    {"lat": 37.7858, "lng": -122.4064},
    {"lat": 37.7958, "lng": -122.4364},
    {"lat": 37.7758, "lng": -122.4464},
    {"lat": 37.7658, "lng": -122.4164}
  ],
  "center": {
    "lat": 37.7808,
    "lng": -122.4264
  },
  "area_sqm": 12345.67,
  "created_at": "2024-04-01T10:40:00Z"
}
POST /v2/maps/polylines

Create a polyline on the map

Request Body

{
  "path": [
    {"lat": 37.7749, "lng": -122.4194},
    {"lat": 37.7850, "lng": -122.4074},
    {"lat": 37.7900, "lng": -122.4030},
    {"lat": 37.7950, "lng": -122.3980}
  ],
  "color": "#0055FF",
  "weight": 5,
  "metadata": {
    "name": "Route to Downtown",
    "distance_km": 3.5
  }
}

Example Request

curl -X POST "https://api.nexus-platform.com/v2/maps/polylines" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "path": [
        {"lat": 37.7749, "lng": -122.4194},
        {"lat": 37.7850, "lng": -122.4074},
        {"lat": 37.7900, "lng": -122.4030},
        {"lat": 37.7950, "lng": -122.3980}
      ],
      "color": "#0055FF",
      "weight": 5,
      "metadata": {
        "name": "Route to Downtown",
        "distance_km": 3.5
      }
    }'

Example Response

{
  "polyline_id": "line_123abc",
  "path": [
    {"lat": 37.7749, "lng": -122.4194},
    {"lat": 37.7850, "lng": -122.4074},
    {"lat": 37.7900, "lng": -122.4030},
    {"lat": 37.7950, "lng": -122.3980}
  ],
  "length_meters": 3500,
  "created_at": "2024-04-01T10:45:00Z"
}

Data Layers

Data layers allow you to visualize geospatial data on top of your maps, such as traffic, weather, or custom datasets.

GET /v2/maps/layers

List available data layers

Example Request

curl -X GET "https://api.nexus-platform.com/v2/maps/layers" \
    -H "Authorization: Bearer your_api_key"

Example Response

{
  "layers": [
    {
      "id": "traffic",
      "name": "Traffic",
      "description": "Real-time traffic conditions",
      "type": "overlay"
    },
    {
      "id": "weather",
      "name": "Weather",
      "description": "Current weather conditions",
      "type": "overlay"
    },
    {
      "id": "transit",
      "name": "Transit",
      "description": "Public transportation routes and stops",
      "type": "overlay"
    },
    {
      "id": "bicycle",
      "name": "Bicycle Lanes",
      "description": "Bicycle lanes and paths",
      "type": "overlay"
    }
  ]
}
POST /v2/maps/layers/custom

Create a custom data layer from GeoJSON

Request Body

{
  "name": "Coffee Shops",
  "description": "Locations of coffee shops in San Francisco",
  "geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [-122.4194, 37.7749]
        },
        "properties": {
          "name": "Downtown Coffee",
          "rating": 4.5
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [-122.4074, 37.7850]
        },
        "properties": {
          "name": "North Beach Café",
          "rating": 4.8
        }
      }
    ]
  },
  "style": {
    "marker_icon": "coffee",
    "marker_color": "#8B4513"
  }
}

Example Request

curl -X POST "https://api.nexus-platform.com/v2/maps/layers/custom" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Coffee Shops",
      "description": "Locations of coffee shops in San Francisco",
      "geojson": {
        "type": "FeatureCollection",
        "features": [
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [-122.4194, 37.7749]
            },
            "properties": {
              "name": "Downtown Coffee",
              "rating": 4.5
            }
          },
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [-122.4074, 37.7850]
            },
            "properties": {
              "name": "North Beach Café",
              "rating": 4.8
            }
          }
        ]
      },
      "style": {
        "marker_icon": "coffee",
        "marker_color": "#8B4513"
      }
    }'

Example Response

{
  "layer_id": "layer_coffee_123",
  "name": "Coffee Shops",
  "description": "Locations of coffee shops in San Francisco",
  "feature_count": 2,
  "bounds": {
    "northeast": {"lat": 37.7850, "lng": -122.4074},
    "southwest": {"lat": 37.7749, "lng": -122.4194}
  },
  "created_at": "2024-04-01T10:50:00Z"
}

Marker Clustering

Marker clustering allows you to group nearby markers together to improve map performance and readability.

POST /v2/maps/markers/cluster

Create a clustered marker set

Request Body

{
  "markers": [
    {"lat": 37.7749, "lng": -122.4194, "title": "Location 1"},
    {"lat": 37.7750, "lng": -122.4195, "title": "Location 2"},
    {"lat": 37.7751, "lng": -122.4196, "title": "Location 3"},
    {"lat": 40.7128, "lng": -74.0060, "title": "Location 4"},
    {"lat": 40.7129, "lng": -74.0061, "title": "Location 5"}
  ],
  "cluster_radius": 50,
  "cluster_min_size": 2,
  "cluster_colors": ["#FF5500", "#FFAA00", "#00AA00"]
}

Example Request

curl -X POST "https://api.nexus-platform.com/v2/maps/markers/cluster" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "markers": [
        {"lat": 37.7749, "lng": -122.4194, "title": "Location 1"},
        {"lat": 37.7750, "lng": -122.4195, "title": "Location 2"},
        {"lat": 37.7751, "lng": -122.4196, "title": "Location 3"},
        {"lat": 40.7128, "lng": -74.0060, "title": "Location 4"},
        {"lat": 40.7129, "lng": -74.0061, "title": "Location 5"}
      ],
      "cluster_radius": 50,
      "cluster_min_size": 2,
      "cluster_colors": ["#FF5500", "#FFAA00", "#00AA00"]
    }'

Example Response

{
  "cluster_id": "cls_123abc",
  "marker_count": 5,
  "cluster_count": 2,
  "clusters": [
    {
      "center": {"lat": 37.7750, "lng": -122.4195},
      "count": 3,
      "bounds": {
        "northeast": {"lat": 37.7751, "lng": -122.4194},
        "southwest": {"lat": 37.7749, "lng": -122.4196}
      }
    },
    {
      "center": {"lat": 40.7128, "lng": -74.0060},
      "count": 2,
      "bounds": {
        "northeast": {"lat": 40.7129, "lng": -74.0060},
        "southwest": {"lat": 40.7128, "lng": -74.0061}
      }
    }
  ],
  "created_at": "2024-04-01T10:55:00Z"
}

Heatmaps

Create heatmaps to visualize density of data points on your maps.

POST /v2/maps/heatmaps

Create a heatmap layer

Request Body

{
  "name": "Traffic Density",
  "points": [
    {"lat": 37.7749, "lng": -122.4194, "weight": 1.0},
    {"lat": 37.7750, "lng": -122.4195, "weight": 0.8},
    {"lat": 37.7751, "lng": -122.4196, "weight": 0.6},
    {"lat": 37.7748, "lng": -122.4193, "weight": 0.9},
    {"lat": 37.7747, "lng": -122.4192, "weight": 0.7}
  ],
  "gradient": ["#00FF00", "#FFFF00", "#FF0000"],
  "radius": 20,
  "opacity": 0.7
}

Example Request

curl -X POST "https://api.nexus-platform.com/v2/maps/heatmaps" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Traffic Density",
      "points": [
        {"lat": 37.7749, "lng": -122.4194, "weight": 1.0},
        {"lat": 37.7750, "lng": -122.4195, "weight": 0.8},
        {"lat": 37.7751, "lng": -122.4196, "weight": 0.6},
        {"lat": 37.7748, "lng": -122.4193, "weight": 0.9},
        {"lat": 37.7747, "lng": -122.4192, "weight": 0.7}
      ],
      "gradient": ["#00FF00", "#FFFF00", "#FF0000"],
      "radius": 20,
      "opacity": 0.7
    }'

Example Response

{
  "heatmap_id": "heat_123abc",
  "name": "Traffic Density",
  "point_count": 5,
  "bounds": {
    "northeast": {"lat": 37.7751, "lng": -122.4192},
    "southwest": {"lat": 37.7747, "lng": -122.4196}
  },
  "created_at": "2024-04-01T11:00:00Z"
}

Map Events

The Maps API provides WebSocket endpoints to receive real-time map events.

GET /v2/maps/events/connect

Connect to a WebSocket for real-time map events

Query Parameters

Parameter Type Required Description
token string Yes API key or access token
events string No Comma-separated list of event types to subscribe to (default: all)

WebSocket Events

Event Type Description
marker.added A new marker has been added to the map
marker.updated A marker has been updated (position, properties, etc.)
marker.removed A marker has been removed from the map
layer.added A new layer has been added to the map
layer.updated A layer has been updated
layer.removed A layer has been removed from the map

Example WebSocket Connection

const socket = new WebSocket('wss://api.nexus-platform.com/v2/maps/events/connect?token=your_api_key&events=marker.updated,marker.added');

socket.onopen = () => {
  console.log('Connected to Maps API events');
};

socket.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received event:', data);
  
  // Handle different event types
  switch (data.type) {
    case 'marker.added':
      console.log('New marker added:', data.marker);
      break;
    case 'marker.updated':
      console.log('Marker updated:', data.marker);
      break;
  }
};

socket.onclose = () => {
  console.log('Disconnected from Maps API events');
};

Next Steps

Navigation API

Implement turn-by-turn navigation and routing capabilities.

Explore Navigation API →

Search API

Add geocoding, address search, and place search functionality.

Explore Search API →

Code Examples

See examples of implementing the Maps API in your applications.

View Examples →