Places

Several queries find places and features. geocode turns free text into named places, reverseGeocode turns a coordinate into the nearest places, pois lists points of interest in an area, and search runs one full-text query across places, POIs, ways, and your own itineraries, collections, and zones.

All coordinates are [longitude, latitude] in WGS 84.

geocode

Forward-geocode a free-text query into a ranked list of named places such as cities, regions, natural features, and addresses.

Input

geocode(input: GeocodeInput!)

The layers filter accepts these values:

Layers are ordered from the coarsest scope (COUNTRY) to the finest (HOUSE, NATURAL). Pass a subset to a geocode query to restrict the result granularity.

Example

query Geocode($input: GeocodeInput!) {
  geocode(input: $input) {
    count
    places {
      name
      label
      layer
      category
      point
      country
      region
      city
      score
    }
  }
}

Response

GeocodeResult carries count and a places list ordered by relevance. Each Place includes:

Place also exposes country, countryName, region, county, city, postcode, street, housenumber, and an osm reference to the source feature.

Run this query live: open it in the playground and try it against the schema.

reverseGeocode

Reverse-geocode a [longitude, latitude] point into the named places closest to it.

Input

reverseGeocode(input: ReverseGeocodeInput!)

Example

query ReverseGeocode($input: ReverseGeocodeInput!) {
  reverseGeocode(input: $input) {
    point
    places {
      name
      label
      layer
      category
    }
  }
}

ReverseGeocodeResult echoes the point and returns a places list of the same Place shape as geocode, ordered by proximity then relevance.

pois

List points of interest matching one or more categories, inside either a bounding box or a buffered geometry. When a buffered area is used, each POI is annotated with its distance to the geometry.

Input

pois(input: POIsInput!)

The categories filter accepts these values:

Example

query Pois($input: POIsInput!) {
  pois(input: $input) {
    count
    pois {
      name
      category
      point
      elevation
      distanceMeters
    }
  }
}

Response

POIsResult carries count and a pois list. Each POI includes name, category, point, optional elevation (meters above sea level), selected OSM tags, and, when a buffered area was used, distanceMeters from the geometry. Admin context (country, region, city) is included when resolved.

search

Run one full-text query across several targets at once. Each target is opt-in, runs concurrently, and degrades gracefully: a target that fails leaves its section null and reports an entry in errors, while the others still return. Owned-entity targets (itineraries, collections, zones) return only entities the calling credential may view.

Input

search(input: SearchInput!)

search also accepts a pois category list and a categories filter that apply to those targets, mirroring the pois and geocode inputs.

Example

query Search($input: SearchInput!) {
  search(input: $input) {
    query
    places {
      count
      places {
        name
        label
      }
    }
    itineraries {
      count
      itineraries {
        id
        name
        activitySlug
      }
    }
    errors {
      target
      code
      message
    }
  }
}

Response

SearchResult echoes the query and targets, then carries one section per enabled target (places, pois, ways, itineraries, collections, zones). A section is null when its target was disabled or its branch failed. The errors list holds one SearchTargetError (target, code, message) per failed branch, and is empty when every enabled branch succeeded.

Next steps