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

# Median Income

> Calculate the median income of the population inside a circle centered at a point with a given radius.

This API endpoint calculates the median income inside a circle from US Census data. You can provide either
a coordinate (latitude and longitude) or an address, plus a radius around the center.

This endpoint is useful for real estate applications, when one might want to contextualize a property according to
its surrounding neighborhood.

### Request Parameters

<ParamField query="center" type="string" placeholder="-108.984,32.026">
  The center of the circle as a coordinate. Residents inside this circle will be counted in calculating
  income statistics.

  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. Residents inside this circle will be counted in calculating
  income statistics.

  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.
</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="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>

### Response

When features are successfully counted, a 200 OK response will be
issued, with `Content-Type: application/json`. The body will have a property `median_income`
which will be a floating point number representing the median income of residents of the circle,
in US dollars.

<ResponseField name="median_income" type="number">
  The median income of the population of the circle, according to US Census data.
</ResponseField>

<ResponseField name="source" type="string">
  A descriptive source for the data, including the year the data was collected.
</ResponseField>

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 data from the [US Census Bureau](https://www.census.gov), which is
freely available.

<RequestExample>
  ```bash cURL
  curl --get 'https://osm.buntinglabs.com/v1/census/income' \
       --data "center=-86.902398,32.318930" \
       --data "radius=1000" \
       --data "api_key=demo"
  ```

  ```javascript JavaScript
  const params = new URLSearchParams({
    center: "-86.902398,32.318930",
    radius: "1000", // in meters
    api_key: "demo"
  });

  fetch(`https://osm.buntinglabs.com/v1/census/income?${params}`)
    .then(response => response.json())
    .then(data => console.log(data));
  ```

  ```python Python
  import requests

  params = {
    "center": "-86.902398,32.318930",
    "radius": "1000",
    "api_key": "demo"
  }

  response = requests.get("https://osm.buntinglabs.com/v1/census/income", params=params)
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "median_income": 34856.37
    "source": "US Census ACS 2020"
  }
  ```
</ResponseExample>