All tutorials
Beginner5 min read

Find Golf Courses Near Me

Build a postcode-based club finder using GET /clubs/nearby.

Overview

The /clubs/nearby endpoint accepts a latitude, longitude, and radius (in km) and returns clubs ordered by distance. Since most users will have a postcode rather than coordinates, we use the free postcodes.io API to convert first.

Step 1 — Convert postcode to coordinates

postcodes.io is free, no auth required, and covers all UK postcodes including partial postcodes.

GET https://api.postcodes.io/postcodes/SW1A%201AA

{
  "result": {
    "postcode": "SW1A 1AA",
    "latitude": 51.501009,
    "longitude": -0.141588,
    "region": "London"
  }
}

Step 2 — Query /clubs/nearby

GET /clubs/nearby?lat=51.501009&lng=-0.141588&radius_km=32.18&limit=10

Parameters:
  lat          float   required  Latitude (-90 to 90)
  lng          float   required  Longitude (-180 to 180)
  radius_km    float   optional  Search radius in km (default: 25)
  limit        int     optional  Max results (default: 20, max: 50)
  offset       int     optional  Pagination offset

Full example

JavaScript
// 1. Convert postcode to coordinates using postcodes.io
async function findNearbyClubs(postcode, radiusMiles = 10) {
  const geoRes = await fetch(
    `https://api.postcodes.io/postcodes/${encodeURIComponent(postcode)}`
  );
  const geo = await geoRes.json();

  if (!geo.result) throw new Error('Invalid postcode');
  const { latitude, longitude } = geo.result;

  // 2. Call UK Golf API
  const radiusKm = radiusMiles * 1.609;
  const res = await fetch(
    `https://uk-golf-api.vercel.app/clubs/nearby?` +
    new URLSearchParams({
      lat: latitude,
      lng: longitude,
      radius_km: radiusKm,
      limit: 10,
    }),
    {
      headers: {
        'X-RapidAPI-Key': process.env.RAPIDAPI_KEY,
        'X-RapidAPI-Host': 'uk-golf-course-data-api.p.rapidapi.com',
      }
    }
  );

  return await res.json();
}

// Example usage
const clubs = await findNearbyClubs('SW1A 1AA', 20);
clubs.data.forEach(club => {
  console.log(`${club.name} — ${club.distance_km.toFixed(1)} km`);
});
Python
import requests

def find_nearby_clubs(postcode: str, radius_miles: float = 10):
    # 1. Convert postcode to coordinates
    geo = requests.get(
        f"https://api.postcodes.io/postcodes/{postcode.replace(' ', '%20')}"
    ).json()

    if not geo.get("result"):
        raise ValueError("Invalid postcode")

    lat = geo["result"]["latitude"]
    lng = geo["result"]["longitude"]
    radius_km = radius_miles * 1.609

    # 2. Call UK Golf API
    res = requests.get(
        "https://uk-golf-api.vercel.app/clubs/nearby",
        params={
            "lat": lat,
            "lng": lng,
            "radius_km": radius_km,
            "limit": 10,
        },
        headers={
            "X-RapidAPI-Key": "YOUR_API_KEY",
            "X-RapidAPI-Host": "uk-golf-course-data-api.p.rapidapi.com",
        }
    )

    return res.json()

clubs = find_nearby_clubs("SW1A 1AA", radius_miles=20)
for club in clubs["data"]:
    print(f"{club['name']} — {club['distance_km']:.1f} km")

Sample response

{
  "data": [
    {
      "id": "...",
      "name": "Royal Wimbledon Golf Club",
      "county": "Greater London",
      "postcode": "SW19 5NR",
      "latitude": 51.4234,
      "longitude": -0.2134,
      "distance_km": 5.2,
      "google_rating": 4.5,
      "google_review_count": 127,
      "phone": "+44 20 8946 2125",
      "website": "https://www.rwgc.co.uk"
    }
  ],
  "meta": {
    "total": 23,
    "count": 10,
    "lat": 51.5014,
    "lng": -0.1419,
    "radius_km": 32.18
  }
}

Next steps