API Documentation

Welcome to the Map.PublicVM developer documentation. This guide covers everything you need to integrate our mapping and geolocation services into your web or mobile applications.

Getting Started

Before you begin, you will need an API key. Contact our team at contact@map.publicvm.com to request access and generate credentials.

All API requests use HTTPS and return JSON responses. Base URL for all endpoints:

BASE https://api.map.publicvm.com/v1

Authentication

Include your API key in every request header using the Authorization field:

Authorization: Bearer YOUR_API_KEY

Keep your API key secure. Do not expose it in client-side code or public repositories. Use environment variables or a backend proxy for production applications.

API Endpoints

All endpoints accept HTTPS requests and return JSON. Authenticate every request with your API key in the Authorization header. See the sections below for detailed usage of each endpoint group.

Geolocation

IP Geolocation Lookup

Retrieve country, region, city, and coordinate data for any IPv4 or IPv6 address.

GET /geolocate?ip=192.0.2.1

curl -X GET "https://api.map.publicvm.com/v1/geolocate?ip=192.0.2.1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sample response:

{
  "ip": "192.0.2.1",
  "country": "United States",
  "country_code": "US",
  "region": "California",
  "city": "San Francisco",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "timezone": "America/Los_Angeles"
}

Reverse Geocoding

Convert latitude and longitude coordinates into a human-readable address string.

GET /reverse?lat=37.7749&lng=-122.4194

curl -X GET "https://api.map.publicvm.com/v1/reverse?lat=37.7749&lng=-122.4194" \
  -H "Authorization: Bearer YOUR_API_KEY"

Map Tiles

Access vector or raster map tiles to render fully customizable maps in your application.

GET /tiles/{style}/{z}/{x}/{y}.pbf

Supported styles: basic, streets, satellite, dark

curl -X GET "https://api.map.publicvm.com/v1/tiles/streets/10/512/340.pbf" \
  -H "Authorization: Bearer YOUR_API_KEY"

Vector tiles use the Mapbox Vector Tile (MVT) specification and are compatible with Mapbox GL JS, MapLibre GL, and other PBF-compatible renderers.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of each request:

200 — Success
400 — Bad Request (invalid or missing parameters)
401 — Unauthorized (invalid or missing API key)
404 — Not Found (resource does not exist)
429 — Too Many Requests (rate limit exceeded)
500 — Internal Server Error

All error responses include a JSON body with a machine-readable code and a human-readable message:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is not valid."
  }
}

Rate Limits

API requests are rate-limited to protect service stability and ensure fair usage across all clients. Default limits by plan:

Free tier: 100 requests per minute
Pro tier: 1,000 requests per minute
Enterprise: Custom limits — contact us

Rate limit metadata is included in every API response header:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699900000

When the limit is exceeded, the API returns a 429 status. Implement exponential back-off in your client to handle these gracefully.

SDKs and Libraries

Official client libraries are available for popular languages to simplify integration and reduce boilerplate:

JavaScript / Node.js: npm install @map-publicvm/sdk
Python: pip install map-publicvm
PHP: composer require map-publicvm/client

Need help? Contact our developer support team at contact@map.publicvm.com for technical assistance or integration questions.