Search
The search query of the Data API. Every request is a POST to https://data.mountaya.com/graphql with a publishable key and a session token: see Authentication.
/graphqlUnified full-text search across geocoded places, POIs, ways, and Mountaya entities (itineraries, collections, zones).
Arguments
inputSearchInput!
The query text, the targets to search, and the filters applied to each of them.
queryString!
User-typed search text, at most 200 characters after trimming. Every target except pois also needs at least one character once trimmed; the pois target accepts an empty query and lists POIs of the requested categories.
languageLanguage
One of: EN, FR, ES, IT, DE, ZH, JA
Language of the names the places, pois and ways targets return. Only EN and FR are localized; any other language reads English. The itineraries, collections and zones targets ignore it and return names as they were written. Defaults to English when omitted.
See Language.
limitInt
Per-target maximum number of results. Must be between 1 and 50; defaults to 8. The cap applies to each enabled target independently, so the whole result can hold up to limit × the number of enabled targets, which is why the default is small. Omitting it caps each target at the default rather than returning everything. A value outside the range is refused by every enabled target, each in its own errors entry.
focus[Float!]
[longitude, latitude] center used to bias ranking toward nearby results for the places, pois, and ways targets: exactly two numbers, in range, or the request fails with VALIDATION_FAILED at ["input", "focus"]. [0, 0] and an empty list both mean no focus.
bbox[Float!]
[minLongitude, minLatitude, maxLongitude, maxLatitude] bounding box used to restrict the search area for the places, pois, and ways targets. [0, 0, 0, 0] and an empty list both mean no box; any count other than four fails the request with VALIDATION_FAILED at ["input", "bbox"]. Each of those three targets also requires values in range, each minimum strictly below its maximum and each axis spanning at most 90 degrees, and reports a box that breaks those rules in errors.
activityActivitySlug
One of: HIKING_AND_TRAIL, PROFESSIONAL_TRAIL, RUNNING, ROAD_CYCLING, GRAVEL_BIKE, MOUNTAIN_BIKE, BACKCOUNTRY_SKIING, SKI_TOURING, CROSS_COUNTRY_SKIING, SNOWSHOE_WALKING
Activity slug used to filter the ways target: a way the activity cannot use is left out, and the order of the rest is unchanged. Ignored unless targets.ways = true.
See ActivitySlug.
targetsSearchTargetsInput!
Per-target enable flags. Every field defaults to false; at least one must be true for the query to execute work. When no flag is true, an empty result is returned and no usage is recorded, so the request counts toward neither the monthly allowance nor an invoice, though it still counts toward the per-minute rate limit.
placesBoolean
Enable the geocoded places target.
poisBoolean
Enable the points-of-interest target.
waysBoolean
Enable the named-ways target.
itinerariesBoolean
Enable the itineraries target.
collectionsBoolean
Enable the collections target.
zonesBoolean
Enable the zones target.
pois[POICategory!]
One of: HUT, PEAK, PASS, VIEWPOINT, PARKING, WATER_SOURCE, CAFE, RESTAURANT, SUPERMARKET, PHARMACY, TOILETS, CAMPSITE, SHELTER, CABLE_CAR, BUS_STATION, TRAIN_STATION, AIRPORT, ACCOMMODATION, CARAVAN_SITE, HOSPITAL
Optional POI categories filter applied to the pois target. When omitted, every category is searched. Ignored unless targets.pois = true.
See POICategory.
categoriesPlaceCategoriesInput
Optional boolean-per-category filter applied to the places target. When omitted, every category is allowed. Ignored unless targets.places = true.
populatedPlaceBoolean
Include populated places like cities, towns, villages, hamlets, and suburbs. Defaults to true.
administrativeAreaBoolean
Include administrative boundaries like regions, counties, departments, districts, and localities. Defaults to true.
countryBoolean
Include country-level results such as France or Switzerland. Defaults to true.
naturalFeatureBoolean
Include natural features like mountain peaks, lakes, glaciers, rivers, and forests. Defaults to true.
transitStationBoolean
Include transit stations like train stations, bus terminals, airports, and cable car stations. Defaults to true.
amenityBoolean
Include amenities like cafes, restaurants, shops, tourist attractions, and leisure venues. Defaults to true.
addressBoolean
Include addresses like streets, house numbers, and postcodes. Defaults to true.
otherBoolean
Include the catch-all bucket for places that do not fit any of the other categories. Defaults to true.
verifyWaysBoolean
Opt-in to routing-graph verification for the ways target. When true, each candidate way is cross-checked against the same geometry analysis analyzeGeometry performs, and an activity for which that analysis finds a stretch it cannot classify is dropped from the way's activityCompatible. An activity that could not be checked is kept: a way with no polyline, an analysis that failed, or an activity with no surface analysis, such as the winter ones. Materially increases latency; ignored unless targets.ways = true.
Returns
searchSearchResult!
Result of the unified search query. Each target's section is non-null only when that target was enabled and its branch succeeded; failed branches leave their section null and surface an entry in errors[].
queryString!
Echo of the input query.
languageLanguage!
One of: EN, FR, ES, IT, DE, ZH, JA
Language the place, POI and way names were returned in: the requested language when it is EN or FR, and EN otherwise, including when none was given.
See Language.
targetsSearchTargets!
Echo of the per-target enable flags carried by the input.
placesBoolean!
Whether the places target was enabled.
poisBoolean!
Whether the pois target was enabled.
waysBoolean!
Whether the ways target was enabled.
itinerariesBoolean!
Whether the itineraries target was enabled.
collectionsBoolean!
Whether the collections target was enabled.
zonesBoolean!
Whether the zones target was enabled.
placesGeocodeResult
Geocoded places section. Null when the places target was disabled or its branch errored.
countInt!
Number of places returned: the length of places, at most limit.
places[Place!]!
List of named places ordered by relevance.
osmOSMRef!
Reference to the underlying OpenStreetMap feature.
idID!
OpenStreetMap identifier of the feature.
typeOSMType!
One of: NODE, WAY, RELATION
Primitive kind of the feature: node, way, or relation.
See OSMType.
keyString!
Matched OSM tag key. Example: "place" or "highway".
valueString!
Matched OSM tag value. Example: "city" or "residential".
nameString!
Localized display name.
labelString!
Single-line label built from the house number and street, the city (or the district when there is no city), the region and the country, in that order, leaving out any the place does not carry.
layerGeocodeLayer!
One of: COUNTRY, REGION, COUNTY, CITY, DISTRICT, POSTCODE, STREET, HOUSE, POI, NATURAL
Canonical geocoding layer for this place.
See GeocodeLayer.
categoryPlaceCategory!
One of: POPULATED_PLACE, ADMINISTRATIVE_AREA, COUNTRY, NATURAL_FEATURE, TRANSIT_STATION, AMENITY, ADDRESS, OTHER
Canonical category for this place. Drives category-specific UI and is the dimension along which PlaceCategoriesInput filters geocoding output.
See PlaceCategory.
point[Float!]!
Centroid as [longitude, latitude].
bounds[Float!]
Optional extent as [minLongitude, minLatitude, maxLongitude, maxLatitude]. Null when no bounds are known.
countryString
ISO 3166-1 alpha-2 country code. Example: "FR". Null when the upstream geocoder did not resolve administrative context for this result.
countryNameString
Localized country display name. Null when the upstream geocoder did not resolve administrative context for this result.
regionString
Administrative region or state. Null when the upstream geocoder did not resolve administrative context for this result.
countyString
Administrative county or department. Null when the upstream geocoder did not resolve administrative context for this result.
cityString
City name. Null when the upstream geocoder did not resolve administrative context for this result.
postcodeString
Postal code. Null when the result is coarser than a postcode, or the upstream geocoder did not resolve one.
streetString
Street name. Null unless the result resolved to a street or an address on one.
houseNumberString
Building number on the street. Null unless the result resolved to a specific address.
poisPoisResult
Points-of-interest section. Null when the pois target was disabled or its branch errored.
countInt!
Number of POIs returned: the length of pois, at most limit.
pois[POI!]!
List of POIs ordered by relevance. A buffered area does not reorder them by distance: read each one's distanceMeters.
osmOSMRef!
Reference to the underlying OpenStreetMap feature.
idID!
OpenStreetMap identifier of the feature.
typeOSMType!
One of: NODE, WAY, RELATION
Primitive kind of the feature: node, way, or relation.
See OSMType.
keyString!
Matched OSM tag key. Example: "place" or "highway".
valueString!
Matched OSM tag value. Example: "city" or "residential".
nameString!
Localized display name.
categoryPOICategory!
One of: HUT, PEAK, PASS, VIEWPOINT, PARKING, WATER_SOURCE, CAFE, RESTAURANT, SUPERMARKET, PHARMACY, TOILETS, CAMPSITE, SHELTER, CABLE_CAR, BUS_STATION, TRAIN_STATION, AIRPORT, ACCOMMODATION, CARAVAN_SITE, HOSPITAL
Canonical POI category mapped from the underlying OSM tags.
See POICategory.
point[Float!]!
Centroid as [longitude, latitude].
elevationFloat
Elevation in meters above sea level, read from the OSM "ele" tag. Often null: present only where the place data carries that tag.
tags[OSMTag!]!
Selected OSM tags useful for UI rendering, present only where the place data carries them. Not exhaustive, and often empty.
keyString!
OSM tag key. Example: "ele" or "name:fr".
valueString!
OSM tag value. Example: "4810" or "Mont Blanc".
distanceMetersFloat
Distance in meters from the buffered geometry itself, measured to its nearest edge rather than its nearest vertex, and 0 for a POI inside a Polygon (outside its holes). Only set when the query used a buffered area.
countryString
ISO 3166-1 alpha-2 country code, e.g. "FR" or "BE". Null when the upstream geocoder did not resolve admin context.
countryNameString
Localized display name of the POI's country. Null when not available.
regionString
Administrative region or state the POI belongs to (e.g. Haute-Savoie). Null when not available.
cityString
City the POI belongs to. Null when not available.
waysWaysResult
Named-ways section. Null when the ways target was disabled or its branch errored.
countInt!
Number of ways returned: the length of ways, at most limit.
ways[Way!]!
List of named ways ordered by relevance.
osmOSMRef!
Reference to the underlying OpenStreetMap feature.
idID!
OpenStreetMap identifier of the feature.
typeOSMType!
One of: NODE, WAY, RELATION
Primitive kind of the feature: node, way, or relation.
See OSMType.
keyString!
Matched OSM tag key. Example: "place" or "highway".
valueString!
Matched OSM tag value. Example: "city" or "residential".
nameString!
Localized display name.
highwayString!
OSM highway tag value (e.g. path, track, footway).
surfaceString
OSM surface tag value. Often null: present only where the way's data carries that tag.
sacScaleString
OSM sac_scale tag value. Often null: present only where the way's data carries that tag.
point[Float!]!
Representative coordinate as [longitude, latitude].
bounds[Float!]
Bounding box as [minLongitude, minLatitude, maxLongitude, maxLatitude]. Null when the upstream geocoder returned no extent.
coordinates[[Float!]!]
Polyline coordinates as a list of [longitude, latitude] pairs; null when the upstream geocoder did not provide a polyline.
activityCompatible[ActivitySlug!]!
One of: HIKING_AND_TRAIL, PROFESSIONAL_TRAIL, RUNNING, ROAD_CYCLING, GRAVEL_BIKE, MOUNTAIN_BIKE, BACKCOUNTRY_SKIING, SKI_TOURING, CROSS_COUNTRY_SKIING, SNOWSHOE_WALKING
Activities whose routing profile accepts this way.
See ActivitySlug.
countryString
ISO 3166-1 alpha-2 country code, e.g. "FR" or "BE". Null when the upstream geocoder did not resolve admin context.
countryNameString
Localized display name of the way's country. Null when not available.
regionString
Administrative region or state the way belongs to (e.g. Haute-Savoie). Null when not available.
cityString
City the way belongs to. Null when not available.
activityAppliedActivitySlug
One of: HIKING_AND_TRAIL, PROFESSIONAL_TRAIL, RUNNING, ROAD_CYCLING, GRAVEL_BIKE, MOUNTAIN_BIKE, BACKCOUNTRY_SKIING, SKI_TOURING, CROSS_COUNTRY_SKIING, SNOWSHOE_WALKING
Activity slug used to filter the ways, echoed back when one was supplied in the input. Null when no activity filter was applied.
See ActivitySlug.
itinerariesItinerariesResult
Itineraries section. Null when the itineraries target was disabled or its branch errored.
countInt!
Number of itineraries returned: the length of itineraries, at most limit.
itineraries[ItinerarySearchResult!]!
List of itinerary references ordered by relevance.
idID!
Itinerary identifier.
nameString!
Display name of the itinerary.
descriptionString
Free-text description of the itinerary. Null when it has none.
distanceFloat
Total distance across all of the itinerary's segments, in meters (the sum of each segment's current distance); null when no segment contributes a distance value (e.g. the itinerary has no segments).
ascentInt
Total elevation gain across all of the itinerary's segments, in meters (the sum of each segment's current ascent); null when no segment contributes an ascent value (e.g. the itinerary has no segments).
activitySlugActivitySlug
One of: HIKING_AND_TRAIL, PROFESSIONAL_TRAIL, RUNNING, ROAD_CYCLING, GRAVEL_BIKE, MOUNTAIN_BIKE, BACKCOUNTRY_SKIING, SKI_TOURING, CROSS_COUNTRY_SKIING, SNOWSHOE_WALKING
Itinerary activity slug; null when no activity is assigned.
See ActivitySlug.
start[Float!]
Representative start coordinate as [longitude, latitude]; null when not available.
bounds[Float!]
Itinerary bounding box as [minLongitude, minLatitude, maxLongitude, maxLatitude]; null when not available.
isPrivateBoolean!
Whether the itinerary is private. A private itinerary is served only to a key of the organization that owns it; no other organization's key reaches it, even with its id. A public one ('anyone with the link') is also served by id to any other organization's key, as last published, but is never listed in another organization's search results.
organizationIdID
Identifier of the organization that owns this itinerary. Null for a personal itinerary, made from an individual account and owned by no organization.
scoreFloat!
Relevance rank over the itinerary's name and description, always greater than 0, higher being a better match; a match in the name weighs twice one in the description. It orders the itineraries section of ONE response and nothing more. The value comes from whichever of two ranking passes produced the match: a full-text rank, which is unbounded above though in practice below 1, or, when the full-text pass matches nothing and the query is at least two characters long, a fuzzy similarity between 0.3 and 1. The two scales differ, so a score is not comparable across responses, across targets, or against a fixed threshold.
matchedFieldMatchedField!
One of: NAME, DESCRIPTION
Field that produced the match.
See MatchedField.
collectionsCollectionsResult
Collections section. Null when the collections target was disabled or its branch errored.
countInt!
Number of collections returned: the length of collections, at most limit.
collections[CollectionSearchResult!]!
List of collection references ordered by relevance.
idID!
Collection identifier.
nameString!
Display name of the collection.
descriptionString
Free-text description of the collection. Null when it has none.
countCollectionCount!
Aggregate counts for the collection.
itinerariesInt!
Total number of itineraries contained in the collection.
zonesInt!
Total number of zones contained in the collection.
bounds[Float!]
Bounding box of the collection's itineraries as [west, south, east, north], measured as the caller sees them: the same box as the bbox of the collection's tile specification, so one across the antimeridian has west greater than east. It covers itineraries only, never a zone. Under a session token naming nobody, the public itineraries as last published, of owners whose agreement includes Map Publishing; under one naming a member, the drafts of the itineraries that member reaches. Null when none is drawn for the caller.
isPrivateBoolean!
Whether the collection is private. A private collection is reached only with a key of the organization that owns it; no other organization's key reaches it, even with its id. A public one ('anyone with the link') is also readable by id with any other organization's key, but is never listed in another organization's search results.
organizationIdID
Identifier of the organization that owns this collection. Null for a personal collection, made from an individual account and owned by no organization.
scoreFloat!
Relevance rank over the collection's name and description, always greater than 0, higher being a better match; a match in the name weighs twice one in the description. It orders the collections section of ONE response and nothing more. The value comes from whichever of two ranking passes produced the match: a full-text rank, which is unbounded above though in practice below 1, or, when the full-text pass matches nothing and the query is at least two characters long, a fuzzy similarity between 0.3 and 1. The two scales differ, so a score is not comparable across responses, across targets, or against a fixed threshold.
matchedFieldMatchedField!
One of: NAME, DESCRIPTION
Field that produced the match.
See MatchedField.
zonesZonesResult
Zones section. Null when the zones target was disabled or its branch errored.
countInt!
Number of zones returned: the length of zones, at most limit.
zones[ZoneSearchResult!]!
List of zone references ordered by relevance.
idID!
Zone identifier.
nameString!
Display name of the zone.
descriptionString
Free-text description of the zone. Null when it has none.
levelZoneLevel!
One of: INFO, RESOLVED, WARNING, DANGER
How serious the zone is, which is what a renderer picks its styling from. It carries no access meaning.
See ZoneLevel.
modeZoneMode!
One of: POLYGON, CIRCLE, SENSOR, SECTOR, FREEHAND
How the zone's area was drawn or computed. A zone computed from a source is POLYGON.
See ZoneMode.
point[Float!]
Representative coordinate as [longitude, latitude]; null when not available.
bounds[Float!]
Zone bounding box as [minLongitude, minLatitude, maxLongitude, maxLatitude]; null when not available.
isPrivateBoolean!
Whether the zone is private. A private zone is served only to a key of the organization that owns it; no other organization's key reaches it, even with its id. A public one is also served by id to any other organization's key, as last published, but is never listed in another organization's search results.
organizationIdID
Identifier of the organization that owns this zone. Null for a personal zone, made from an individual account and owned by no organization.
scoreFloat!
Relevance rank over the zone's name and description, always greater than 0, higher being a better match; a match in the name weighs twice one in the description. It orders the zones section of ONE response and nothing more. The value comes from whichever of two ranking passes produced the match: a full-text rank, which is unbounded above though in practice below 1, or, when the full-text pass matches nothing and the query is at least two characters long, a fuzzy similarity between 0.3 and 1. The two scales differ, so a score is not comparable across responses, across targets, or against a fixed threshold.
matchedFieldMatchedField!
One of: NAME, DESCRIPTION
Field that produced the match.
See MatchedField.
errors[SearchTargetError!]!
Graceful-degradation entries: one per target whose branch failed, or answered only in part because of a failure on Mountaya's side. Empty when every enabled branch succeeded.
targetSearchTarget!
One of: PLACES, POIS, WAYS, ITINERARIES, COLLECTIONS, ZONES
Identifier of the target whose branch failed.
See SearchTarget.
codeErrorCode!
One of: BAD_REQUEST, VALIDATION_FAILED, UNAUTHORIZED, PAYMENT_REQUIRED, FORBIDDEN, NOT_FOUND, METHOD_NOT_ALLOWED, CONFLICT, PAYLOAD_TOO_LARGE, TOO_MANY_REQUESTS, INTERNAL_ERROR, NOT_IMPLEMENTED, BAD_GATEWAY, SERVICE_UNAVAILABLE, GATEWAY_TIMEOUT
Why this target's branch failed. The same extensions.code that querying this target on its own would have emitted on the spec errors[] array.
See ErrorCode.
messageString!
Message describing the failure, localized by the Accept-Language header.
Errors A field the API refuses is answered 200, its entry in errors beside the data that resolved. See Errors.
curl https://data.mountaya.com/graphql \
-H "X-API-Key: pk_your_publishable_key" \
-H "X-Session-Token: sess_your_session_token" \
-H "Content-Type: application/json" \
-d '{
"query": "query Search($input: SearchInput!) { search(input: $input) { itineraries { count } places { count } query } }",
"variables": {
"input": {
"focus": [6.8712, 45.9231],
"limit": 2,
"query": "Tour du Mont-Blanc",
"targets": {"itineraries": true, "places": true}
}
}
}'