Our API


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.

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.

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.

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