Skip to content
API reference

Places

Retrieve local places by area, category, name, coordinates, or stable token. Permanently closed places are excluded unless include_closed=true. List endpoints that are not distance-sorted order by editorial_score (nulls last), then rating.

GET /api/v1/places.json?place_type=cafe&page=1

Lists places with area, city, category, and coordinate filters.

Every request is paginated. Default page size is 10; pass per_page to request more, capped at 100.

Query parameters

Name Type Required Description
neighborhood_id integer No Filter by neighborhood database ID.
district_id integer No Filter by district database ID.
latitude number No Sort by distance; use with longitude.
longitude number No Sort by distance; use with latitude.
place_type string No Filter by one place category.
page integer No Page number. Defaults to 1.
per_page integer No Page size. Defaults to 10, maximum 100.
include_closed boolean No Include permanently closed places. Defaults to false.
city_uuids[] / city_names[] array No Filter by one or more cities.

Example request

curl --get 'https://hoodsdk.com/api/v1/places.json?place_type=cafe&page=1'

Example response 200 OK

[
  {
    "id": 42,
    "name": "Example Cafe",
    "description": "A neighborhood cafe.",
    "longitude": -73.9501,
    "latitude": 40.7241,
    "full_address": "123 Example St, Brooklyn, NY 11222",
    "website": "https://example.com",
    "rating": 4.2,
    "editorial_score": 1.5,
    "place_type": "cafe",
    "primary_image": "https://cdn.example.com/place.jpg"
  }
]
GET /api/v1/places/all.json?limit=20&place_types[]=cafe

Returns a limited set of places using the rich place representation with image variants and areas.

Query parameters

Name Type Required Description
limit integer No Maximum records. Defaults to 20.
place_types[] array No Filter by place categories.
neighborhood_uuid string No Filter by neighborhood UUID.
include_closed boolean No Include permanently closed places. Defaults to false.
city_uuids[] / city_names[] array No Filter by cities.

Example request

curl --get 'https://hoodsdk.com/api/v1/places/all.json?limit=20&place_types[]=cafe'

Example response 200 OK

[
  {
    "id": 42,
    "token": "example-cafe-abc123",
    "name": "Example Cafe",
    "place_type": "cafe",
    "rating": 4.2,
    "editorial_score": 1.5,
    "full_address": "123 Example St, Brooklyn, NY 11222",
    "latitude": 40.7241,
    "longitude": -73.9501,
    "primary_image": {"small": "https://cdn.example.com/small.jpg", "large": "https://cdn.example.com/large.jpg"},
    "neighborhoods": [{"uuid": "neighborhood-uuid", "name": "Greenpoint"}],
    "districts": [{"uuid": "district-uuid", "name": "Brooklyn"}]
  }
]
GET /api/v1/places/top.json?limit=5&place_types[]=cafe

Returns top places grouped by place type, with a featured collection.

Query parameters

Name Type Required Description
limit integer No Maximum places per group.
place_types[] array No Groups to include.
except_place_types[] array No Groups to exclude.
neighborhood_uuid string No Limit results to a neighborhood.
include_closed boolean No Include permanently closed places. Defaults to false.
city_uuids[] / city_names[] array No Filter by cities.

Example request

curl --get 'https://hoodsdk.com/api/v1/places/top.json?limit=5&place_types[]=cafe'

Example response 200 OK

{
  "featured": [{"id": 42, "name": "Example Cafe", "place_type": "cafe"}],
  "cafe": [{"id": 42, "name": "Example Cafe", "place_type": "cafe"}],
  "park": [{"id": 81, "name": "Example Park", "place_type": "park"}]
}
GET /api/v1/places/nearby.json?latitude=40.7241&longitude=-73.9501&radius=1

Finds places nearest to a coordinate, sorted by distance.

Query parameters

Name Type Required Description
latitude number Yes Origin latitude.
longitude number Yes Origin longitude.
radius integer No Radius in miles. Defaults to 1.
limit integer No Maximum records. Defaults to 20.
place_types[] array No Filter by categories.
include_closed boolean No Include permanently closed places. Defaults to false.
city_uuids[] / city_names[] array No Filter by cities.

Example request

curl --get 'https://hoodsdk.com/api/v1/places/nearby.json?latitude=40.7241&longitude=-73.9501&radius=1'

Example response 200 OK

[
  {
    "id": 42,
    "token": "example-cafe-abc123",
    "name": "Example Cafe",
    "place_type": "cafe",
    "rating": 4.2,
    "editorial_score": 1.5,
    "full_address": "123 Example St, Brooklyn, NY 11222",
    "latitude": 40.7241,
    "longitude": -73.9501,
    "primary_image": {"small": "https://cdn.example.com/small.jpg", "large": "https://cdn.example.com/large.jpg"},
    "neighborhoods": [{"uuid": "neighborhood-uuid", "name": "Greenpoint"}],
    "districts": [{"uuid": "district-uuid", "name": "Brooklyn"}]
  }
]
GET /api/v1/places/find.json?token=example-cafe-abc123

Retrieves one place by its stable public token. Returns an empty object when no place matches.

Query parameters

Name Type Required Description
token string Yes The place token.

Example request

curl --get 'https://hoodsdk.com/api/v1/places/find.json?token=example-cafe-abc123'

Example response 200 OK

{
  "id": 42,
  "token": "example-cafe-abc123",
  "name": "Example Cafe",
  "place_type": "cafe",
  "rating": 4.2,
  "editorial_score": 1.5,
  "full_address": "123 Example St, Brooklyn, NY 11222"
}