API Guides

Introduction

Golfbert provides a REST API that includes hole information and geolocation for the top golf courses across the USA. Below is an overview and some quick examples of how to get up and running with the Golfbert API.

You can use this API to retrieve:

1. Course information
   • Course name
   • Address
   • Handicap
   • Slope and rating
   • Location
2. Hole information
   • Yardage
   • Par
   • Handicap
   • Teeboxes (color, tee box type, yardage)
3. Geolocation polygons for course surfaces
   • Greens
   • Fairways
   • Sand traps
   • Stone
   • Trees and wooded areas
   • Water hazards

Getting Started

You can find the Golfbert API at https://api.golfbert.com. The current version of the API is v1 which means that all endpoints are prefixed by this version, for example: https://api.golfbert.com/v1/courses. All endpoints are https only and all of them require authentication. See below for more information around how to compose requests.

To get started, you will need an API token, an access key and a secret key which you will use in every interaction with the API. While this is something you receive as part of a paying engagement, we do have demo accounts (restrictions apply) so that you can experiment. Once you have that information, you can proceed.

Contact us for a free demo account

Authentication and Authorization

Every account/api token provided is associated with entitlements as far as which courses can be accessed. All that happens behind the scenes. If you are not seeing courses that you think you are supposed to please contact us.

In order to authenticate, every request to the Golfbert API must include the API token you received along with a valid AWS Signature Version 4 that is derived from the access key and secret sent to you. Keep in mind that if you lose your secret key, there is no way to recover it. It was emailed to you upon registartion, but if you cannot locate it, you will need a new one to be created. For information around AWS Signature Version 4 please take a look here: http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html. You can find libraries that will perform the request signing for you for nearly every popular language out there, for example nodejs: https://github.com/mhart/aws4, Python: https://github.com/DavidMuller/aws-requests-auth. The API key provided must also accompany every API request as a request header with the name x-api-key.

A typical API request might look like this:

GET /v1/ping HTTP/1.1
x-api-key: GFHFJHFH7588ENJ
Content-Type: application/x-www-form-urlencoded
Host: api.golfbert.com
X-Amz-Date: 20161221T201625Z

Authorization: AWS4-HMAC-SHA256 Credential=GFHFJHFH7588ENJ/20161221/us-east-1/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-api-key, Signature=4aea424a9a48429e7c608d1642af83fdd01fbf4c7ce3689f6076ecd9ee96820b

Testing Your API key

In order to make sure you are using the API key as required and you are signing your requests correctly, you can try to hit the courses endpoint as a test: https://api.golfbert.com/v1/courses.

If you have indeed done everything right, you will see a http response with body that includes:

[ {"id":1,"address":{"country":"U...

Great Job!

Swagger

To maximize interoperability and reach the widest audience possible, the Golfbert API exposes a Swagger (http://swagger.io) definition file. The Swagger file describes the types of assets that you can call, the parameters etc. Swagger provides code generations for most popular languages in order to reduce the time it takes to build your API client.

Swagger definition file

API Model

The API Model is self-explanatory, but might require some basic knowledge of the game of golf. There are endpoints available to list courses, get hole information for specific course, get teeboxes for each hole etc. Every asset that can be fetched individually has a unique id attached to it for easy retrieval later on. All APIs that return information stemming from unbounded sets (course list, for example) support paging using the marker and limit paradigm. See the Paging section below for more info.

A high level model of the API can be seen here:

Paging

Paging allows for quick retrieval of information in manageable chunks. Let's see how you can page the courses API.

Let's say your initial call is: https://api.golfbert.com/v1/courses. The result looks something like this:

[
  {
    "id": 1,
    "name": "Highland Park Golf Course",
  },
  {
    "id": 2,
    "name": "Shoal Creek Golf Club",
  },
  {
    "id": 3,
    "name": "Pebble Brook Golf Course",
  },

  …

  {
    "id": 9,
    "name": "Shark's Tooth Golf Club",
  },
  {
    "id": 10,
    "name": "Hoover Country Club",
  }
]

Here, as you can see, the API returns the first 10 courses available, each with a unique id attribute. The last one you encounter has id: 10 because the default page size is 10. To get the next 10 courses, you must call:

https://api.golfbert.com/v1/courses?marker=10

This tells the api to start returning courses from id 10, exclusive. The result will look like:

[
  {
    "id": 11,
    "name": "Oxmoor Valley Golf Course - Ridge",
  }
]

The last id you get is 19 (not shown here). Let's say you want to get the next page but actually shrink the page size. You can use the limit parameter like this: https://api.golfbert.com/v1/courses?marker=19&limit=5. The resulting set will start with course id 20 and end with 24. Both marker and limit parameters are optional but sometimes you must use them to receive information in small chunks.

Now you know how to page!

Rate Limits

Each account comes with rate limits (both daily and burst). Those are communicated when accounts are created and depend on tier of service purchased.

Deprecated API

There is nothing deprecated at this point but from time to time, certain endpoints might change or be removed. API releases will usually increment the /vN prefix but older APIs will stick around for a sufficient period of time so that customers can have adequate time to move off them.

Next: documentation