> ## Documentation Index
> Fetch the complete documentation index at: https://docs.golfjoin.co.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# 골프장

> 티 매물 등록에 필요한 골프장 ID와 코스 이름을 받습니다.

> 티 매물은 골프장 이름이 아니라 **골프장 ID**로 등록합니다. 골프장 목록을 받아 두고, 매니저가 고른 골프장의 ID와 코스 이름을 쓰세요.

## 무엇을 조회하나요

| 경로 | 용도 |
| - | - |
| `GET /api/v1/golf-courses?all=1` | 전체 골프장과 코스 목록 (동기화용) |
| `GET /api/v1/golf-courses?q={검색어}` | 골프장 이름 검색 (자동완성용, 최대 20건) |

두 API 모두 인증 없이 호출할 수 있습니다.

## 전체 목록

```bash theme={null}
curl "https://golfjoin.co.kr/api/v1/golf-courses?all=1"
```

```json theme={null}
{
  "courses": [
    {
      "id": 3,
      "name": "라싸",
      "region": "GYEONGGI_NORTH",
      "roadAddress": null,
      "address": "경기도 포천시 이동면 제비울2길 161",
      "updatedAt": "2026-10-21T07:14:53.971Z",
      "fields": [
        { "id": 67, "name": "레이크", "holeCount": 9 },
        { "id": 94, "name": "마운틴", "holeCount": 9 },
        { "id": 65, "name": "밸리", "holeCount": 9 }
      ]
    }
  ]
}
```

| 필드 | 형식 | 설명 |
| - | - | - |
| `id` | integer | 골프장 ID. 등록할 때 `golfCourseId`로 씁니다. |
| `name` | string | 골프장 이름 |
| `region` | string | 지역. [지역 값](#지역-값) 참고 |
| `roadAddress` | string 또는 null | 도로명 주소 |
| `address` | string 또는 null | 지번 또는 대표 주소 |
| `updatedAt` | string | 골프장 정보가 마지막으로 바뀐 시각(UTC) |
| `fields` | array | 골프장 안의 코스. 없으면 빈 배열 |
| `fields[].id` | integer | 코스 ID (참고용) |
| `fields[].name` | string | 코스 이름. 등록할 때 `courseLabel`로 씁니다. |
| `fields[].holeCount` | integer 또는 null | 코스의 홀 수 |

응답은 1시간 동안 캐시됩니다. 하루에 한 번 받아 두고 프로그램 안에서 검색하는 방식을 권합니다.

## 이름 검색

```bash theme={null}
curl "https://golfjoin.co.kr/api/v1/golf-courses?q=라싸골프클럽"
```

```json theme={null}
{
  "courses": [
    { "id": 3, "name": "라싸", "region": "GYEONGGI_NORTH", "address": "경기도 포천시 이동면 제비울2길 161", "roadAddress": null, "slug": "rassa" }
  ]
}
```

이름 일부로도 찾고, `CC`, `GC`, `골프클럽`, `컨트리클럽` 같은 꼬리와 띄어쓰기를 빼고도 맞춰 찾습니다. 위 예시처럼 "라싸골프클럽"으로 검색해도 "라싸"가 나옵니다. 검색 결과에는 코스 목록이 없으니, 코스 이름은 전체 목록에서 가져오세요.

## 코스 이름

* 27홀, 36홀 골프장은 대부분 9홀 코스가 여러 개 있습니다. 매니저가 고른 코스 이름을 `courseLabel`에 넣으면 조인성공 화면에 `라싸(레이크)`처럼 함께 표시됩니다.
* 코스 이름이 없는 골프장(9홀 단일 코스 등)은 `courseLabel`을 비워 두세요.
* 목록에 없는 코스 이름도 30자 이내라면 그대로 넣을 수 있습니다.

## 골프장 변경

조인성공은 같은 골프장이 두 번 등록된 경우 하나로 합치고, 이름이 바뀐 골프장은 새 이름으로 고칩니다. 합쳐서 없어진 골프장 ID로 등록하면 `404 course_not_found`를 돌려줍니다.

* 하루 한 번 전체 목록을 받아, 없어진 ID와 바뀐 이름을 반영하세요.
* 골프장을 합칠 때는 없어진 ID와 남은 ID 대응표를 연동 신청 때 알려 주신 메일 주소로 따로 보내 드립니다.
* 이미 올린 매물은 합칠 때 남은 골프장으로 함께 옮겨지니 따로 처리할 필요가 없습니다.

## 지역 값

| `region` | 지역 |
| - | - |
| `GYEONGGI_NORTH` | 경기북부 |
| `GYEONGGI_SOUTH` | 경기남부 |
| `GANGWON` | 강원 |
| `CHUNGCHEONG` | 충청 |
| `JEOLLA` | 전라 |
| `GYEONGSANG` | 경상 |
| `JEJU` | 제주 |
| `ETC` | 기타·미분류 |

예전 값인 `INCHEON`, `GYEONGGI_EAST`, `SEOUL`, `GYEONGGI`가 일부 남아 있을 수 있습니다. 각각 경기북부, 경기남부, 기타로 보면 됩니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.