HCRA API Documentation (v1.0)

Overview

The HCRA API provides read-only JSON data endpoints for clubs, canoe classes, canoes, regattas, events, lanes, crews, and race results. All endpoints require a valid API key passed via the x-api-key header.

Endpoints

Each endpoint is available in two formats:

RESTful: /api/v1/[resource]/[optional_parameters]
Procedural: /api/v1/hcra_api.php?action=[action]&[parameters]

Available Actions

Validate a paddler
RESTful: /validate/PADDLER_ID
Procedural: ?action=validate&number=PADDLER_ID
Get associations
RESTful: /assocs
Procedural: ?action=assocs
Get clubs
RESTful: /clubs or /clubs/ASSOC_INITS
Procedural: ?action=clubs or ?action=clubs&assoc=ASSOC_INITS
Get canoe classes
RESTful: /classes
Procedural: ?action=classes
Get canoes for a club and class
RESTful: /canoes/club/CLUB_ID/class/CLASS_ID
Procedural: ?action=canoes&club_id=CLUB_ID&class_id=CLASS_ID
Get available years
RESTful: /years
Procedural: ?action=years
Get regattas
RESTful: /regattas/assoc/ASSOC or /regattas/assoc/ASSOC_INITS/year/YEAR
Procedural: ?action=regattas&assoc=ASSOC_INITS&year=YEAR
Get events for a regatta
RESTful: /regatta/REGATTA_ID/events
Procedural: ?action=events&regatta=REGATTA_ID
Get lanes for a race
RESTful: /lanes/race/RACE_ID optional /with_paddlers
Procedural: ?action=lanes&race=RACE_ID optional &with_paddlers=1
Get crew for a race entry
RESTful: /crews/CREW_ID
Procedural: ?action=crew&crew_id=CREW_ID
Get race results
RESTful: /results/race/RACE_ID
Procedural: ?action=results&race=RACE_ID
Get results updates
RESTful: /results/updates/REGATTA_ID optional filter ?after=EPOCH_TS
Procedural: ?action=result_updates&regatta=REGATTA_ID optional filter &after=EPOCH_TS

All requests must include a valid API key using the x-api-key HTTP header.

Validate Paddler

Reports whether a paddler, specified by HCRA number paddler_id, is valid to race, i.e. they have signed a waiver and their ID has been validated within the period specified by rule.

Request Example

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/paddlers/1394611/validation"

fetch("https://www.hcrapaddler.com/api/v1/paddlers/1394611/validation", {
  headers: { "x-api-key": "YOUR_API_KEY" }
})
.then(res => res.json())
.then(data => console.log(data));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/hcra_api.php?action=validate&paddler_id=1394611"


fetch("https://www.hcrapaddler.com/api/v1/hcra_api.php?action=validate&paddler_id=1394611", {
  headers: { "x-api-key": "YOUR_API_KEY" }
})
.then(res => res.json())
.then(data => console.log(data));

Response Example

{ "id": 1394611, "valid": "false" }

Get Associations

Retrieves a list of association IDs, their associated association shortnames and a logo file reference. Each class has an associated numeric assoc_id and a assoc_inits, which is used to filter results in endpoints such as getRegattas.

Request Example

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/assocs"

fetch("https://www.hcrapaddler.com/api/v1/assocs", {
  headers: { "x-api-key": "YOUR_API_KEY" }
})
.then(res => res.json())
.then(data => console.log(data));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/hcra_api.php?action=assocs"

fetch("https://www.hcrapaddler.com/api/v1/hcra_api.php?action=assocs", {
  headers: { "x-api-key": "YOUR_API_KEY" }
})
.then(res => res.json())
.then(data => console.log(data));

Response Example

