Geospatial Search

​

Find Nearby Venues

curl -X GET "https://api.hub.example/api/venues/nearby?lat=41.3851&lng=2.1734&radiusMeters=5000" \
  -H "Content-Type: application/json"

​

Query Parameters

​

Response

​

Example Searches

​

Search Near Barcelona City Center

# Find venues within 2 km of Plaça de Catalunya
curl -X GET "https://api.hub.example/api/venues/nearby?lat=41.3851&lng=2.1734&radiusMeters=2000" \
  -H "Content-Type: application/json"

​

Search Near Madrid

# Find venues within 10 km of Puerta del Sol, Madrid
curl -X GET "https://api.hub.example/api/venues/nearby?lat=40.4168&lng=-3.7038&radiusMeters=10000" \
  -H "Content-Type: application/json"

​

Search with Default Radius

# Uses default 5km radius
curl -X GET "https://api.hub.example/api/venues/nearby?lat=51.5074&lng=-0.1278" \
  -H "Content-Type: application/json"

​

Geospatial Implementation

​

How It Works

1. Coordinate System: The API uses the WGS 84 coordinate system (SRID 4326) for latitude/longitude values
2. Distance Calculation: PostGIS calculates great-circle distances on the Earth’s surface
3. Spatial Index: A GiST index on the coordinates column enables efficient geographic queries
4. Active Only: Only venues with status ACTIVE are included in search results

​

Performance Characteristics

• Typical Response Time: < 100ms for searches returning up to 100 venues
• Scalability: Spatial index ensures logarithmic query time regardless of database size
• Accuracy: Great-circle distance calculations accurate to within meters

​

Use Cases

• Mobile Apps: “Find courts near me” feature using device GPS
• Map Interfaces: Display venues on interactive maps with dynamic radius
• Location-Based Booking: Show available courts within walking/driving distance
• Coverage Analysis: Identify underserved areas for new venue opportunities

​

Common Coordinate Examples

​

Best Practices

​

Choosing the Right Radius

• Urban Areas: 1-3 km (users willing to travel shorter distances)
• Suburban Areas: 5-10 km (more spread out venues)
• Rural Areas: 15-25 km (fewer venues, longer travel acceptable)

​

Client-Side Implementation

// Get user's current location
navigator.geolocation.getCurrentPosition(async (position) => {
  const { latitude, longitude } = position.coords;
  
  // Search nearby venues
  const response = await fetch(
    `https://api.hub.example/api/venues/nearby?lat=${latitude}&lng=${longitude}&radiusMeters=5000`,
    {
      method: 'GET',
      headers: { 'Content-Type': 'application/json' }
    }
  );
  
  const venues = await response.json();
  
  // Display venues on map or list
  displayVenues(venues);
});

​

Error Handling

const searchNearby = async (lat, lng, radius = 5000) => {
  // Validate coordinates
  if (lat < -90 || lat > 90) {
    throw new Error('Latitude must be between -90 and 90');
  }
  if (lng < -180 || lng > 180) {
    throw new Error('Longitude must be between -180 and 180');
  }
  
  const response = await fetch(
    `https://api.hub.example/api/venues/nearby?lat=${lat}&lng=${lng}&radiusMeters=${radius}`,
    {
      method: 'GET',
      headers: { 'Content-Type': 'application/json' }
    }
  );
  
  if (!response.ok) {
    throw new Error(`Search failed: ${response.status}`);
  }
  
  return response.json();
};