# Get Map Properties
> Source: /api-reference/members/properties/map
> Get properties for map display with clustering and bounds
> Endpoint: POST /members/properties/map

## Overview [#overview]

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 [#authentication]

Requires a valid Clerk JWT token in the Authorization header.

## Request Body [#request-body]

<ParamField body="bounds" type="object" required>
  Map viewport bounds for filtering properties
  
  <Expandable title="bounds">
    <ParamField body="north" type="number" required>
      Northern boundary latitude
    </ParamField>
    
    <ParamField body="south" type="number" required>
      Southern boundary latitude
    </ParamField>
    
    <ParamField body="east" type="number" required>
      Eastern boundary longitude
    </ParamField>
    
    <ParamField body="west" type="number" required>
      Western boundary longitude
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="zoom" type="number" required>
  Map zoom level (affects clustering behavior)
</ParamField>

<ParamField body="dates" type="object">
  Check-in and check-out dates for availability filtering
  
  <Expandable title="properties">
    <ParamField body="checkIn" type="string">
      Check-in date (YYYY-MM-DD)
    </ParamField>
    
    <ParamField body="checkOut" type="string">
      Check-out date (YYYY-MM-DD)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="filters" type="object">
  Search filters to apply
  
  <Expandable title="filter options">
    <ParamField body="priceRange" type="object">
      Price range in points per night
      
      <Expandable title="price range">
        <ParamField body="min" type="number">
          Minimum price per night
        </ParamField>
        
        <ParamField body="max" type="number">
          Maximum price per night
        </ParamField>
      </Expandable>
    </ParamField>
    
    <ParamField body="propertyTypes" type="array">
      Property types to include
    </ParamField>
    
    <ParamField body="amenities" type="array">
      Required amenities
    </ParamField>
    
    <ParamField body="brands" type="array">
      Specific brands to include
    </ParamField>
    
    <ParamField body="guestRating" type="number">
      Minimum guest rating
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="enableClustering" type="boolean">
  Whether to enable property clustering (default: true)
</ParamField>

<ParamField body="clusterRadius" type="number">
  Clustering radius in pixels (default: 50)
</ParamField>

## Response [#response]

Returns properties and clusters optimized for map display.

<ResponseField name="properties" type="array" required>
  Individual properties that should be displayed as markers
  
  <Expandable title="property markers">
    <ResponseField name="id" type="number" required>
      Property identifier
    </ResponseField>
    
    <ResponseField name="latitude" type="number" required>
      Property latitude
    </ResponseField>
    
    <ResponseField name="longitude" type="number" required>
      Property longitude
    </ResponseField>
    
    <ResponseField name="name" type="string" required>
      Property name
    </ResponseField>
    
    <ResponseField name="nightlyCost" type="number" required>
      Cost per night in points
    </ResponseField>
    
    <ResponseField name="guestRating" type="number">
      Average guest rating
    </ResponseField>
    
    <ResponseField name="heroImage" type="object">
      Thumbnail image for map popup
      
      <Expandable title="image">
        <ResponseField name="url" type="string" required>
          Image URL
        </ResponseField>
        
        <ResponseField name="alt" type="string">
          Alt text
        </ResponseField>
      </Expandable>
    </ResponseField>
    
    <ResponseField name="available" type="boolean">
      Availability status for requested dates (if dates provided)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="clusters" type="array" required>
  Property clusters for areas with multiple properties
  
  <Expandable title="cluster markers">
    <ResponseField name="id" type="string" required>
      Cluster identifier
    </ResponseField>
    
    <ResponseField name="latitude" type="number" required>
      Cluster center latitude
    </ResponseField>
    
    <ResponseField name="longitude" type="number" required>
      Cluster center longitude
    </ResponseField>
    
    <ResponseField name="propertyCount" type="number" required>
      Number of properties in cluster
    </ResponseField>
    
    <ResponseField name="averageCost" type="number" required>
      Average nightly cost in the cluster
    </ResponseField>
    
    <ResponseField name="costRange" type="object">
      Price range within the cluster
      
      <Expandable title="cost range">
        <ResponseField name="min" type="number" required>
          Lowest price in cluster
        </ResponseField>
        
        <ResponseField name="max" type="number" required>
          Highest price in cluster
        </ResponseField>
      </Expandable>
    </ResponseField>
    
    <ResponseField name="bounds" type="object" required>
      Geographic bounds of the cluster
      
      <Expandable title="cluster bounds">
        <ResponseField name="north" type="number" required>
          Northern boundary
        </ResponseField>
        
        <ResponseField name="south" type="number" required>
          Southern boundary
        </ResponseField>
        
        <ResponseField name="east" type="number" required>
          Eastern boundary
        </ResponseField>
        
        <ResponseField name="west" type="number" required>
          Western boundary
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number" required>
  Total number of properties within the bounds (before clustering)
</ResponseField>

<ResponseField name="viewport" type="object">
  Suggested viewport adjustments
  
  <Expandable title="viewport">
    <ResponseField name="bounds" type="object">
      Optimal bounds for displaying all results
    </ResponseField>
    
    <ResponseField name="zoom" type="number">
      Suggested zoom level
    </ResponseField>
  </Expandable>
</ResponseField>

## Example [#example]

```typescript
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
  })
});
```

<RequestExample>

```bash cURL
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
  }'
```

</RequestExample>

<ResponseExample>

```json 200 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
  }
}
```

</ResponseExample>

## Usage Notes [#usage-notes]

### Clustering Behavior [#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 [#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 [#map-integration]

1. **Display individual properties** as markers with price labels
2. **Show clusters** as grouped markers with property count
3. **Handle cluster clicks** by zooming in or showing property list
4. **Update on map move** by calling endpoint with new bounds

## Related Endpoints [#related-endpoints]

- [Search Properties](/api-reference/members/properties/search) - Full property search with list results