[
  { "assoc_id": 0, "assoc_inits": "HCRA", "assoc_icon": "https://www.hcrapaddler.com/members/logos/hcra.gif" },
  { "assoc_id": 5, "assoc_inits": "HUI WA'A", "assoc_icon": "https://www.hcrapaddler.com/members/logos/assoc5.jpg" },
  { "assoc_id": 6, "assoc_inits": "KOA", "assoc_icon": "https://www.hcrapaddler.com/members/logos/assoc6.jpg" },
  { "assoc_id": 2, "assoc_inits": "MCHCA", "assoc_icon": "https://www.hcrapaddler.com/members/logos/assoc2.gif" },
  { "assoc_id": 3, "assoc_inits": "MCRA", "assoc_icon": "https://www.hcrapaddler.com/members/logos/assoc3.gif" },
  { "assoc_id": 1, "assoc_inits": "MOKU", "assoc_icon": "https://www.hcrapaddler.com/members/logos/assoc1.jpg" },
  { "assoc_id": 4, "assoc_inits": "OHCRA", "assoc_icon": "https://www.hcrapaddler.com/members/logos/assoc4.jpg" }
]

Get Clubs

Returns a list of all clubs with their name, association code, and unique club ID. A special "Private" entry is included with club_id 0.

Parameters

assoc (optional) — Filter results to a specific association using its initials (e.g., OHCRA).

Request Example

All Clubs (no association filter)

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/clubs"

fetch("https://www.hcrapaddler.com/api/v1/clubs", {
  headers: { "x-api-key": "YOUR_API_KEY" }
})
.then(res => res.json())
.then(data => console.log(data));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/hcra_api.php?action=clubs"

fetch("https://www.hcrapaddler.com/api/v1/hcra_api.php?action=clubs", {
  headers: { "x-api-key": "YOUR_API_KEY" }
})
.then(res => res.json())
.then(data => console.log(data));

Filtered by Association (e.g., MOKU)

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/clubs/MOKU"

fetch("https://www.hcrapaddler.com/api/v1/clubs/MOKU", {
  headers: { "x-api-key": "YOUR_API_KEY" }
})
.then(res => res.json())
.then(data => console.log(data));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/hcra_api.php?action=clubs&assoc=MOKU"

fetch("https://www.hcrapaddler.com/api/v1/hcra_api.php?action=clubs&assoc=MOKU", {
  headers: { "x-api-key": "YOUR_API_KEY" }
})
.then(res => res.json())
.then(data => console.log(data));

Response Example

[
  {
    "name": "Private",
    "assoc": "",
    "club_id": 0,
    "club_icon_file": "https://www.hcrapaddler.com/members/logos/private.png",
    "club_inits": "PRV"
  },
  {
    "name": "Hoemana",
    "assoc": "MOKU",
    "club_id": 84,
    "club_icon_file": "https://www.hcrapaddler.com/members/logos/club84.png",
    "club_inits": "HMN"
  },
  {
    "name": "Hui Wa?a ?O Waiakea",
    "assoc": "MOKU",
    "club_id": 13,
    "club_icon_file": "https://www.hcrapaddler.com/members/logos/club13.jpg",
    "club_inits": "HWW"
  }
]

Get Canoe Classes

Retrieves a list of valid canoe class identifiers. Each class has an associated numeric id and a name, which are used to filter results in endpoints such as getCanoes.

Request Example

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/canoes/classes"

fetch("https://www.hcrapaddler.com/api/v1/canoes/classes", {
  headers: { "x-api-key": "YOUR_API_KEY" }
})
.then(res => res.json())
.then(data => console.log(data));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/hcra_api.php?action=classes"

fetch("https://www.hcrapaddler.com/api/v1/hcra_api.php?action=classes", {
  headers: { "x-api-key": "YOUR_API_KEY" }
})
.then(res => res.json())
.then(data => console.log(data));

Response Example

[
  { "id": 1, "name": "KOA" },
  { "id": 2, "name": "non-Traditional" },
  { "id": 3, "name": "Traditional" },
  { "id": 4, "name": "Unlimited" }
]

Get Canoes

Returns a list of canoes for a given club and canoe class. Each canoe includes name, class, type, hull and gunnel colors, and a boolean flag indicating if it was weighed in the current year.

Parameters

