Getting Started with the MapEmbed API

The MapEmbed API gives you complete programmatic control over your maps, allowing you to build custom integrations, automate map creation, and sync map data with your existing systems. Whether you're building a property management platform, a fleet tracking app, or a location-based service, our API provides all the tools you need.

📋 Before You Begin

You'll need:

✓ A MapEmbed account (Free, Pro, or Enterprise)
✓ Your API key from the Dashboard
✓ Basic knowledge of REST APIs and JSON
✓ A tool to make HTTP requests (curl, Postman, or your favorite language)

Step 1: Get Your API Key

First, you'll need to generate an API key from your dashboard:

Log into your MapEmbed account
Navigate to Settings → API Keys
Click "Generate New API Key"
Copy your key and store it securely (it won't be shown again!)

🔐 Security Best Practices

• Never commit API keys to version control
• Use environment variables to store keys
• Rotate keys regularly (every 90 days)
• Use different keys for development and production

Step 2: Authenticate Your Requests

All API requests must include your API key in the Authorization header:

Bash - curl example

curl -X GET https://api.mapembed.com/v1/maps \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

✓ Correct


                            Authorization: Bearer mpe_live_abc123xyz...

❌ Incorrect


                            Authorization: mpe_live_abc123xyz...

Missing "Bearer" prefix

Step 3: Create Your First Map

Let's create a simple map with a few markers using the POST /maps endpoint:

JavaScript - Create Map

const createMap = async () => {
  const response = await fetch('https://api.mapembed.com/v1/maps', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MAPEMBED_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: "Coffee Shops in San Francisco",
      description: "Best coffee spots in SF",
      center: {
        lat: 37.7749,
        lng: -122.4194
      },
      zoom: 12,
      markers: [
        {
          lat: 37.7849,
          lng: -122.4094,
          title: "Blue Bottle Coffee",
          description: "Artisanal coffee roaster",
          icon: "☕"
        },
        {
          lat: 37.7649,
          lng: -122.4294,
          title: "Philz Coffee",
          description: "Customize your own blend",
          icon: "☕"
        }
      ],
      style: "standard",
      isPublic: false
    })
  });

  const map = await response.json();
  console.log('Map created:', map);
  return map;
};

Response (201 Created)

{
  "id": "map_abc123xyz",
  "name": "Coffee Shops in San Francisco",
  "embedUrl": "https://mapembed.com/map/abc123xyz",
  "createdAt": "2026-01-10T10:30:00Z",
  "status": "draft"
}

Step 4: Retrieve Your Maps

Get a list of all your maps with pagination and filtering:

Python - List Maps

import requests
import os

API_KEY = os.environ.get('MAPEMBED_API_KEY')
BASE_URL = 'https://api.mapembed.com/v1'

def get_maps(page=1, limit=10, status=None):
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
    
    params = {
        'page': page,
        'limit': limit
    }
    
    if status:
        params['status'] = status  # 'draft', 'published', 'archived'
    
    response = requests.get(
        f'{BASE_URL}/maps',
        headers=headers,
        params=params
    )
    
    return response.json()

# Get all published maps
published_maps = get_maps(status='published')
print(f"Total: {published_maps['total']}")
print(f"Maps: {len(published_maps['data'])}")

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (max: 100)
`status`	string	Filter by status
`search`	string	Search map names

Step 5: Update Map Details

Modify existing maps using the PUT /maps/:id endpoint:

cURL - Update Map

curl -X PUT https://api.mapembed.com/v1/maps/map_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Coffee & Bakeries in San Francisco",
    "description": "Updated with bakeries!",
    "markers": [
      {
        "lat": 37.7849,
        "lng": -122.4094,
        "title": "Blue Bottle Coffee",
        "description": "Artisanal coffee roaster",
        "icon": "☕"
      },
      {
        "lat": 37.7750,
        "lng": -122.4183,
        "title": "Tartine Bakery",
        "description": "Famous sourdough bread",
        "icon": "🥖"
      }
    ]
  }'

💡 Pro Tip: Partial Updates

You can update individual fields without sending the entire map object. Only include the fields you want to change.

Step 6: Add Markers Dynamically

Add markers to existing maps without re-creating them:

Node.js - Add Markers in Bulk

