Quick Start
Get started with MapHighlight in under 5 minutes. Generate your first map with a simple API call.
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.
Authorization: Bearer YOUR_API_KEYNote: Keep your API key secure. Never expose it in client-side code or public repositories.
API Endpoints
/v1/mapGenerate a map with highlighted countries.
Base URL: https://api.maphighlight.com
Parameters
countriesRequiredComma-separated list of ISO 3166-1 alpha-3 country codes to highlight.
countries=USA,CAN,MEXcolorOptionalHex color code for highlighted countries (without #). Default: 3498db
color=e74c3cformatOptionalOutput format: png, svg, or html. Default: png
format=svgwidthOptionalWidth in pixels (PNG only). Range: 400-4000. Default: 1200
width=1920backgroundOptionalBackground color hex code (without #). Default: ffffff
background=f8f9faResponse 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
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
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
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
| Plan | Monthly Limit | Rate Limit |
|---|---|---|
| Free | 1,000 maps | 10 req/min |
| Starter | 25,000 maps | 60 req/min |
| Pro | 250,000 maps | 300 req/min |
| Enterprise | Unlimited | Custom |
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.
Invalid parameters or missing required fields.
Invalid or missing API key.
Rate limit exceeded. Check X-RateLimit-Reset header.
Server error. Contact support if persistent.
{
"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.