Sign inGet API key Console
3 min read

Handle missing golf club specs in API responses

A missing field, a false value and a field you did not request are three different states. Keep them apart in code, in filters and in agent instructions.

An open space in a grid of specifications makes an unknown value visible.

In code, a missing field and a false field are easy to mix up, and they mean different things. There are three cases, and an app that treats them as one shows golfers wrong facts.

Three states of a driver specification

  • Not published. The field is absent from a record you requested in full. The catalog has no reviewed value for it. This does not mean the club lacks the feature.
  • Published false or 0. The field is present with that value. adjustable_hosel: false states that the hosel does not adjust.
  • Not requested. You sent fields=id,name, so every other field is absent. This says nothing about the catalog.

Label a driver's hosel from adjustable_hosel

Check for the field before reading its value, and keep the projection next to the code that reads it:

JavaScript
// club comes from GET /drivers/{id} without fields=, or with adjustable_hosel in fields=
function hoselLabel(club) {
  if (!('adjustable_hosel' in club)) return 'Not published';
  return club.adjustable_hosel ? 'Adjustable' : 'Fixed';
}

A check such as if (!club.adjustable_hosel) labels a Not published hosel as Fixed.

A filter returns only drivers with a published value

The catalog had 462 drivers on 3 November 2026. adjustable_hosel was true for 291, false for 54, and Not published for the other 117. A filter on the field matches published values only:

Shell
curl 'https://api.golfapi.dev/drivers?adjustable_hosel=false&fields=id,name&limit=100' \
  -H "Authorization: Bearer $GOLFDEV_API_KEY"

Run export GOLFDEV_API_KEY='sk_test_…' with your key in the same terminal first. Leave $GOLFDEV_API_KEY as written; the shell replaces it with your key. How to set your key

That request, with a live key, returns 54 drivers. The 117 drivers with no published hosel value are in neither the true nor the false result. Which drivers have a fixed hosel breaks these counts down by release year.

Read field coverage from /coverage before designing a screen

GET /coverage counts how many records carry each field. Use it to decide whether a column or filter is worth building:

Shell
curl 'https://api.golfapi.dev/coverage' \
  -H "Authorization: Bearer $GOLFDEV_API_KEY"

Driver counts with a live key on 3 November 2026, cut to six fields:

JSON
{
  "build": "bld_01M6F0VDZH8HGAJAG815AJAGQC",
  "published_at": "2026-11-02T20:59:00Z",
  "resources": [
    {
      "resource": "drivers",
      "records": 462,
      "fields": {
        "released": 371,
        "lofts_deg": 407,
        "variants": 407,
        "adjustable_hosel": 345,
        "volume_cc": 414,
        "intro_price": 373
      }
    }
  ]
}

intro_price is counted only for a key with the market entitlement. A test key's /coverage describes the fixed test sample.

Give an agent the same three states

When an agent reads the API through a tool, pass records through as returned, and tell it what an absent field means:

text
A field missing from a GolfAPI.dev record is Not published: say it is unknown.
Do not take the value from another driver, another hand or another model.
false and 0 are published values. A field outside the fields= list was not requested.

The MCP server gives connected assistants the same rule on every plan. Its instructions say: "A field missing from a document has no published value. Do not fill it from another club, hand or loft. A 0 or false is a real value." Ask Claude about golf club specs shows how to connect it.

More posts

All posts