club_id (required) — Club ID as returned by getClubs
class_id (required) — Class ID from your canoe class selector

Request Example

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/canoes/club/CLUB_ID/class/CLASS_ID"

fetch("https://www.hcrapaddler.com/api/v1/canoes/club/CLUB_ID/class/CLASS_ID", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/hcra_api.php?action=canoes&club_id=1&class_id=1"

fetch("https://www.hcrapaddler.com/api/v1/hcra_api.php?action=canoes&club_id=1&class_id=1", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data));

Response Example

[
  {
    "name": "Makani Kai",
    "class": "KOA",
    "type": "Handbuilt",
    "hull": "Koa",
    "gunnel": "Koa",
    "valid": 1
  },
  {
    "name": "Lele Wa'a",
    "class": "KOA",
    "type": "Handbuilt",
    "hull": "Koa",
    "gunnel": "Koa",
    "valid": 1
  }
]

Get Available Years

Retrieve all years for which regattas exist in the database.

Request Example

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/regattas/years"

fetch("https://www.hcrapaddler.com/api/v1/regattas/years", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/hcra_api.php?action=years"

fetch("https://www.hcrapaddler.com/api/v1/hcra_api.php?action=years", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
  .then(res => res.json())
  .then(data => console.log(data));

Response Example

[2005, 2006, 2007, 2024, 2025]

Get Regattas

Returns a list of regattas for a given association and optional year.

Parameters

assoc (required) — Association code (e.g., HCRA)
year (optional) — Four-digit year (e.g., 2025)

Request Examples

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/regattas/assoc/ASSOC_INITS/year/YEAR"

fetch("https://www.hcrapaddler.com/api/v1/regattas/assoc/ASSOC_INITS/year/YEAR", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("Error:", err));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/hcra_api.php?action=regattas&assoc=HCRA&year=2007"

fetch("https://www.hcrapaddler.com/api/v1/hcra_api.php?action=regattas&assoc=HCRA&year=2007", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("Error:", err));

Response Example

[
  {
    "reg_id": 45,
    "reg_name": "HCRA STATE CHAMPIONSHIP"
  }
]

Get Events

Retrieve the list of events for a specified regatta.

Parameters

regatta (required) — Regatta ID (e.g., 45)

Request Examples

https://hcrapaddler.com/api/v1/regattas/REG_ID/events

fetch("https://hcrapaddler.com/api/v1/regattas/REG_ID/events", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("Error:", err));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/hcra_api.php?action=events&regatta=45"

fetch("https://www.hcrapaddler.com/api/v1/hcra_api.php?action=events&regatta=45", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("Error:", err));

Response Example

[
  {
    "race_order": 1,
    "race_name": "Girls 12",
    "race_id": 3578
  },
  {
    "race_order": 2,
    "race_name": "Boys 12",
    "race_id": 3579
  }
]

Get Lanes

Retrieves the lane assignments for a given race, including each crew's lane number, association, club name, and club logo. This endpoint is often used to build the start list or race bracket for a given event.

Optionally, you can include a list of paddler names for each crew by passing with_paddlers=1 in the request. This makes it easy to show full crew rosters alongside lane assignments in a single call.

Parameters

race (required) — Race ID (e.g., 3613)
with_paddlers (optional) — flag: 1/0

Request Examples

Without Paddlers

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://hcrapaddler.com/api/v1/races/RACE_ID/lanes"

fetch("https://hcrapaddler.com/api/v1/races/RACE_ID/lanes", {
  headers: { "x-api-key": "YOUR_API_KEY" }
})
.then(res => res.json())
.then(data => console.log(data));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://www.hcrapaddler.com/api/v1/hcra_api.php?action=lanes&race=3613"

fetch("https://www.hcrapaddler.com/api/v1/hcra_api.php?action=lanes&race=3613", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data));

With Paddlers

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://hcrapaddler.com/api/v1/races/RACE_ID/lanes/with-paddlers"

fetch("https://hcrapaddler.com/api/v1/races/RACE_ID/lanes/with-paddlers", {
  headers: { "x-api-key": "YOUR_API_KEY" }
})
.then(res => res.json())
.then(data => console.log(data));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://hcrapaddler.com/api/v1/hcra_api.php?action=lanes&race=3613&with_paddlers=1"

fetch("https://www.hcrapaddler.com/api/v1/hcra_api.php?action=lanes&race=3613&with_paddlers=1", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data));

