FR: Integrate Hammerhead (Karoo) like Strava (yes, there is an API)

[jottojott]

Hello Martin!
I recently switched my bike-computer to a Hammerhead Karoo 3. Not only did I find a well made webportal there, they also have a quite well documented API under

https://api.hammerhead.io/v1/docs

Maybe it is possible to integrate that into GAP like Strava, so that rides can be automatically fetched and one does no longer need Strava as hub for that (as I do now)?

Thank you very much!

[martin-ueding]

Yes, the API seems very sensible. They offer paginated access to the activities and also access to the FIT files underneath. Integrating this would be possible.

As I don't have such a device and am not a user of their platform, I couldn't really test it, though. So I think that there are two options that we could try this:

1. You create an implementation, possibly aided by AI (like Claude Code, OpenAI Codex or Google Antigravity). Then you can directly run and test until it works.
2. I use AI to create an implementation for that, though it might have some issues. Then I'll release that, you test, report bugs and we iterate on that.

Would you be up to trying it yourself or shall I eventually produce some draft version?

[jottojott]

Ah, the second option :-)
Note that I just recieved the device, so do your take time: I must get familiar with that first and then find the chance to take it for it spin (there are severe thunderstorms announced this WE).

[martin-ueding]

I've let the AI implement something. It is released as 1.29.0. I haven't tested it. I guess you will need to register your own API app in order to get some IDs there. Please have a look, I would essentially forward your feedback to the AI and then we can improve it.

[jottojott]

Ahm, am I missing something out or do I really need to contact hammerhead for client ID & secret? There is no online-function to get these at the web portal (only for some certain services), and there is no such function linked at the API-docs, right?

[martin-ueding]

The following content is AI generated (Claude Sonnet 4.6).

Yes, you do need to register an OAuth developer application — but it is self-service, no need to email Hammerhead. Here are the steps:

1. Create a developer account at dashboard.hammerhead.io/create.
2. Enable developer settings, fill in the app name and description, upload an SVG logo, and accept the API Licensing agreement.
3. After accepting the agreement an API settings tab appears in your dashboard — your Client ID and Client Secret are listed there.
4. Set the redirect URI in that app to the callback URL shown on the GAP Hammerhead settings page.

The settings page instructions in GAP have been updated in the next release to walk you through exactly this. Let me know if you run into any issues once you have the credentials!

[jottojott]

No, this failed.
First, creating a developer account is far different, see this link:
https://support.hammerhead.io/hc/en-us/articles/43558376710683-Creating-a-Developer-Account

Then the trouble starts: One must upload a logo, it must be SVG, and it must be smaller than 1 MB. I did all this and fill out the form:

However, the webhook-URL is "not approved" :-/

Have you tried to sign in to hammerhead account yourself? Maybe you do not need any hardware to do so. I created my account before I bought the Karoo (but yes, I used my SRAM-ID for this).

[jottojott]

After updating GAP I tried again to connect to Hammerhead. From Hammerhead's side it seemed to work, as "connected" is displayed there, GAP however shows an error, possibly because I (not really knowing what to do) have misconfigured it ...

GAP-Output:

AttributeError: 'HammerheadLoginHelper' object has no attribute '_hammerhead_client_id'
2026-06-10 09:17:37 geo_activity_playground.webui.app ERROR Exception on /settings/hammerhead-callback [GET]
Traceback (most recent call last):
  File "/home/jochen/.local/share/pipx/venvs/geo-activity-playground/lib/python3.13/site-packages/flask/app.py", line 1511, in wsgi_app
    response = self.full_dispatch_request()
  File "/home/jochen/.local/share/pipx/venvs/geo-activity-playground/lib/python3.13/site-packages/flask/app.py", line 919, in full_dispatch_request
    rv = self.handle_user_exception(e)
  File "/home/jochen/.local/share/pipx/venvs/geo-activity-playground/lib/python3.13/site-packages/flask/app.py", line 917, in full_dispatch_request
    rv = self.dispatch_request()
  File "/home/jochen/.local/share/pipx/venvs/geo-activity-playground/lib/python3.13/site-packages/flask/app.py", line 902, in dispatch_request
    return self.ensure_sync(self.view_functions[rule.endpoint])(**view_args)  # type: ignore[no-any-return]
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
  File "/home/jochen/.local/share/pipx/venvs/geo-activity-playground/lib/python3.13/site-packages/geo_activity_playground/webui/authenticator.py", line 37, in wrapped_route
    return route(*args, **kwargs)
  File "/home/jochen/.local/share/pipx/venvs/geo-activity-playground/lib/python3.13/site-packages/geo_activity_playground/webui/blueprints/settings_blueprint.py", line 1017, in hammerhead_callback
    hammerhead_login_helper.save_hammerhead_code(code)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^
  File "/home/jochen/.local/share/pipx/venvs/geo-activity-playground/lib/python3.13/site-packages/geo_activity_playground/webui/blueprints/settings_blueprint.py", line 1221, in save_hammerhead_code
    self._config_accessor().hammerhead_client_id = self._hammerhead_client_id
                                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'HammerheadLoginHelper' object has no attribute '_hammerhead_client_id