API Documentation

Everything you need to integrate MapHighlight into your application.

Quick Start

Get started with MapHighlight in under 5 minutes. Generate your first map with a simple API call.

cURL
curl "https://api.maphighlight.com/v1/map?countries=USA,CAN,MEX&color=3498db&format=png" \
  -H "Authorization: Bearer YOUR_API_KEY"

Fast

Sub-500ms response times globally

Simple

RESTful API with intuitive parameters

Global

All 177 countries supported

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header.

Header
Authorization: Bearer YOUR_API_KEY

Note: Keep your API key secure. Never expose it in client-side code or public repositories.

API Endpoints

GET/v1/map

Generate a map with highlighted countries.

Base URL: https://api.maphighlight.com

Parameters

countriesRequired
String

Comma-separated list of ISO 3166-1 alpha-3 country codes to highlight.

countries=USA,CAN,MEX
colorOptional
String

Hex color code for highlighted countries (without #). Default: 3498db

color=e74c3c
formatOptional
String

Output format: png, svg, or html. Default: png

format=svg
widthOptional
Integer

Width in pixels (PNG only). Range: 400-4000. Default: 1200

width=1920
backgroundOptional
String

Background color hex code (without #). Default: ffffff

background=f8f9fa

Response Formats

PNG (Raster)

High-quality raster image. Best for embedding in documents, emails, or when exact pixel control is needed.

  • Content-Type: image/png
  • Typical size: 50-200 KB
  • Supports custom width parameter

SVG (Vector)

Scalable vector graphics. Best for responsive designs, print, or when infinite scaling is required.

  • Content-Type: image/svg+xml
  • Typical size: 10-50 KB
  • Scales without quality loss

HTML (Interactive)

Embeddable HTML with interactive features. Best for web applications requiring tooltips or click events.

  • Content-Type: text/html
  • Includes country hover effects
  • Responsive and mobile-friendly

Code Examples

JavaScript / Node.js

JavaScript
const response = await fetch(
  'https://api.maphighlight.com/v1/map?countries=USA,CAN,MEX&color=3498db&format=png',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const blob = await response.blob();
const imageUrl = URL.createObjectURL(blob);

// Use imageUrl in <img> tag
document.getElementById('map').src = imageUrl;

Python

Python
import requests

url = "https://api.maphighlight.com/v1/map"
params = {
    "countries": "USA,CAN,MEX",
    "color": "3498db",
    "format": "png"
}
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get(url, params=params, headers=headers)

with open("map.png", "wb") as f:
    f.write(response.content)

React

React
import { useState, useEffect } from 'react';

function MapComponent({ countries }) {
  const [mapUrl, setMapUrl] = useState('');

  useEffect(() => {
    const fetchMap = async () => {
      const params = new URLSearchParams({
        countries: countries.join(','),
        color: '3498db',
        format: 'png'
      });

      const response = await fetch(
        `https://api.maphighlight.com/v1/map?${params}`,
        {
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY'
          }
        }
      );

      const blob = await response.blob();
      setMapUrl(URL.createObjectURL(blob));
    };

    fetchMap();
  }, [countries]);

  return <img src={mapUrl} alt="Map" />;
}

Rate Limits

PlanMonthly LimitRate Limit
Free1,000 maps10 req/min
Starter25,000 maps60 req/min
Pro250,000 maps300 req/min
EnterpriseUnlimitedCustom

Rate Limit Headers: Each response includes X-RateLimit-Remaining and X-RateLimit-Reset headers.

Error Handling

The API uses standard HTTP status codes. All error responses include a JSON body with details.

400Bad Request

Invalid parameters or missing required fields.

401Unauthorized

Invalid or missing API key.

429Too Many Requests

Rate limit exceeded. Check X-RateLimit-Reset header.

500Internal Server Error

Server error. Contact support if persistent.

Error Response
{
  "error": {
    "code": "INVALID_COUNTRY",
    "message": "Invalid country code: XYZ",
    "details": "Use ISO 3166-1 alpha-3 codes"
  }
}

Best Practices

Cache Responses

Cache generated maps on your server or CDN to reduce API calls and improve performance.

Use SVG for Web

SVG format provides smaller file sizes and better scalability for web applications.

Handle Rate Limits

Implement exponential backoff when receiving 429 responses. Monitor rate limit headers.

Validate Country Codes

Validate country codes client-side before making API calls to reduce errors.

Secure Your API Key

Never expose API keys in client-side code. Use server-side proxies for frontend applications.

Need Help?

Can't find what you're looking for? Our support team is here to help.

Contact Support