canonical: https://jentic.com/apis/gpxz/gpxz

# GPXZ Elevation API

Jentic publishes the only available OpenAPI specification for GPXZ Elevation API, keeping it validated and agent-ready. GPXZ is a worldwide elevation lookup service that returns high-resolution terrain data for single points, batches of points, sampled paths, and 2D raster extracts. It also exposes drop-in compatibility endpoints for Google Maps Elevation API and Open Topo Data, making migration from those services a header-and-host swap. The 11-endpoint surface covers point lookups, path sampling, raster export, source metadata, and a health probe.

## For AI agents

Look up high-resolution elevation worldwide for single or many points, sample elevation along a path, or pull a 2D raster extract. Includes Google Maps Elevation and Open Topo Data drop-in compatibility.

## Scope

Does not handle geocoding, routing, or weather data - use for elevation lookups and elevation rasters only.

## Capabilities

- Look up elevation for a single coordinate via GET `/elevation/point`
- Batch elevation lookups for many coordinates with GET or POST `/elevation/points`
- Sample elevation along a polyline path via `/elevation/sample`
- Export a 2D high-resolution elevation raster through `/elevation/hires-raster`
- Drop-in replace Google Maps Elevation API via `/elevation/gmaps-compat/{outputFormat}`
- Drop-in replace Open Topo Data API via `/elevation/otd-compat`
- Inspect available elevation source datasets with `/elevation/sources`

## Use cases

### Outdoor Route Profile Generation

Hiking, cycling, and running apps build elevation profiles by sending a polyline to `/elevation/sample` and rendering the returned series as a chart. The endpoint accepts the path geometry and a sample count, returning evenly-spaced elevations across the route. Coverage and resolution depend on the underlying source dataset, which can be inspected via `/elevation/sources.`

Example prompt: POST `/elevation/sample` with a 50-point GeoJSON LineString and samples=200, then return the elevation series for chart rendering.

### Drop-In Migration from Google Maps Elevation

Teams hitting Google Maps Elevation API quotas migrate to GPXZ via `/elevation/gmaps-compat/{outputFormat}`, which mirrors Google's request and response shapes. The agent only needs to swap the host and supply the GPXZ x-api-key - query parameters and JSON shape stay the same, so application code does not change. The compatibility endpoint is bound by GPXZ's source coverage rather than Google's.

Example prompt: Repoint application traffic from maps.googleapis.com/maps/api/elevation/json to https://api.gpxz.io/v1/elevation/gmaps-compat/json with x-api-key header and verify response equivalence.

### Bulk Elevation for Geospatial Pipelines

Geospatial pipelines processing thousands of points use POST `/elevation/points` to avoid per-point HTTP overhead. The endpoint accepts an array of coordinates and returns elevations in matching order, making it the high-throughput entry point for terrain enrichment in ETL jobs. Single-point `/elevation/point` exists for low-volume interactive workflows.

Example prompt: POST `/elevation/points` with 1000 lat/lng pairs from a CSV and merge the elevation array back into the source rows.

### 2D Raster Export for Local Modelling

Hydrology, viewshed, and slope analyses need a 2D raster patch rather than point samples. GET `/elevation/hires-raster` returns a high-resolution elevation grid for a bounding box, ready to load into rasterio, GDAL, or QGIS. Resolution and format are bounded by what the underlying sources expose for the requested area.

Example prompt: GET `/elevation/hires-raster` with a bounding box for a watershed and load the response into rasterio for slope computation.

### Agent-Driven Elevation Lookup via Jentic

An AI assistant answering 'how high is Ben Nevis?' uses Jentic to discover GPXZ, load `/elevation/point`, and execute with the user-supplied coordinates. The x-api-key sits in your Jentic One instance so the agent never handles the raw secret, and the agent reasons over the elevation value to compose a natural-language answer.

