Hol deine Zahlen mit der API

Basis-URL

Alle Endpoints hängen unter einem Host. Antworten sind JSON.

https://api.geony.ai

Authentifizierung

Du erstellst einen API-Schlüssel in den Organisationseinstellungen in der App (nur ein Organisationsadministrator kann das). Den vollständigen Schlüssel siehst du genau einmal, also bewahr ihn gut auf; verlierst du ihn, erstellst du einen neuen. Schlüssel beginnen mit geony_ sodass ein geleakter Schlüssel für Secret-Scanner erkennbar ist.

Schick den Schlüssel als Bearer-Token im Authorization-Header mit:

Authorization: Bearer geony_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Der Schlüssel ist strikt schreibgeschützt: jede andere Methode als GET gibt einen 403 zurück. Die Daten sind auf die Organisation des Schlüssels begrenzt; ein auf einen Arbeitsbereich begrenzter Schlüssel sieht nur seine eigenen Arbeitsbereiche.

Eine erste Anfrage

Beginn bei deinen Arbeitsbereichen; daraus holst du die IDs, die die anderen Endpoints brauchen.

curl https://api.geony.ai/v1/workspaces \
  -H "Authorization: Bearer $GEONY_API_KEY"

Beispielantwort:

[
  {
    "id": "ws_3f2a…",
    "name": "Acme Nederland",
    "slug": "acme-nederland"
  }
]

Kern-Endpoints

Beispiel: Projekte in einem Arbeitsbereich

curl https://api.geony.ai/v1/workspaces/ws_3f2a.../projects \
  -H "Authorization: Bearer $GEONY_API_KEY"

Beispielantwort:

[
  {
    "id": "prj_9b1c…",
    "name": "Acme.nl",
    "domain": "acme.nl",
    "archivedAt": null,
    "visibilityScoreBp": 3600,
    "lastRunAt": "2026-08-01T06:00:00.000Z"
  }
]

Felder, die enden auf Bp sind Basispunkte: 3600 bedeutet 36%. So bleiben Prozentsätze ganze Zahlen, ohne Rundungsfehler.

Beispiel: die Sichtbarkeitsübersicht

Mit dem optionalen Parameter period (day, week oder month) wählst du die Aggregation.

curl "https://api.geony.ai/v1/projects/prj_9b1c.../overview?period=week" \
  -H "Authorization: Bearer $GEONY_API_KEY"

Beispielantwort:

{
  "periodStart": "2026-07-27T00:00:00.000Z",
  "entities": [
    {
      "entityId": "ent_1a2b…",
      "entityName": "Acme",
      "entityType": "brand",
      "isPrimary": true,
      "observationsN": 180,
      "presentN": 65,
      "presenceRateBp": 3600,
      "presenceCiLowBp": 2600,
      "presenceCiHighBp": 4700,
      "visibilityScoreBp": 3400,
      "sovBp": 2800,
      "citationShareBp": 1500
    }
  ]
}

Die Felder presenceCiLowBp und presenceCiHighBp sind die Unter- und Obergrenze des 95%-Konfidenzintervalls, ebenfalls in Basispunkten. Aus dem Beispiel: 36% sichtbar, Intervall 26 bis 47%.

Weitere read-only Endpoints

Unter demselben Authentifizierungs- und Mandantenmodell sind auch diese GETs verfügbar. Sie arbeiten auf denselben Projekten:

MCP-Server für KI-Assistenten

Dieselben read-only Daten sind auch als MCP-Server (Model Context Protocol) verfügbar, sodass ein KI-Assistent wie Claude, Cursor oder ChatGPT deine Messdaten direkt abfragen kann, ohne dass du selbst Skripte schreibst. Der Server ist eine dünne, schreibgeschützte Schicht über dieser API und nutzt denselben geony_ Schlüssel.

Er bietet Werkzeuge für deine Arbeitsbereiche und Projekte, und pro Projekt für die Sichtbarkeitsübersicht, die Fragen, die Quellen, die zitierten Seiten, Sentiment, die Aufgabenliste, Meldungen, den Trend und die AI Readiness. Das Verbinden geht über zwei Umgebungsvariablen:

{
  "mcpServers": {
    "geony": {
      "command": "geony-mcp",
      "env": {
        "GEONY_API_BASE": "https://api.geony.ai",
        "GEONY_API_KEY": "geony_..."
      }
    }
  }
}

Weil der Schlüssel schreibgeschützt ist, kann der Assistent nichts ändern: er fragt die Daten ab und denkt darüber nach. Beta beim Bureau- und Enterprise-Tarif, genau wie die API.

Fehler

Die API verwendet gewöhnliche HTTP-Statuscodes und eine kompakte Fehlerform.

{ "error": "forbidden" }