const axios = require('axios');

const addMarkersFromCSV = async (mapId, csvData) => {
  const markers = csvData.map(row => ({
    lat: parseFloat(row.latitude),
    lng: parseFloat(row.longitude),
    title: row.name,
    description: row.description,
    icon: row.category === 'restaurant' ? '🍽️' : '📍'
  }));

  const response = await axios.post(
    `https://api.mapembed.com/v1/maps/${mapId}/markers/bulk`,
    { markers },
    {
      headers: {
        'Authorization': `Bearer ${process.env.MAPEMBED_API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );

  console.log(`Added ${response.data.count} markers`);
  return response.data;
};

// Example usage
const locations = [
  { latitude: 37.7749, longitude: -122.4194, name: "Location 1", ... },
  { latitude: 37.7849, longitude: -122.4094, name: "Location 2", ... }
];

addMarkersFromCSV('map_abc123xyz', locations);

Step 7: Publish Your Map

Make your map publicly accessible by publishing it:

Ruby - Publish Map

require 'net/http'
require 'json'

def publish_map(map_id)
  uri = URI("https://api.mapembed.com/v1/maps/#{map_id}/publish")
  
  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = "Bearer #{ENV['MAPEMBED_API_KEY']}"
  request['Content-Type'] = 'application/json'
  
  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end
  
  JSON.parse(response.body)
end

# Publish the map
result = publish_map('map_abc123xyz')
puts "Map published at: #{result['publicUrl']}"
# => "https://mapembed.com/map/abc123xyz"

📍 Publish

POST /maps/:id/publish

Makes map publicly accessible. Returns public URL.

🔒 Unpublish

POST /maps/:id/unpublish

Revokes public access. Map becomes private.

Step 8: Retrieve Analytics

Track how your maps are performing with detailed analytics:

TypeScript - Get Analytics

interface AnalyticsParams {
  mapId: string;
  startDate: string;  // ISO 8601 format
  endDate: string;
  granularity?: 'day' | 'week' | 'month';
}

async function getMapAnalytics(params: AnalyticsParams) {
  const { mapId, startDate, endDate, granularity = 'day' } = params;
  
  const queryParams = new URLSearchParams({
    start_date: startDate,
    end_date: endDate,
    granularity
  });
  
  const response = await fetch(
    `https://api.mapembed.com/v1/maps/${mapId}/analytics?${queryParams}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.MAPEMBED_API_KEY}`
      }
    }
  );
  
  return response.json();
}

// Get last 30 days of analytics
const analytics = await getMapAnalytics({
  mapId: 'map_abc123xyz',
  startDate: '2026-01-01',
  endDate: '2026-01-31',
  granularity: 'day'
});

console.log(`Total views: ${analytics.totalViews}`);
console.log(`Unique viewers: ${analytics.uniqueViewers}`);
console.log(`Avg time on map: ${analytics.avgTimeOnMap}s`);

Available Metrics

📊

Total Views

👥

Unique Viewers

⏱️

Time on Map

🖱️

Interactions

Understanding Rate Limits

To ensure fair usage and service stability, the API enforces rate limits:

Plan	Requests/Hour	Burst Limit
Free	1,000	100/min
Pro	10,000	500/min
Enterprise	Unlimited*	Custom

* Subject to fair use policy. Contact sales for custom limits.

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1641895200

Error Handling

The API uses standard HTTP status codes and provides detailed error messages:

200 OK

Request succeeded

201 Created

Resource created successfully

400 Bad Request

Invalid request parameters

401 Unauthorized

Invalid or missing API key

429 Too Many Requests

Rate limit exceeded

Error Response Example

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid latitude value",
    "details": {
      "field": "markers[0].lat",
      "value": "invalid",
      "expected": "number between -90 and 90"
    }
  }
}

Next Steps

You now have the basics of the MapEmbed API! Here's what to explore next:

📖 Full API Reference

Explore all endpoints, parameters, and response schemas

View Documentation →

🔧 SDK Libraries

Official client libraries for Python, Node.js, Ruby, PHP

Browse SDKs →

💬 Community Forum

Ask questions and share your integrations

Join Community →

📚 Code Examples

Real-world integration examples and use cases

View Examples →