esc
Loading...
to navigate
to select
API reference

Places

Retrieve local places by area, category, name, coordinates, or stable token. Permanently closed places are excluded.

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

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

Pagination is applied in pages of 40 only when coordinates or place_type are supplied.

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 when pagination applies.
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",
    "longitude": -73.9501,
    "latitude": 40.7241,
    "full_address": "123 Example St, Brooklyn, NY 11222",
    "website": "https://example.com",
    "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.
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",
    "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.
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.
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",
    "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",
  "full_address": "123 Example St, Brooklyn, NY 11222"
}