Example prompt: Use the Jentic SDK to search 'get elevation for a coordinate', load GET `/elevation/point`, and execute with lat=56.7969 lng=-5.0036 to return Ben Nevis's elevation.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/elevation/point` | Get elevation for a single point |
| POST | `/elevation/points` | Batch elevation lookup for many points |
| POST | `/elevation/sample` | Sample elevation along a path |
| GET | `/elevation/hires-raster` | Export a 2D elevation raster for a bounding box |
| GET | `/elevation/gmaps-compat/{outputFormat}` | Google Maps Elevation API drop-in compatibility |
| GET | `/elevation/otd-compat` | Open Topo Data API drop-in compatibility |
| GET | `/elevation/sources` | List elevation source datasets and coverage |

## Key resources

- **Point Elevation** — Single-coordinate and batch elevation lookups
- **Path Sampling** — Evenly-spaced elevation samples along a polyline
- **Raster Export** — 2D high-resolution elevation raster for a bounding box
- **Compatibility Endpoints** — Drop-in equivalents for Google Maps Elevation and Open Topo Data APIs
- **Source Metadata** — Available source datasets and their coverage

## Why Jentic

- **Setup:** Wiring the GPXZ Elevation API by hand means setting the x-api-key header, choosing between its US and EU hosts, and routing each request to the right endpoint for a point, a batch, a sampled path, or a raster yourself. Through Jentic you install once, import GPXZ from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** GPXZ takes the coordinates or path in query parameters or the request body rather than a resource id in the path, so limit the agent to the operations it needs, such as elevation/point or elevation/sample. You choose the operations it may call, so the agent cannot reach anything you have not included.
- **Credential handling:** Your GPXZ x-api-key is stored once, encrypted, by your own Jentic One instance and injected as the header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get elevation for a coordinate' or 'sample elevation along a path', and Jentic returns the matching GPXZ operation with its parameter schema so the agent picks point versus sample versus raster automatically.

## Related APIs

- **OpenCage Geocoding API** — Forward and reverse geocoding that pairs with GPXZ point elevation
- **Positionstack** — Forward and reverse geocoding API for resolving addresses before elevation lookups
- **TomTom Routing API** — Routing engine producing polylines that GPXZ can profile for elevation
- **HERE Maps APIs** — Commercial mapping platform with broader geospatial surface - choose for one-vendor coverage

## FAQ

### Why is there no official OpenAPI spec for GPXZ Elevation API?

GPXZ does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call GPXZ Elevation API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the GPXZ Elevation API use?

GPXZ supports two equivalent schemes - an x-api-key header (apiKeyHeader) and an api-key query parameter (apiKeyQuery). Prefer the header for production. Through Jentic, the key is stored in your Jentic One instance and injected at execution time so the agent never sees it.

### Can I migrate from Google Maps Elevation without rewriting my code?

Yes. `/elevation/gmaps-compat/{outputFormat}` mirrors Google Maps Elevation API's request and response shapes. Swap the host to api.gpxz.io and add the x-api-key header - request parameters and JSON output are unchanged. Note that source coverage and resolution come from GPXZ's datasets, not Google's.

### What are the rate limits for the GPXZ Elevation API?

The OpenAPI spec does not declare specific limits. Limits are tied to your plan tier in the GPXZ dashboard, with free, hobby, and commercial tiers offering different per-second and per-month quotas. Use POST `/elevation/points` to batch lookups and reduce per-request overhead.

### How do I sample elevation along a route through Jentic?

Search Jentic for 'sample elevation along a path', load POST `/elevation/sample`, and execute with the polyline geometry and a samples count. The Jentic SDK returns the elevation series array directly, ready to plot.

### Does GPXZ cover the entire world?

Yes - GPXZ provides worldwide coverage by stitching multiple elevation source datasets. Resolution varies by region: high-resolution lidar and survey data is available for some countries while remote areas fall back to global SRTM-style sources. Call `/elevation/sources` to inspect what's available for a given bounding box.

### Can I limit what my agent is allowed to do with the GPXZ Elevation API?

Yes. Because Jentic One is self-hosted, you decide which GPXZ operations your agent may call, so you can grant only `/elevation/point` or `/elevation/sample` and leave batch, raster, and compatibility endpoints out of reach. GPXZ takes coordinates or a path in query parameters or the request body rather than a resource id in the path, so the operations you include define the full boundary of what the agent can touch. Your rules govern both the allowed operations and the x-api-key, and the agent cannot reach anything you have not added.