PUT
/
v1
/
osm
/
extract
curl -X PUT \
     --url "https://osm.buntinglabs.com/v1/osm/extract?api_key=YOUR_API_KEY&tags=name%3DNew%20Mexico%20State%20Capitol&simplify=point" \
     --data "POLYGON((-109.0448 36.9971,-109.0489 31.3337,-108.2140 31.3349,-108.2071 31.7795,-106.5317 31.7830,-106.6223 32.0034,-103.0696 31.9999,-103.0023 36.9982,-109.0475 36.9982,-109.0448 36.9971))"

{
  "features": [{
    "type": "Feature",
    "properties": {
      "addr:city": "Santa Fe",
      "addr:housenumber": "490",
      "addr:postcode": "87501",
      "addr:street": "Old Santa Fe Trail",
      "building": "yes",
      "name": "New Mexico State Capitol",
      "wikipedia": "en:New Mexico State Capitol"
    },
    "geometry": {
      "type": "Point",
      "coordinates": [ -105.9396344, 35.6823018 ]
    }
  }],
  "type": "FeatureCollection"
}

This endpoint pulls OpenStreetMap features inside a geometry and streams them as GeoJSON. For example, this was downloaded as building=* inside the WKT POLYGON((-112.17562 33.57116, ...)):

openstreetmap features in polygon

You can filter for any tag in the database, either as key=value or key=*, and can chain tags if you need 2+ tags.

Before running the extract, you can also calculate the size and feature count of an extract first.

This endpoint requires the growth plan because it uses thousands of expensive geometric operations.

​
Body

This request takes a single WKT geometry as the PUT request body (ASCII/UTF8 encoded).

Coordinates are in WGS84 (EPSG:4326) and ordered longitude, latitude. All counted geometries will intersect with the uploaded geometry.

​
Request Parameters

tags
string
required

This is a list of tags in the form key=value to filter features for. All features extracted will satisfy each of the passed tags given by this parameter.

This tag list can be created by forming an array of key=value items and joining them into one string with the & character.

Because both = and & are reserved characters in URIs, this list must be URL encoded.

An example list of tags could be leisure=park and name=Westglen Park. This matches parks that have the name Westglen Park. To set this parameter, we’ll URL encode leisure=park&name=Westglen Park.

Documentation on tags can be found on the TagInfo resource website.

api_key
string
required

Your account’s API key. You can create an API key by registering for an account and copy and paste it from your account dashboard.

simplify
string

This optional parameter, when passed, simplifies the output geometries. The only valid value is simplify=point, which turns every output geometry into a single point (its centroid).

This is convenient for approximating LineStrings and MultiPolygons as their central point.

Note the centroid may fall outside the original polygon, e.g. a donut’s centroid is outside the ring.

​
Response

When the OSM feature extract is successfully created, a 200 OK response will be issued, with Content-Type: application/json. The body will be a valid GeoJSON FeatureCollection.

In the event of an error, an error response will be issued, usually with a 5xx error code. The error will be JSON-formatted, with an error field describing the cause.

error
string

The error message if the extract request parameters were incorrectly formatted.

This response field will not be present if the extract succeeds.

​
Data License

This API serves OpenStreetMap data, which is freely available and is licensed under the Open Data Commons Open Database License (ODbL).

Extract in RadiusCount Features