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

> Download features within a radius around an address (or coordinates), matching given tags as GeoJSON.

This endpoint downloads OpenStreetMap features that are inside a circle, centered
at `address` extending `radius` meters out.

For example, these are the results for `building=*` within `radius=1000` meters of
San Francisco International Airport's address:

![openstreetmap features in radius](https://mintlify.s3-us-west-1.amazonaws.com/buntinglabs/images/buildings_circle.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.

### 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="center" type="string" placeholder="-108.984,32.026">
  The center of the circle as a coordinate. Features falling inside the circle will be downloaded.

  The center coordinate is formatted as `longitude,latitude`. One of `center` or `address` is required.
</ParamField>

<ParamField query="address" type="string" placeholder="335 McAllister St, San Francisco, CA 94102">
  The center of the circle as an address. Features falling inside the circle will be downloaded.

  If the address is ambiguous, the best result will be chosen, which may or may not be the target address.
  To get the best results, provide the full address, including: building number, street name, city name,
  state, zip code, and country.

  An example address is `335 McAllister St, San Francisco, CA 94102`. One of `center` or `address` is required.

  <Note>Providing an `address` requires the [growth plan](https://buntinglabs.com/pricing) because it consumes third-party geocoding resources.</Note>
</ParamField>

<ParamField query="radius" type="number" placeholder="1000" required>
  The radius around the center, in meters. Maximum radius is 16,093 meters (10 miles).
</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 --get 'https://osm.buntinglabs.com/v1/osm/extract-in-radius' \
       --data "address=1+Dr+Carlton+B+Goodlett+Pl+San Francisco+CA+94102" \
       --data "radius=1000" \
       --data "api_key=YOUR_API_KEY" \
       --data "tags=amenity=restaurant"
  ```
</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>