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

# Neighborhood Description

> Describes a neighborhood to contextualize a home, rental, or investment opportunity listed on a website.

This API generates a description of a neighborhood surrounding a location. It includes
points of interest potential residents might want to know, including:

* Nearby restaurants and cafes
* Schools in walking distance
* Grocery stores and supermarkets

This is especially useful for describing a rental or home listing on a website or contextualizing
a potential investment opportunity for prospective investors. By providing an easy-to-read description,
websites can enhance the viewer experience without copy-paste formatting.

### Sample Output

The following was generated for an apartment near 1581 Webster St #235, San Francisco, CA 94115.

> Welcome to Japantown, a vibrant and diverse neighborhood in San Francisco!
> The area is known for its many nearby Asian restaurants, and the convenience of having
> a Safeway right around the corner for all your grocery needs. The neighborhood is
> highly educated, with 29% of residents holding masters degrees. The area is very
> walkable and densely populated with 3-story buildings. The average home in the
> area sells for \$1.2M.
> The nearby public schools are rated as 5/10, it may not be the best option
> for families with school-aged children. But for those that work in the Financial
> District, the SFMTA 24 and 38 buses provide good transit options into the city.
> This is a great neighborhood for those looking to be in the heart of the city, with
> easy access to all that San Francisco has to offer.

### Request Parameters

<ParamField body="address" type="string" placeholder="2355 Broadway, Oakland, CA 94612" required>
  The full address of the target location. Points of interest (POIs) in a circle around this location
  will be extracted and summarized as part of the description.
</ParamField>

<ParamField body="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 header="content-type" type="string" placeholder="application/json" required>
  This endpoint requires that the `Content-Type` header be set to `application/json`.
</ParamField>

### Response

When features are successfully counted, a 200 OK response will be
issued, with `Content-Type: application/json`.

<ResponseField name="description" type="string">
  The description of the surrounding neighborhood.
</ResponseField>

<ResponseField name="coordinates" type="string">
  After the input address is *geocoded* to the right location, this contains
  an array (in longitude, latitude order) of the location position.
</ResponseField>

<ResponseField name="attribution_text" type="string">
  Sample attribution text the end application could display.

  Attribution in your application is required by OpenStreetMap's ODbL license.
  Because the description is generated using OpenStreetMap data, proper attribution
  is required for use in your application.

  See:

  * [OpenStreetMap copyright and license](https://www.openstreetmap.org/copyright)
  * [OSM Foundation's Attribution Guidelines](https://wiki.osmfoundation.org/wiki/Licence/Attribution_Guidelines)
  * [The ODbL license](https://opendatacommons.org/licenses/odbl/)
</ResponseField>

<ResponseField name="attribution_link" type="string">
  Link to the OpenStreetMap copyright page.
</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>

<RequestExample>
  ```bash cURL
  curl 'https://osm.buntinglabs.com/v1/poi/neighborhood' \
       --header "Content-Type: application/json" \
       --data '{
          "api_key": "YOUR_API_KEY_HERE",
          "address": "800 N Alameda St, Los Angeles, CA 90012"
       }'
  ```

  ```javascript JavaScript
  const body = JSON.stringify({
    api_key: "YOUR_API_KEY_HERE",
    address: "800 N Alameda St, Los Angeles, CA 90012"
  });

  fetch("https://osm.buntinglabs.com/v1/poi/neighborhood", {
    method: 'POST',
    headers: { "Content-Type": "application/json" },
    body
  })
    .then(response => response.json())
    .then(data => console.log(data));
  ```

  ```python Python
  import requests

  data = {
    "api_key": "YOUR_API_KEY_HERE",
    "address": "800 N Alameda St, Los Angeles, CA 90012"
  }

  response = requests.post("https://osm.buntinglabs.com/v1/poi/neighborhood", json=data)
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "coordinates": [
      -122.4384732,
      37.7794274
    ],
    "description": "The area is known for its many nearby Asian restaurants, and the convenience of having a Safeway right around the corner for all your grocery needs.",
    "attribution_text": "Map data from OpenStreetMap",
    "attribution_link": "https://www.openstreetmap.org/copyright"
  }
  ```
</ResponseExample>