GraphQL conventions
The Data API is one GraphQL endpoint that only reads. The rules on this page hold for all fourteen queries.
Every sample on this page reuses this setup. It mints a session token with your secret key, so run it on your server.
Every query takes a single argument, input. Pass it as a variable, and spell enum values in capitals with underscores: HIKING_AND_TRAIL, CITY.
Send every request as a POST with a JSON body. Any other method answers 405 Method Not Allowed.
A GraphQL query lists the fields it wants back, and the answer holds those fields alone. Ask for a route's geometry only when you draw it: it holds one position per vertex.
In TypeScript, pass select to any mountaya.data method. Without it, the client asks for every field. The result type narrows to what you selected, so reading a field you did not select fails to compile.
One request can carry up to four queries. Give each one an alias to tell their answers apart.
The TypeScript client sends one query per call: run several calls with Promise.all instead. A fifth query in one request is refused, so split larger batches.
A query that fails still answers 200 OK. The body then carries an errors array, so check it on every response. Each error names a code and, for invalid input, the path of the field to fix.
The TypeScript client throws a MountayaDataError holding the same entries. A request refused before any query runs, such as one with an expired token, gets an HTTP error status instead. Errors lists them.
A query document can be long, so you can send its SHA-256 hash in its place. The first time, the API may not know the hash: send the request again with the document. The TypeScript client does this for you.
The Data API explorer runs queries from your browser. Open its Headers tab and paste your publishable key and a fresh session token as X-API-Key and X-Session-Token.
To generate types in your own tooling, download the GraphQL schema.