Our API is used through our subscription based Automatic updates Service. To get our username and password, you first need to purchase one of our databases then subscribe to our Automatic Update service for it.
Introduction
This describes the Golf-Course Database REST API. Please send all feedback, questions and requests to support@golf-course-database.com.
Version
The current version of the API is 1.0.0. The API supports semantic versioning (semver) via the HTTP Accept-Version header. If the version is not specified, the API will default to the latest version. To ensure the stability of your API, we recommend you request a specific version.
Requesting a specific version with the latest minor version and patches:
curl -H 'Accept-Version: ~1' https://api.golf-course-database.com:8000/clubs
Requesting a specific version with the latest patches:
curl -H 'Accept-Version: 1.0' https://api.golf-course-database.com:8000/clubs
Requesting a specific version:
curl -H 'Accept-Version: 1.0.0' https://api.golf-course-database.com:8000/clubs
Note that requesting Accept-Version: * will return the default version.
Authentication
All requests are secured using HTTP Basic Auth over HTTPS. HTTP requests will be refused. A user name and password must be sent with every request. These will be assigned to you when your account is created. Privileges (resource and field access) will be restricted by your package.
curl -u user:password https://api-staging.golf-course-database.com:8000/clubs
Requests
Base URL
| Environment | URL |
|---|---|
| Staging | https://api-staging.golf-course-database.com:8080 |
| Production | https://api.golf-course-database.com:8000 |
HTTP Verbs
| Verb | Description |
|---|---|
HEAD |
Can be issued against any endpoint to get only the HTTP header information. |
GET |
Used for retrieving a resource or a collection of resources. |
This is a read-only API so POST, PUT, PATCH, and DELETE verbs are not supported.
Responses
All responses are JSON encoded, without envelopes. Blank fields are included as "" or "null" instead of being omitted. Dates are returned in ISO 8601 format, i.e. YYYY-MM-DDTHH:MM:SSZ.
A single resource is represented as a JSON object:
{
"club_id": "USA-AK-00001",
"club_name": "Anchorage Golf Course",
"club_membership": "Public",
"number_of_holes": "18",
"address": "3651 O'Malley Rd",
"city": "Anchorage",
"state": "Alaska",
"country": "United States of America",
"postal_code": "99507",
"phone": "(907) 522-3363",
"fax": "(907) 349-6640",
"website": "www.anchoragegolfcourse.com",
"contact_name": "Rich Sayers",
"contact_title": "General Manager",
"email_address": "rich@anchoragegolfcourse.com",
"driving_range": "Yes",
"putting_green": "Yes",
"chipping_green": "No",
"practice_bunker": "No",
"motor_cart": "Yes",
"pull_cart": "Yes",
"golf_clubs_rental": "Yes",
"club_fitting": "Yes",
"pro_shop": "Yes",
"golf_lessons": "Yes",
"caddie_hire": "No",
"restaurant": "Yes",
"reception_hall": "No",
"changing_room": "Yes",
"lockers": "No",
"lodging_on_site": "No",
"last_update": "0000-00-00"
}
A collection of resources is represented as an array of JSON objects:
[
{
"club_id": "USA-AK-00001",
"club_name": "Anchorage Golf Course",
"club_membership": "Public",
"number_of_holes": "18",
"address": "3651 O'Malley Rd",
"city": "Anchorage",
"state": "Alaska",
"country": "United States of America",
"postal_code": "99507",
"phone": "(907) 522-3363",
"fax": "(907) 349-6640",
"website": "www.anchoragegolfcourse.com",
"contact_name": "Rich Sayers",
"contact_title": "General Manager",
"email_address": "rich@anchoragegolfcourse.com",
"driving_range": "Yes",
"putting_green": "Yes",
"chipping_green": "No",
"practice_bunker": "No",
"motor_cart": "Yes",
"pull_cart": "Yes",
"golf_clubs_rental": "Yes",
"club_fitting": "Yes",
"pro_shop": "Yes",
"golf_lessons": "Yes",
"caddie_hire": "No",
"restaurant": "Yes",
"reception_hall": "No",
"changing_room": "Yes",
"lockers": "No",
"lodging_on_site": "No",
"last_update": "0000-00-00"
},
{
"club_id": "USA-AK-00002",
"club_name": "Bear Valley Golf Course",
"club_membership": "Military",
"number_of_holes": "9",
"address": "28 Mile Anton Larson Bay Rd",
"city": "Kodiak",
"state": "Alaska",
"country": "United States of America",
"postal_code": "99615",
"phone": "(907) 486-7561",
"fax": "",
"website": "www.kodiakmwr.com/golf.shtml",
"contact_name": "",
"contact_title": "",
"email_address": "",
"driving_range": "Yes",
"putting_green": "Yes",
"chipping_green": "No",
"practice_bunker": "No",
"motor_cart": "Yes",
"pull_cart": "Yes",
"golf_clubs_rental": "Yes",
"club_fitting": "Yes",
"pro_shop": "Yes",
"golf_lessons": "Yes",
"caddie_hire": "No",
"restaurant": "Yes",
"reception_hall": "No",
"changing_room": "Yes",
"lockers": "No",
"lodging_on_site": "No",
"last_update": "0000-00-00"
}
...
]
Successful Requests
Successful requests return a 200 OK HTTP status.
Failed Requests
In addition to the HTTP status, failed requests return a response body:
{
"code": "ErrorCode",
"message": "Some error message"
}
Status Codes
| HTTP Status | Code | Description |
|---|---|---|
400 |
InvalidHeaderError |
Invalid HTTP header sent. |
400 |
InvalidVersionError |
Invalid API version requested. |
401 |
InvalidCredentialsError |
Authentication failed. |
403 |
NotAuthorizedError |
User doesn’t have access to the resource. |
404 |
ResourceNotFoundError |
Resource not found. |
405 |
BadMethodError |
Endpoint doesn’t support a method. |
409 |
InvalidArgumentError |
Invalid request argument sent. |
409 |
MissingParameterError |
Required parameter missing. |
500 |
InternalError |
Server error occurred. |
Endpoints
| Endpoint | Description |
|---|---|
/clubs |
Retrieves a collection of club resources. |
/clubs/{id} |
Retrieves a club resource by ID. |
/courses |
Retrieves a collection of course resources. |
/courses/{id} |
Retrieves a course resource by ID. |
/tees |
Retrieves a collection of tee resources. |
/tees/{id} |
Retrieves a tee resource by ID. |
/deleted-clubs |
Retrieves a collection of deleted club IDs. |
/deleted-courses |
Retrieves a collection of deleted course IDs. |
/deleted-tees |
Retrieves a collection of deleted tee IDs. |
Parameters
| Name | Value | Required? | Default | Description |
|---|---|---|---|---|
fields |
string | no | none | Comma-separated list of fields to return in the response. Applies to both individual resources and collections. |
page |
integer | no | 1 | Page number of a collection. Must be greater than 0. Applies to collections only. |
per_page |
integer | no | 20 | Page size of a collection, i.e. the number of items per page. Maximum size is 500. Must be greater than 0. Applies to collections only. |
sort |
string | no | none | Comma-separated list of fields to sort by. Applies to collections only. |
updated_since |
string | no | none | Date of last update. Limits the collection to items that are greater than or equal to the date. Applies to collections only. |
since |
string | no | none | Date of last update or deletion (depending on endpoint). Limits the collection to items that are greater than or equal to the date. Applies to collections only. |
{field} |
string | no | none | Resource field name used to filter result. See Resources section. Applies to collections only. |
Field Selection
You can limit the fields of a resource or resource collection by passing a ?fields query parameter with a comma-separated list of field names, e.g. ?fields=club_id,club_name Or, equivalently, by passing a ?fields parameter array, e.g. ?fields=club_id&fields=club_name or ?fields[]=club_id&fields[]=club_name (remember to URL-encode the []).
curl -u user:password 'https://api.golf-course-database.com:8000/clubs?fields=club_id,club_name'
The above is equivalent to:
curl -u user:password 'https://api.golf-course-database.com:8000/clubs?fields=club_id&fields=club_name'
[
{
"club_id": "USA-AK-00001",
"club_name": "Anchorage Golf Course",
},
{
"club_id": "USA-AK-00002",
"club_name": "Bear Valley Golf Course",
}
...
]
Filtering
You can filter collections by passing filter parameters in the query. A filter parameter is simply a resource field name with a value to filter by, e.g. ?city=augusta&club_membership=public. The value will be matched exactly (case-insensitive). Unique filter fields will be ANDed, while a filter field parameter array will be ORed. Filters can be combined to form complex expressions.
curl -u user:password 'https://api.golf-course-database.com:8000/clubs?city=augusta'
[
{
"club_id": "USA-GA-00012",
"club_name": "Augusta Country Club",
"club_membership": "Private",
"number_of_holes": "18",
"address": "655 Milledge Rd",
"city": "Augusta",
"state": "Georgia",
"country": "United States of America",
"postal_code": "30904",
"phone": "(706) 733-9426",
"fax": "(706) 733-8255",
"website": "www.augcc.com/",
"contact_name": "Henry Marburger",
"contact_title": "General Manager",
"email_address": "henrym@augcc.com",
"driving_range": "Yes",
"putting_green": "Yes",
"chipping_green": "No",
"practice_bunker": "No",
"motor_cart": "Yes",
"pull_cart": "Yes",
"golf_clubs_rental": "Yes",
"club_fitting": "Yes",
"pro_shop": "Yes",
"golf_lessons": "Yes",
"caddie_hire": "No",
"restaurant": "Yes",
"reception_hall": "No",
"changing_room": "Yes",
"lockers": "No",
"lodging_on_site": "No",
"last_update": "0000-00-00"
},
{
"club_id": "USA-GA-00013",
"club_name": "Augusta Municipal Golf Club",
"club_membership": "Municipal",
"number_of_holes": "18",
"address": "2023 Highland Ave",
"city": "Augusta",
"state": "Georgia",
"country": "United States of America",
"postal_code": "30904",
"phone": "(706) 731-9344",
"fax": "(706) 731-9426",
"website": "www.thepatchaugusta.com",
"contact_name": "Brian Hendry",
"contact_title": "Chairman",
"email_address": "info@thepatchaugusta.com",
"driving_range": "Yes",
"putting_green": "Yes",
"chipping_green": "No",
"practice_bunker": "No",
"motor_cart": "Yes",
"pull_cart": "Yes",
"golf_clubs_rental": "Yes",
"club_fitting": "Yes",
"pro_shop": "Yes",
"golf_lessons": "Yes",
"caddie_hire": "No",
"restaurant": "Yes",
"reception_hall": "No",
"changing_room": "Yes",
"lockers": "No",
"lodging_on_site": "No",
"last_update": "0000-00-00"
}
...
]
To match (club_membership = “public” OR club_membership = “military”) AND lodging_on_site = “yes”:
curl -u user:password 'https://api.golf-course-database.com:8000/clubs?club_membership=public&club_membership=military&lodging_on_site=yes'
[
{
"club_id": "USA-AL-00007",
"club_name": "Arrowhead Golf Course",
"club_membership": "Public",
"number_of_holes": "9",
"address": "3947 Holly Grove Road",
"city": "Jasper",
"state": "Alabama",
"country": "United States of America",
"postal_code": "35503",
"phone": "(205) 384-3065",
"fax": "",
"website": "",
"contact_name": "",
"contact_title": "",
"email_address": "",
"driving_range": "Yes",
"putting_green": "Yes",
"chipping_green": "No",
"practice_bunker": "Yes",
"motor_cart": "Yes",
"pull_cart": "Yes",
"golf_clubs_rental": "Yes",
"club_fitting": "Yes",
"pro_shop": "Yes",
"golf_lessons": "Yes",
"caddie_hire": "Yes",
"restaurant": "Yes",
"reception_hall": "Yes",
"changing_room": "Yes",
"lockers": "Yes",
"lodging_on_site": "Yes",
"last_update": "0000-00-00"
},
{
"club_id": "USA-AL-00010",
"club_name": "Auburn Links at Mill Creek",
"club_membership": "Public",
"number_of_holes": "18",
"address": "826 Shelltoomer Pkwy",
"city": "Auburn",
"state": "Alabama",
"country": "United States of America",
"postal_code": "36831",
"phone": "(334) 887-5151",
"fax": "(334) 826-6168",
"website": "http://www.auburnlinksgolf.com/",
"contact_name": "",
"contact_title": "",
"email_address": "auburnlinksatmillcreek@gmail.com",
"driving_range": "Yes",
"putting_green": "Yes",
"chipping_green": "No",
"practice_bunker": "Yes",
"motor_cart": "Yes",
"pull_cart": "Yes",
"golf_clubs_rental": "Yes",
"club_fitting": "Yes",
"pro_shop": "Yes",
"golf_lessons": "Yes",
"caddie_hire": "Yes",
"restaurant": "Yes",
"reception_hall": "Yes",
"changing_room": "Yes",
"lockers": "Yes",
"lodging_on_site": "Yes",
"last_update": "0000-00-00"
}
...
]
Latest Updates
To obtain the latest updates, you can pass the ?updated_since (also ?since) filter parameter with the desired date. The date must be in ISO 8601 format, i.e. YYYY-MM-DD. This will return all resources updated since the specified date (inclusive).
Latest Deletions
To obtain the latest deletions, you can pass the ?since filter parameter with the desired date. The date must be in ISO 8601 format, i.e. YYYY-MM-DD. This will return all IDs deleted since the specified date (inclusive).
Example:
curl -u user:password 'https://api.golf-course-database.com:8000/deleted-clubs?since=2015-11-16'
[
{
"id": 1,
"club_id": "USA-AK-0001",
"deleted_at": "2015-11-16T13:41:30.000Z"
},
{
"id": 2,
"club_id": "USA-AK-0002",
"deleted_at": "2015-11-16T13:41:30.000Z"
}
]
Sorting
You can sort collections by passing a ?sort query parameter with the fields to sort by in a comma-separated list. Order is ascending by default. To sort in descending order, prefix the field name with a -, e.g. ?sort=club_name,-club_membership.
curl -u user:password 'https://api.golf-course-database.com:8000/clubs?sort=club_name,-club_membership'
[
{
"club_id": "USA-AK-00002",
"club_name": "Bear Valley Golf Course",
"club_membership": "Military",
"number_of_holes": "9",
"address": "28 Mile Anton Larson Bay Rd",
"city": "Kodiak",
"state": "Alaska",
"country": "United States of America",
"postal_code": "99615",
"phone": "(907) 486-7561",
"fax": "",
"website": "www.kodiakmwr.com/golf.shtml",
"contact_name": "",
"contact_title": "",
"email_address": "",
"driving_range": "Yes",
"putting_green": "Yes",
"chipping_green": "No",
"practice_bunker": "No",
"motor_cart": "Yes",
"pull_cart": "Yes",
"golf_clubs_rental": "Yes",
"club_fitting": "Yes",
"pro_shop": "Yes",
"golf_lessons": "Yes",
"caddie_hire": "No",
"restaurant": "Yes",
"reception_hall": "No",
"changing_room": "Yes",
"lockers": "No",
"lodging_on_site": "No",
"last_update": "0000-00-00"
},
{
"club_id": "USA-AK-00004",
"club_name": "Chena Bend Golf Course",
"club_membership": "Military",
"number_of_holes": "18",
"address": "Bldg 2092 AFVR-FW-PAD",
"city": "Fort Wainwright",
"state": "Alaska",
"country": "United States of America",
"postal_code": "99703",
"phone": "(907) 353-6223",
"fax": "(907) 353-9400",
"website": "www.ftwainwrightfmwr.com/chenabendgolf.html",
"contact_name": "",
"contact_title": "",
"email_address": "",
"driving_range": "Yes",
"putting_green": "Yes",
"chipping_green": "No",
"practice_bunker": "No",
"motor_cart": "Yes",
"pull_cart": "Yes",
"golf_clubs_rental": "Yes",
"club_fitting": "Yes",
"pro_shop": "Yes",
"golf_lessons": "Yes",
"caddie_hire": "No",
"restaurant": "Yes",
"reception_hall": "No",
"changing_room": "Yes",
"lockers": "No",
"lodging_on_site": "No",
"last_update": "0000-00-00"
}
...
]
Pagination
All collections are paginated with a default page size of 20. You can customize this by passing the ?per_page query parameter, up to a maximum page size of 500. To retrieve a specific page, use the ?page query parameter. Page numbering is 1-based (not to be confused with an offset, which is 0-based). Omitting the page will default to the first page.
Total Count
The total count of the collection is returned in the Total-Count HTTP header. It is a count of the total number of resources (items) in the collection and is returned with every page request.
Total-Count: 13604
Link
The Link HTTP header contains the the pagination information. You should follow these header values rather than constructing your own.
Possible rel values:
| Name | Description |
|---|---|
next |
URL of the immediate next page of results (if there is one). |
last |
URL of the last page of results (if not at the last page). |
prev |
URL of the immediate previous page of results (if there is one). |
first |
URL of the first page of results (if not at the first page). |
First page:
curl -u user:password 'https://api.golf-course-database.com:8000/clubs'
Link: <https://api.golf-course-database.com:8000/clubs?page=2>; rel="next", <https://api.golf-course-database.com:8000/clubs?page=681>; rel="last"
Next page:
curl -u user:password 'https://api.golf-course-database.com:8000/clubs?page=2'
Link: <https://api.golf-course-database.com:8000/clubs?page=3>; rel="next", <https://api.golf-course-database.com:8000/clubs?page=681>; rel="last", <https://api.golf-course-database.com:8000/clubs?page=1>; rel="prev", <https://api.golf-course-database.com:8000/clubs?page=1>; rel="first"
Last page:
curl -u user:password 'https://api.golf-course-database.com:8000/clubs?page=681'
Link: <https://api.golf-course-database.com:8000/clubs?page=680>; rel="prev", <https://api.golf-course-database.com:8000/clubs?page=1>; rel="first"
Note that there are no "next" and "last" rel links for the last page.
Resources
Clubs
| Field Name |
|---|
| club_id |
| club_name |
| club_membership |
| number_of_holes |
| address |
| city |
| state |
| country |
| postal_code |
| phone |
| fax |
| website |
| driving_range |
| putting_green |
| chipping_green |
| practice_bunker |
| motor_cart |
| pull_cart |
| golf_clubs_rental |
| club_fitting |
| pro_shop |
| golf_lessons |
| caddie_hire |
| restaurant |
| reception_hall |
| changing_room |
| lockers |
| lodging_on_site |
| latitude |
| longitude |
| contact_name |
| contact_title |
| email_address |
| last_update |
Courses
| Field Name |
|---|
| course_id |
| club_id |
| course_name |
| holes |
| par |
| course_type |
| course_architect |
| open_date |
| guest_policy |
| currency |
| weekday_price |
| weekend_price |
| twilight_price |
| fairway |
| green |
| last_update |
Tees
| Field Name |
|---|
| tee_id |
| course_id |
| tee_name |
| tee_color |
| course_par_for_tee |
| hole1 |
| hole2 |
| hole3 |
| hole4 |
| hole5 |
| hole6 |
| hole7 |
| hole8 |
| hole9 |
| hole10 |
| hole11 |
| hole12 |
| hole13 |
| hole14 |
| hole15 |
| hole16 |
| hole17 |
| hole18 |
| total_distance |
| rating |
| slope |
| hole1_par |
| hole2_par |
| hole3_par |
| hole4_par |
| hole5_par |
| hole6_par |
| hole7_par |
| hole8_par |
| hole9_par |
| hole10_par |
| hole11_par |
| hole12_par |
| hole13_par |
| hole14_par |
| hole15_par |
| hole16_par |
| hole17_par |
| hole18_par |
| hole1_handicap |
| hole2_handicap |
| hole3_handicap |
| hole4_handicap |
| hole5_handicap |
| hole6_handicap |
| hole7_handicap |
| hole8_handicap |
| hole9_handicap |
| hole10_handicap |
| hole11_handicap |
| hole12_handicap |
| hole13_handicap |
| hole14_handicap |
| hole15_handicap |
| hole16_handicap |
| hole17_handicap |
| hole18_handicap |
| last_update |
Deleted Clubs
| Field Name |
|---|
| ID |
| club_id |
| deleted_at |
Deleted Courses
| Field Name |
|---|
| ID |
| course_id |
| deleted_at |
Deleted Tees
| Field Name |
|---|
| ID |
| tee_id |
| deleted_at |