Response Example

Without Paddlers (default)

{
  "event_number": 36,
  "event_name": "Mixed (40)",
  "entries": [
    {
      "crew_id": 24794,
      "lane": 1,
      "association": "MOKU",
      "club": "Keauhou Canoe Club",
      "club_icon_file": "https://www.hcrapaddler.com/members/logos/club1.jpg"
    },
    {
      "crew_id": 24795,
      "lane": 2,
      "association": "HUI WA'A",
      "club": "Manu O Ke Kai",
      "club_icon_file": "https://www.hcrapaddler.com/members/logos/club48.jpg"
    }
  ]
}

With Paddlers

{
  "event_number": 36,
  "event_name": "Mixed (40)",
  "entries": [
    {
      "crew_id": 24794,
      "lane": 1,
      "association": "MOKU",
      "club": "Keauhou Canoe Club",
      "club_icon_file": "https://www.hcrapaddler.com/members/logos/club1.jpg",
      "paddlers": [
        "Jonathan Grayson",
        "Mel Pauole",
        "Leslie Crawford",
        "Jane Dulaney",
        "Joreen Knox",
        "Duane Webster"
      ]
    },
    {
      "crew_id": 24795,
      "lane": 2,
      "association": "MCH",
      "club": "Hawaiian Canoe Club",
      "club_icon_file": "https://www.hcrapaddler.com/members/logos/club2.jpg",
      "paddlers": [
        "Mele Kalama",
        "Kimo Kekoa",
        "Kainoa Alika",
        "Nanea Wright",
        "Noa Kai",
        "Alana Ho"
      ]
    }
  ]
}

Get Crew

Retrieve the names of paddlers in a specific crew.

Parameters

crew_id (required) — Crew ID (e.g., 24794)

Request Examples

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://hcrapaddler.com/api/v1/crews/CREW_ID"

fetch("https://hcrapaddler.com/api/v1/crews/CREW_ID", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("Error:", err));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://hcrapaddler.com/api/v1/hcra_api.php?action=crew&crew_id=24794"

fetch("https://hcrapaddler.com/api/v1/hcra_api.php?action=crew&crew_id=24794", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("Error:", err));

Response Example

[
  "Jonathan Grayson",
  "Mel Pauole",
  "Leslie Crawford",
  "Jane Dulaney",
  "Joreen Knox",
  "Duane Webster"
]

Get Results

Retrieve race results including placements, times, and crew information.

Parameters

race (required) — Race ID (e.g., 3613)

Request Examples

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://hcrapaddler.com/api/v1/races/RACE_ID/results"

fetch("https://hcrapaddler.com/api/v1/races/RACE_ID/results", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("Error:", err));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://hcrapaddler.com/api/v1/hcra_api.php?action=results&race=3613"

fetch("https://hcrapaddler.com/api/v1/hcra_api.php?action=results&race=3613", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("Error:", err));

Response Example

[
  {
    "crew_id": 24794,
    "place": 1,
    "club": "Keauhou Canoe Club",
    "time": "3:50.49",
    "points": 15,
    "paddlers": [
      "Jonathan Grayson",
      "Mel Pauole",
      "Leslie Crawford",
      "Jane Dulaney",
      "Joreen Knox",
      "Duane Webster"
    ]
  },
  {
    "crew_id": 24797,
    "place": 2,
    "club": "Hawaiian Canoe Club",
    "time": "3:59.90",
    "points": 13
  }
]

Get Updates

Retrieve results updates potentially based on the client epoch timestamp.

Parameters

after (optional) — epoch timestamp (e.g., 1723051234)

Request Examples

