Find OSM features inside an area via the Overpass API, for surveys of everything in a region (openstreetmap_query_nearby covers proximity to a point). Scope with the four corner fields south, west, north, east, or with within and a single OSM boundary ref such as a city relation or a park way, which searches the boundary polygon itself instead of an overcovering box; never both. Filter with amenity, or with tag_key plus an optional tag_value, ANDing up to five more filters; every feature returns with its full OSM tag set (no extratags flag here) or the keys tag_keys lists.
View input schema
{
"type": "object",
"properties": {
"within": {
"description": "OSM boundary to search inside, as one ref: R plus a relation id (\"R237385\", Seattle) or W plus a closed-way id (\"W13800188\", a park), case-insensitive, or the object path (\"relation/237385\") or its openstreetmap.org URL. Take it from osm_type plus osm_id on openstreetmap_search_places, openstreetmap_reverse_geocode, or openstreetmap_lookup_objects. The alternative to the four corner fields, never both. A node ref is rejected: a node is never an area. A ref that maps to no Overpass area returns an empty page whose notice names the cause.",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\s*(?:([WRwr])(\\d+)|(?:(?:https?:\\/\\/)?(?:(?:www\\.)?openstreetmap|osm)\\.org\\/|\\/)?([wW][aA][yY]|[rR][eE][lL][aA][tT][iI][oO][nN])\\/(\\d+)(?:[/?#]\\S*)?)\\s*$",
"description": "One way or relation ref, path, or openstreetmap.org URL."
}
]
},
"south": {
"description": "Southern boundary latitude (minimum latitude). One of four corner fields: supply all four, or use within instead.",
"type": "number",
"minimum": -90,
"maximum": 90
},
"west": {
"description": "Western boundary longitude (minimum longitude). A west greater than east is valid, not an error: Overpass reads it as an antimeridian-crossing box and returns the union of west..180 and -180..east.",
"type": "number",
"minimum": -180,
"maximum": 180
},
"north": {
"description": "Northern boundary latitude (maximum latitude).",
"type": "number",
"minimum": -90,
"maximum": 90
},
"east": {
"description": "Eastern boundary longitude (maximum longitude). A value below west describes an antimeridian crossing rather than an inverted box.",
"type": "number",
"minimum": -180,
"maximum": 180
},
"amenity": {
"description": "OSM amenity tag value shortcut (e.g. \"cafe\", \"bench\", \"hospital\"). Exactly one primary mode is required: this or tag_key, never both. Many categories live under other keys — tourism (museums, hotels, viewpoints), leisure (parks, pitches, playgrounds), shop (supermarkets), historic (castles, memorials), natural (beaches, peaks); query those with tag_key and tag_value.",
"type": "string"
},
"tag_key": {
"description": "Primary OSM tag key (e.g. \"leisure\", \"shop\", \"natural\"); omit tag_value to match any feature carrying the key, or supply it for exact equality. The alternative to amenity, never both. Additional filters are ANDed with this tag.",
"type": "string"
},
"tag_value": {
"description": "Literal value paired with tag_key for exact equality (e.g., \"park\", \"supermarket\"); omit for key existence. Exact equality misses semicolon-list values (cuisine=pizza;italian); tag_value_match \"list_item\" catches them. Explicit empty or whitespace-only values are invalid. Keys and values are trimmed; blank unused fields are ignored in amenity mode.",
"type": "string"
},
"tag_value_match": {
"description": "How tag_value matches: \"exact\" (default) compares the whole value; \"list_item\" matches one item of a semicolon list, so \"pizza\" finds cuisine=pizza;italian. Needs tag_value; not available with amenity.",
"type": "string",
"enum": [
"exact",
"list_item"
]
},
"filters": {
"description": "Up to five additional filters, ANDed with the required primary amenity or tag_key filter in input order. Omitted or [] adds no conditions. Exact values miss semicolon-list values; set match \"list_item\" on the entry. Keys must be unique after trimming; keys and values must not contain Overpass QL metacharacters (\" \\ [ ] ; ( )).",
"maxItems": 5,
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Literal OSM tag key. Trimmed and nonblank; must be unique across the primary tag and all filters."
},
"value": {
"description": "Literal value to match. Omit for key existence; an explicitly blank value is invalid. Trimmed before matching.",
"type": "string"
},
"match": {
"description": "How value matches: \"exact\" (default) or \"list_item\", one item of a semicolon list. Needs value.",
"type": "string",
"enum": [
"exact",
"list_item"
]
}
},
"required": [
"key"
],
"additionalProperties": false,
"description": "One additional equality, list-item, or key-existence filter."
}
},
"element_types": {
"default": [
"node",
"way",
"relation"
],
"description": "OSM element types to search, at least one. Nodes cover most standalone POIs, ways most buildings and areas, relations large parks, lakes, campuses, and boundaries. Omit the field to search all three; pass [\"node\", \"way\"] to leave relations out. An empty array is rejected because it can only match nothing.",
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"node",
"way",
"relation"
]
}
},
"tag_keys": {
"description": "Return only these tag keys in each feature's tags, matched exactly; list name:en to get it, no wildcards. Shrinks responses on heavily tagged features such as boundary relations. Matching, ranking, and paging still read every tag. Omitted or [] returns the full tag set.",
"maxItems": 50,
"type": "array",
"items": {
"type": "string"
}
},
"sort_by": {
"description": "Rank the whole match set by a tag's numeric value before offset and limit apply. A value ranks when it is a plain decimal such as 4392 or -12.5; one with a unit, comma, range, or list (8280ft, 2,5, 100-200, 849;871) is not converted. Those and features lacking the tag follow the ranked ones in default order, counted in unrankedCount. A blank key means no sort.",
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Tag whose numeric value ranks the features, e.g. \"ele\", \"population\"."
},
"order": {
"default": "desc",
"description": "\"desc\" puts the largest value first.",
"type": "string",
"enum": [
"desc",
"asc"
]
}
},
"required": [
"key"
],
"additionalProperties": false
},
"limit": {
"default": 20,
"description": "Maximum results to return, up to 500 per call; a larger value is served as 500 and limitNotice says so. Applied after the Overpass query — if the area has more features, they are truncated.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"offset": {
"default": 0,
"description": "Number of matching features to skip before applying limit, for paging through a large result set; sort_by ranks the whole set before the page is cut. The full match set is fetched and cached ~10 minutes keyed by the query, so re-paging at a new offset is deterministic and costs no extra upstream request. Pass the nextOffset value from a prior truncated response.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"timeout_seconds": {
"default": 25,
"description": "Overpass query timeout in seconds. Increase for large bounding boxes or dense areas.",
"type": "integer",
"minimum": 5,
"maximum": 60
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"required": [
"south",
"west",
"north",
"east",
"amenity"
]
},
{
"type": "object",
"required": [
"south",
"west",
"north",
"east",
"tag_key"
]
},
{
"type": "object",
"required": [
"within",
"amenity"
]
},
{
"type": "object",
"required": [
"within",
"tag_key"
]
}
]
}