# Map Zone Maps API — Philippines

> Vector basemap (MapLibre GL style/tiles/fonts/sprites), geocoding/autocomplete, and directions/distance matrix
> for the Philippines. One gateway, one auth scheme across all three: an API key on the query string, accepted
> under either `key` or `apikey`.

Base URL: `https://ph.map.zone`. HTTP status codes are standard for Tiles; Geocoding and Routing are
Google-compatible (HTTP always 200, errors reported in the JSON `status` field, snake_case field names).

**For a full copy-paste integration guide** (working code for the basemap, autocomplete, place details,
geocoding, reverse geocoding, directions, TSP, and distance matrix - paste the whole thing into an agent's
context to build an integration in one pass): [llms-full.txt](llms-full.txt).

## API specs (OpenAPI 3.1, machine-readable)

- [Tiles API spec](specs/tiles-api.openapi.yaml): style.json, vector tiles, font glyphs, sprites.
- [Geocoding API spec](specs/geocoding-api.openapi.yaml): autocomplete, place details, forward/reverse geocode.
- [Routing API spec](specs/routing-api.openapi.yaml): directions (incl. TSP via `optimize:true`), distance matrix.
- [Consolidated reference](api-reference.md): all three APIs in one plain-markdown file, same content as the
  site's [overview page](index.html), no HTML/JS required to read it.

## Human-readable reference (same specs, full per-endpoint detail incl. schemas and examples)

- [Tiles API reference](tiles.html)
- [Geocoding API reference](geocoding.html)
- [Routing API reference](routing.html)
- [Interactive playground](playground.html): paste a real API key, call the live endpoints, see results on an
  actual map (Swagger UI + MapLibre GL JS side by side). Useful for verifying a request shape before writing code.

## Minimal MapLibre GL JS usage (Tiles API)

The style endpoint returns a complete MapLibre GL Style Spec - pass its URL directly as `style`, no further
rewriting needed. Tile/glyph/sprite URLs inside the style already point back at this same API.

```js
import maplibregl from "maplibre-gl"; // https://maplibre.org/maplibre-gl-js/

const map = new maplibregl.Map({
  container: "map",
  style: "https://ph.map.zone/maps/styles/basemap-phl/style.json?apikey=YOUR_API_KEY",
  center: [121.0, 14.6], // [lng, lat] - Metro Manila
  zoom: 11,
});
```

`basemap-phl` is the only style name currently published. No further MapLibre configuration (sources, transformRequest,
sprite/glyph URLs) is required - the style document is fully self-describing.

## Auth

Append `apikey=YOUR_KEY` or `key=YOUR_KEY` to any request (both accepted on all three APIs). No headers, no
OAuth, no signing. Get a key via the contact link on the [overview page](index.html).

## Notes for automated integration

- No SDK/client library is published; call the HTTP endpoints directly (fetch/curl/any HTTP client).
- No redirects are ever returned by design - a 3xx response indicates a misconfigured request, not a normal flow.
- Geocoding/Routing: always check the JSON `status` field; HTTP 200 does not imply success (`status: "OK"` does).
- Tiles: 204 (no body) is a normal, valid empty tile - not an error.