> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buntinglabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract within Geometry

> This endpoint downloads features matching tags inside an uploaded WKT geometry as GeoJSON.

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](https://mintlify.s3-us-west-1.amazonaws.com/buntinglabs/images/wkt_extract.png)

You can filter for any tag in the [database](https://taginfo.openstreetmap.org/), 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](/openstreetmap-api/count-within-geometry) first.

<Note>This endpoint requires the [growth plan](https://buntinglabs.com/pricing) because it uses thousands of expensive geometric operations.</Note>

### 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

<ParamField query="tags" type="string" placeholder="leisure=park" 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](https://taginfo.openstreetmap.org) resource website.
</ParamField>

<ParamField query="api_key" type="string" placeholder="demo" required>
  Your account's API key. You can create an API key by
  [registering for an account](https://buntinglabs.com/account/register)
  and copy and paste it from your [account dashboard](https://buntinglabs.com/dashboard).
</ParamField>

<ParamField query="simplify" type="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.
</ParamField>

### 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](https://geojson.org/).

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.

<ResponseField name="error" type="string">
  The error message if the extract request parameters were incorrectly formatted.

  This response field will not be present if the extract succeeds.
</ResponseField>

### Data License

This API serves [OpenStreetMap](https://www.openstreetmap.org/) data, which is
freely available and is licensed under the
[Open Data Commons Open Database License (ODbL)](https://www.openstreetmap.org/copyright).

<RequestExample>
  ```bash cURL
  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))"
  ```

  ```javascript JavaScript
  const params = new URLSearchParams({
    api_key: "YOUR_API_KEY",
    tags: "name=New Mexico State Capitol"
  });

  const body = "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))";

  fetch(`https://osm.buntinglabs.com/v1/osm/extract?${params}`, { method: 'PUT', body })
    .then(response => response.json())
    .then(data => console.log(data));
  ```

  ```python Python
  import requests

  params = {
    "api_key": "YOUR_API_KEY",
    "tags": "name=New Mexico State Capitol"
  }
  geometry_wkt = "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))"

  response = requests.put("https://osm.buntinglabs.com/v1/osm/extract", params=params, data=geometry_wkt)
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "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"
  }
  ```
</ResponseExample>