Get started
Data API

GraphQL conventions

GraphQL conventions

The Data API is one GraphQL endpoint that only reads. The rules on this page hold for all fourteen queries.

POST https://data.mountaya.com/graphql

Set up

Every sample on this page reuses this setup. It mints a session token with your secret key, so run it on your server.

export MOUNTAYA_PUBLISHABLE_KEY="pk_your_publishable_key"
export MOUNTAYA_SESSION_TOKEN=$(curl -s -X POST https://api.mountaya.com/v1/sessions \
  -H "X-API-Key: $MOUNTAYA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"publishable_key\": \"$MOUNTAYA_PUBLISHABLE_KEY\"}" | jq -r .data.token)

One input per query

Every query takes a single argument, input. Pass it as a variable, and spell enum values in capitals with underscores: HIKING_AND_TRAIL, CITY.

curl https://data.mountaya.com/graphql \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query ReverseGeocode($input: ReverseGeocodeInput!) { reverseGeocode(input: $input) { places { name layer } } }",
    "variables": {
      "input": { "point": [6.8712, 45.9231], "limit": 1, "layers": ["CITY"] }
    }
  }'
Response
{
  "data": {
    "reverseGeocode": {
      "places": [
        {
          "name": "Chamonix-Mont-Blanc",
          "layer": "CITY"
        }
      ]
    }
  }
}

Send every request as a POST with a JSON body. Any other method answers 405 Method Not Allowed.

Select the fields you need

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.

Batch up to four queries

One request can carry up to four queries. Give each one an alias to tell their answers apart.

curl https://data.mountaya.com/graphql \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query Trailheads { chamonix: reverseGeocode(input: { point: [6.8712, 45.9231], limit: 1, layers: [CITY] }) { places { name } } argentiere: reverseGeocode(input: { point: [6.9271, 45.9822], limit: 1, layers: [DISTRICT] }) { places { name } } }"
  }'
Response
{
  "data": {
    "chamonix": {
      "places": [{ "name": "Chamonix-Mont-Blanc" }]
    },
    "argentiere": {
      "places": [{ "name": "Argentière" }]
    }
  }
}

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.

Read errors in the body

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.

curl https://data.mountaya.com/graphql \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query Directions($input: DirectionsInput!) { directions(input: $input) { routes { distance } } }",
    "variables": {
      "input": { "activity": "HIKING_AND_TRAIL", "waypoints": [[6.8712, 45.9231]] }
    }
  }'
Response
{
  "errors": [
    {
      "message": "Must have at least 2 waypoints",
      "path": ["directions"],
      "locations": [{ "line": 1, "column": 46 }],
      "extensions": {
        "code": "VALIDATION_FAILED",
        "path": ["input", "waypoints"]
      }
    }
  ],
  "data": null
}

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.

Persisted queries

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.

{
  "extensions": { "persistedQuery": { "version": 1, "sha256Hash": "11a4644a20386ce7a28aa711862e60231b43fef41ab0444f7a25b18c9352979b" } },
  "variables": { "input": { "locations": [[6.8712, 45.9231]] } }
}
Response when the hash is unknown
{"errors":[{"message":"PersistedQueryNotFound","extensions":{"code":"PERSISTED_QUERY_NOT_FOUND"}}],"data":null}

Explore the schema

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.

Next steps

Last updated