Get Map Properties
Get properties for map display with clustering and bounds
/members/properties/mapOverview
Retrieves properties optimized for map display with clustering support and viewport bounds. This endpoint is designed for interactive maps where properties need to be displayed as markers or clusters based on zoom level and viewport.
Returns lean property data suitable for map markers while supporting dynamic clustering and bounds-based filtering.
Authentication
Requires a valid Clerk JWT token in the Authorization header.
Request Body
boundsbodyobjectrequiredMap viewport bounds for filtering properties
bounds
northbodynumberrequiredNorthern boundary latitude
southbodynumberrequiredSouthern boundary latitude
eastbodynumberrequiredEastern boundary longitude
westbodynumberrequiredWestern boundary longitude
zoombodynumberrequiredMap zoom level (affects clustering behavior)
datesbodyobjectCheck-in and check-out dates for availability filtering
properties
checkInbodystringCheck-in date (YYYY-MM-DD)
checkOutbodystringCheck-out date (YYYY-MM-DD)
filtersbodyobjectSearch filters to apply
filter options
priceRangebodyobjectPrice range in points per night
price range
minbodynumberMinimum price per night
maxbodynumberMaximum price per night
propertyTypesbodyarrayProperty types to include
amenitiesbodyarrayRequired amenities
brandsbodyarraySpecific brands to include
guestRatingbodynumberMinimum guest rating
enableClusteringbodybooleanWhether to enable property clustering (default: true)
clusterRadiusbodynumberClustering radius in pixels (default: 50)
Response
Returns properties and clusters optimized for map display.
propertiesarrayrequiredIndividual properties that should be displayed as markers
property markers
idnumberrequiredProperty identifier
latitudenumberrequiredProperty latitude
longitudenumberrequiredProperty longitude
namestringrequiredProperty name
nightlyCostnumberrequiredCost per night in points
guestRatingnumberAverage guest rating
heroImageobjectThumbnail image for map popup
image
urlstringrequiredImage URL
altstringAlt text
availablebooleanAvailability status for requested dates (if dates provided)
clustersarrayrequiredProperty clusters for areas with multiple properties
cluster markers
idstringrequiredCluster identifier
latitudenumberrequiredCluster center latitude
longitudenumberrequiredCluster center longitude
propertyCountnumberrequiredNumber of properties in cluster
averageCostnumberrequiredAverage nightly cost in the cluster
costRangeobjectPrice range within the cluster
cost range
minnumberrequiredLowest price in cluster
maxnumberrequiredHighest price in cluster
boundsobjectrequiredGeographic bounds of the cluster
cluster bounds
northnumberrequiredNorthern boundary
southnumberrequiredSouthern boundary
eastnumberrequiredEastern boundary
westnumberrequiredWestern boundary
totalnumberrequiredTotal number of properties within the bounds (before clustering)
viewportobjectSuggested viewport adjustments
viewport
boundsobjectOptimal bounds for displaying all results
zoomnumberSuggested zoom level
Example
const response = await fetch('https://api.journey.com/members/properties/map', {
method: 'POST',
headers: {
'Authorization': `Bearer ${clerkToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
bounds: {
north: 40.9176,
south: 40.4774,
east: -73.7004,
west: -74.2591
},
zoom: 10,
dates: {
checkIn: '2024-06-15',
checkOut: '2024-06-17'
},
enableClustering: true,
clusterRadius: 50
})
});Request
curl -X POST "https://api.journey.com/members/properties/map" \
-H "Authorization: Bearer YOUR_CLERK_JWT" \
-H "Content-Type: application/json" \
-d '{
"bounds": {
"north": 40.9176,
"south": 40.4774,
"east": -73.7004,
"west": -74.2591
},
"zoom": 10,
"dates": {
"checkIn": "2024-06-15",
"checkOut": "2024-06-17"
},
"filters": {
"priceRange": {
"min": 30000,
"max": 100000
},
"propertyTypes": ["hotel", "resort"],
"guestRating": 4.0
},
"enableClustering": true,
"clusterRadius": 50
}'Response
{
"properties": [
{
"id": 123,
"latitude": 40.7128,
"longitude": -74.0060,
"name": "Manhattan Boutique Hotel",
"nightlyCost": 45000,
"guestRating": 4.6,
"heroImage": {
"url": "https://cdn.journey.com/properties/123/thumb.jpg",
"alt": "Manhattan boutique hotel exterior"
},
"available": true
}
],
"clusters": [
{
"id": "cluster_midtown_1",
"latitude": 40.7550,
"longitude": -73.9840,
"propertyCount": 15,
"averageCost": 52000,
"costRange": {
"min": 35000,
"max": 85000
},
"bounds": {
"north": 40.7614,
"south": 40.7486,
"east": -73.9765,
"west": -73.9915
}
}
],
"total": 127,
"viewport": {
"bounds": {
"north": 40.8876,
"south": 40.5074,
"east": -73.7304,
"west": -74.2291
},
"zoom": 11
}
}Usage Notes
Clustering Behavior
- High zoom levels (greater than 15): Properties displayed individually
- Medium zoom levels (10-15): Automatic clustering based on density
- Low zoom levels (less than 10): Aggressive clustering to reduce marker count
Performance Considerations
- Viewport size: Larger bounds return more properties
- Filter complexity: More filters increase processing time
- Response size: Clustering reduces payload size for dense areas
Map Integration
- Display individual properties as markers with price labels
- Show clusters as grouped markers with property count
- Handle cluster clicks by zooming in or showing property list
- Update on map move by calling endpoint with new bounds
Related Endpoints
- Search Properties - Full property search with list results