Without after epoch timestamp filter

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://hcrapaddler.com/api/v1/results/updates/REGATTA_ID"

fetch("https://hcrapaddler.com/api/v1/results/updates/REGATTA_ID", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("Error:", err));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://hcrapaddler.com/api/v1/hcra_api.php?action=result_updates&regatta=45"

fetch("https://hcrapaddler.com/api/v1/hcra_api.php?action=result_updates&regatta=45", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("Error:", err));

With after epoch timestamp filter

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://hcrapaddler.com/api/v1/results/updates/REGATTA_ID?after=EPOCH_TS"

fetch("https://hcrapaddler.com/api/v1/results/updates/REGATTA_ID?after=EPOCH_TS", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("Error:", err));

curl --ssl-no-revoke -H "x-api-key: YOUR_API_KEY" "https://hcrapaddler.com/api/v1/hcra_api.php?action=result_updates&regatta=REGATTA_ID&after=EPOCH_TS"

fetch("https://hcrapaddler.com/api/v1/hcra_api.php?action=result_updates&regatta=REGATTA_ID&after=EPOCH_TS", {
  headers: {
    "x-api-key": "YOUR_API_KEY"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error("Error:", err));

Response Example

Without after epoch timestamp filter

[
  { "race_id": 75257, "updated": 1754158232 },
  { "race_id": 75258, "updated": 1754199022 },
  ...
  { "race_id": 75301, "updated": 1754193895 }
]

With after epoch timestamp filter

[
  { "race_id": 75300, "updated": 1754193039 },
  { "race_id": 75301, "updated": 1754193895 }
]

Test Bench

This TestBench exercises the functionality described above. The javascript codeblock that is used to load the JSON is included after the Response Output and can be copied freely.

Generate API Key

To access the API, you must provide a valid email address. Your key will be linked to your account, and you may request revocation or regeneration at any time. Use the form below to generate your own unique test key. This test key will be limited to 500 calls per day and 10 calls per minute. Once you are ready to go into production contact dev@hcrapaddler.com to increase your usage limits.

Use Case: Google Sheets Integration

The HCRA API can be used directly inside a live Google Spreadsheet to retrieve and interact with real-time race, club, and crew data. We've created a showcase demo here:

🔗 Google Sheets API Demo

To use the spreadsheet fully and customize it with your own inputs or club data, you need to make your own copy. This allows all built-in functions (like =getRaces() and =getResults(raceId)) to execute properly under your account.

📋 How to Make Your Own Copy

Open the spreadsheet link above.
From the menu, click File > Make a copy…
Give your new copy a name and choose a destination in your Google Drive.
Click OK to create your personal copy.

Your copy will include all the custom functions powered by the HCRA API, and you’ll be able to edit input fields, call data, and build custom views or dashboards.

Note: If you get a #NAME? error when using the demo, it means you're viewing the spreadsheet in read-only mode. Only copied or owned versions can run the script functions.

Contents

HCRA API Documentation (v1.0)

Overview

Endpoints

Available Actions

Validate Paddler

Request Example

Response Example

Get Associations

Request Example

Response Example

Get Clubs

Parameters

Request Example

All Clubs (no association filter)

Filtered by Association (e.g., MOKU)

Response Example

Get Canoe Classes

Request Example

Response Example

Get Canoes

Parameters

Request Example

Response Example

Get Available Years

Request Example

Response Example

Get Regattas

Parameters

Request Examples

Response Example

Get Events

Parameters

Request Examples

Response Example

Get Lanes

Parameters

Request Examples

Without Paddlers

With Paddlers

Response Example

Without Paddlers (default)

With Paddlers

Get Crew

Parameters

Request Examples

Response Example

Get Results

Parameters

Request Examples

Response Example

Get Updates

Parameters

Request Examples

Without after epoch timestamp filter

With after epoch timestamp filter

Response Example

Without after epoch timestamp filter

With after epoch timestamp filter

Test Bench

Generate API Key

Use Case: Google Sheets Integration

📋 How to Make Your Own Copy