The REST surface
Most map work needs none of this — tiles are read directly by the client. These endpoints exist for the server-side jobs: discovering what layers exist, resolving paths, and pulling offline packages.
Authentication
Every /api/v1/* endpoint requires an API key, passed either as a header or a query parameter. Requests without one are rejected with 401.
# Header (preferred)
curl https://www.mapsfordevelopers.com/api/v1/layers \
-H "x-api-key: $MFD_API_KEY"
# Query parameter, where a header is impractical
curl "https://www.mapsfordevelopers.com/api/v1/layers?api_key=$MFD_API_KEY"Keys are issued by hand during early access. Request one here. Treat the key as a secret: it belongs on your server, not in a browser bundle.
Endpoints
/api/v1/layersReturns the catalogue of available layers with their archive paths, coverage and offline availability. This is the reliable way to resolve which archive to use for a given state rather than guessing at a filename.
| Parameter | Type | Description |
|---|---|---|
| category | string | Filter by layer group. One of base, enrichment, hunting or all. Defaults to all. |
| state | string | Two-letter state code. Returns nationwide layers plus that state’s, with paths resolved. |
curl "https://www.mapsfordevelopers.com/api/v1/layers?state=TX" \
-H "x-api-key: $MFD_API_KEY"/api/v1/tiles/{path}Authenticated proxy to a tile archive, for server-side consumers that cannot run the browser token flow. Range requests are supported and expected.
/api/v1/searchFree-text place search, optionally constrained to a bounding box. Rate-limited and cached upstream, so treat it as interactive lookup rather than batch work.
| Parameter | Type | Description |
|---|---|---|
| q* | string | The search text. |
| type | string | address, poi, parcel or all. Defaults to all. |
| bbox | string | minLon,minLat,maxLon,maxLat — restricts results to a box. |
| limit | number | Maximum results. Defaults to 10. |
/api/v1/geocodeAddress to coordinate lookup. Provided as a convenience for light use; it is not intended as a bulk or high-throughput geocoder, and rate limits are deliberately conservative. If geocoding is central to your product, talk to us before you build on it.
| Parameter | Type | Description |
|---|---|---|
| q* | string | Address or place text. |
| limit | number | Maximum results. Defaults to 5. |
/api/v1/offline/{path}Downloads an offline tile package for use with no connectivity. Available on paid plans.
Responses and errors
| Status | Meaning |
|---|---|
| 200 | Success. |
| 400 | A required parameter is missing or malformed. |
| 401 | No API key was supplied. |
| 403 | The key is invalid, or lacks permission for this endpoint. |
| 429 | The gateway’s rolling byte budget was hit. Plan quotas are not metered yet — see below. |
| 5xx | Our problem. Check /status, then tell us. |
Errors return JSON with an error field describing what went wrong.
On quotas, honestly
The per-month figures on the pricing page are the plan you are buying, but they are not yet enforced by a meter — during early access we watch usage and talk to you rather than cutting anything off automatically. What is enforced today is the tile gateway's rolling per-client byte budget, which exists to stop bulk extraction rather than to police your plan. Responses carry X-Tiles-Metered: false while that remains true.