API Documentation

Everything you need to integrate OpenMap API into your application.

Quick Start

1. Get your API key

Authentication

All API requests require authentication via the X-API-Key header.

curl "https://api.openmap.ph/v1/geocode?address=Manila" \
  -H "X-API-Key: your-api-key"

Quotas & Rate Limits

Each endpoint has its own monthly quota. Check the response headers for your current usage:

X-Quota-Limit - Monthly quota for this endpoint
X-Quota-Used - Requests used this month
X-Quota-Remaining - Remaining quota
X-Quota-Reset - When quota resets

Monthly Quotas by Plan

Endpoint	Free	Premium ($5/mo)
Geocoding	1,000	20,000 + overage
Reverse Geocoding	1,000	20,000 + overage
Routing	500	10,000 + overage
Distance Matrix	500	10,000 + overage

Free plan: API returns 429 when exceeded. Premium: pay-as-you-go overage billing.

Route Avoidance (Premium)

Premium users can avoid specific road types when calculating routes. When avoidance is enabled, routes are calculated using the Valhalla engine.

Avoid Types

Type	Description
tolls	Avoid toll roads and expressways
highways	Avoid highways and major expressways
ferries	Avoid ferry crossings
unpaved	Avoid unpaved/gravel roads

Example: Avoid Tolls

curl "https://api.openmap.ph/v1/route?origin=14.5995,120.9842&destination=14.5547,121.0244&avoid=tolls" \
  -H "X-API-Key: your-api-key"

Example: Avoid Multiple Types

curl "https://api.openmap.ph/v1/route?origin=14.5995,120.9842&destination=14.5547,121.0244&avoid=tolls,highways" \
  -H "X-API-Key: your-api-key"

Advanced: Polygon Avoidance (POST)

For custom area avoidance, use the POST endpoint with polygon coordinates:

curl -X POST "https://api.openmap.ph/v1/route" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "14.5995,120.9842",
    "destination": "14.5547,121.0244",
    "avoid": {
      "types": ["tolls"],
      "polygons": [{
        "coordinates": [
          [121.0, 14.5],
          [121.1, 14.5],
          [121.1, 14.6],
          [121.0, 14.6]
        ]
      }]
    }
  }'

Note: Route avoidance uses the Valhalla routing engine. The response will include meta.engine: "valhalla" to indicate which engine was used.

API Reference

Geocoding

Convert addresses to coordinates (forward geocoding) or coordinates to addresses (reverse geocoding).

GET/api/v1/geocode

Convert an address to coordinates

Parameters

Name	Type	Required	Description
address	string	Yes	The address to geocode
limit	number	No	Max results (default: 5)

Example Request

curl "https://api.openmap.ph/v1/geocode?address=Makati%20City" \
  -H "X-API-Key: your-api-key"

Example Response

{
  "success": true,
  "data": {
    "lat": 14.5547,
    "lng": 121.0244,
    "display_name": "Makati, Metro Manila, Philippines",
    "type": "city"
  }
}

GET/api/v1/geocode/reverse

Convert coordinates to an address

Parameters

Name	Type	Required	Description
lat	number	Yes	Latitude
lng	number	Yes	Longitude

Example Request

curl "https://api.openmap.ph/v1/geocode/reverse?lat=14.5547&lng=121.0244" \
  -H "X-API-Key: your-api-key"

Example Response

{
  "success": true,
  "data": {
    "display_name": "Ayala Avenue, Makati, Metro Manila, Philippines",
    "address": {
      "road": "Ayala Avenue",
      "city": "Makati",
      "region": "Metro Manila",
      "country": "Philippines"
    }
  }
}

Routing

Calculate driving routes between two points with distance, duration, and optional avoidance.

GET/api/v1/route

Get driving directions between two points

Parameters

Name	Type	Required	Description
origin	string	Yes	Origin coordinates (lat,lng)
destination	string	Yes	Destination coordinates (lat,lng)
avoid	string	No	Comma-separated: tolls, highways, ferries, unpaved (Premium)
mode	string	No	Travel mode: driving, walking, cycling (default: driving)

Example Request

curl "https://api.openmap.ph/v1/route?origin=14.5995,120.9842&destination=14.5547,121.0244&avoid=tolls,highways" \
  -H "X-API-Key: your-api-key"

Example Response

{
  "success": true,
  "data": {
    "distance": 8542,
    "duration": 1245,
    "distance_text": "8.5 km",
    "duration_text": "21 mins",
    "geometry": "encoded_polyline_here"
  },
  "meta": {
    "engine": "valhalla"
  }
}

Distance Matrix

Calculate distances and durations between multiple origin-destination pairs.

POST/api/v1/matrix

Calculate distance matrix

Parameters

Name	Type	Required	Description
origins	array	Yes	Array of origin coordinates
destinations	array	Yes	Array of destination coordinates

Example Request

curl -X POST "https://api.openmap.ph/v1/matrix" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "origins": ["14.5995,120.9842", "14.5547,121.0244"],
    "destinations": ["14.6091,121.0223", "14.5896,120.9812"]
  }'

Example Response

{
  "success": true,
  "data": {
    "distances": [[5234, 3421], [2156, 4532]],
    "durations": [[845, 612], [423, 756]]
  }
}

Need Help?

Can't find what you're looking for? We're here to help.

Contact Support Try API Demo