Geocoding
The geocode and reverseGeocode queries 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.
/graphqlForward geocode a free-text query into a list of named places. Returns cities, regions, natural features, and addresses ranked by relevance.
Arguments
inputGeocodeInput!
The text to geocode, and the filters that narrow where and what it may match.
queryString!
User-typed search text. Must be between 1 and 200 characters after trimming (VALIDATION_FAILED at ["input", "query"] otherwise). Example: "Chamonix" or "Mont Blanc".
languageLanguage
One of: EN, FR, ES, IT, DE, ZH, JA
Language of the returned names. Only EN and FR are localized; any other language reads English. Defaults to English when omitted.
See Language.
limitInt
Maximum number of places to return. Must be between 1 and 50; defaults to 10. Omitting it returns at most the default rather than everything.
focus[Float!]
[longitude, latitude] center used to bias ranking toward nearby results: exactly two numbers, in range. [0, 0] and an empty list both mean no focus. Example: [6.8712, 45.9231] to bias results around Chamonix.
bbox[Float!]
[minLongitude, minLatitude, maxLongitude, maxLatitude] bounding box to restrict the search area: exactly four values, each minimum strictly below its maximum, and each axis spanning at most 90 degrees. [0, 0, 0, 0] and an empty list both mean no box.
layers[GeocodeLayer!]
One of: COUNTRY, REGION, COUNTY, CITY, DISTRICT, POSTCODE, STREET, HOUSE, POI, NATURAL
Layers to restrict results to, at most 10. When omitted, all layers are eligible. Like categories, it runs on the places the geocoder returned for limit, so it can leave fewer than limit, or none, even where more places of those layers exist: POSTCODE does not narrow the geocoder's own search, and POI and NATURAL narrow it only to the one set both belong to. Raise limit when a narrow filter leaves too few.
See GeocodeLayer.
categoriesPlaceCategoriesInput
Boolean-per-category filter applied to the geocoded place output. When omitted, every category is allowed. It runs on the places the geocoder returned for limit, so it can leave fewer than limit.
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.
Returns
geocodeGeocodeResult!
Result of a forward geocoding query.
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.
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 Geocode($input: GeocodeInput!) { geocode(input: $input) { count places { label name point } } }",
"variables": {
"input": {
"focus": [6.8712, 45.9231],
"limit": 3,
"query": "Chamonix"
}
}
}'/graphqlReverse geocode a [longitude, latitude] point into a list of named places. Returns the place closest to the point, optionally constrained by layer or radius. A failure of the geocoder, its refusal of a lookup included, is INTERNAL_ERROR, never the caller's to fix.
Arguments
inputReverseGeocodeInput!
The position to name, and the filters that decide which kinds of place may answer.
point[Float!]!
[longitude, latitude] anchor point to reverse-geocode: exactly two numbers, in range (VALIDATION_FAILED at ["input", "point"] otherwise). Example: [6.8712, 45.9231] for Chamonix.
languageLanguage
One of: EN, FR, ES, IT, DE, ZH, JA
Language of the returned names. Only EN and FR are localized; any other language reads English. Defaults to English when omitted.
See Language.
radiusMetersInt
Maximum search radius in meters around the anchor point. Must be between 1 and 5000.
limitInt
Maximum number of places to return. Must be between 1 and 50; defaults to 1, since a reverse lookup asks which single place a coordinate falls in.
layers[GeocodeLayer!]
One of: COUNTRY, REGION, COUNTY, CITY, DISTRICT, POSTCODE, STREET, HOUSE, POI, NATURAL
Layers to restrict results to, at most 10. When omitted, all layers are eligible. Like categories, it runs on the places the geocoder returned for limit, so it can leave fewer than limit, or none, even where more places of those layers exist: POSTCODE does not narrow the geocoder's own search, and POI and NATURAL narrow it only to the one set both belong to. Raise limit when a narrow filter leaves too few.
See GeocodeLayer.
categoriesPlaceCategoriesInput
Boolean-per-category filter applied to the geocoded place output. When omitted, every category is allowed. It runs on the places the geocoder returned for limit, so it can leave fewer than limit.
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.
Returns
reverseGeocodeReverseGeocodeResult!
Result of a reverse geocoding query.
point[Float!]!
Echo of the anchor [longitude, latitude] point used for the lookup.
places[Place!]!
List of named places, in the order the geocoder returns them for the point.
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.
countInt!
Number of places returned: the length of places, at most limit.
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 ReverseGeocode($input: ReverseGeocodeInput!) { reverseGeocode(input: $input) { count places { layer name } } }",
"variables": {"input": {"limit": 2, "point": [6.9271, 45.9822]}}
}'