Haal je cijfers op met de API

Basis-URL

Alle endpoints hangen onder één host. Antwoorden zijn JSON.

https://api.geony.ai

Authenticatie

Je maakt een API-sleutel aan bij de organisatie-instellingen in de app (alleen een organisatiebeheerder kan dat). De volledige sleutel zie je precies één keer, dus bewaar hem goed; raak je hem kwijt, dan maak je een nieuwe. Sleutels beginnen met geony_ zodat een gelekte sleutel herkenbaar is voor secretscanners.

Stuur de sleutel mee als Bearer-token in de Authorization-header:

Authorization: Bearer geony_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

De sleutel is strikt alleen-lezen: elke andere methode dan GET geeft een 403. De data is begrensd tot de organisatie van de sleutel; een werkruimte-begrensde sleutel ziet alleen zijn eigen werkruimtes.

Een eerste verzoek

Begin bij je werkruimtes; daaruit haal je de id's die de andere endpoints nodig hebben.

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

Voorbeeldantwoord:

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

Kernendpoints

Voorbeeld: projecten in een werkruimte

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

Voorbeeldantwoord:

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

Velden die eindigen op Bp zijn basispunten: 3600 betekent 36%. Zo blijven percentages hele getallen, zonder afrondingsfouten.

Voorbeeld: het zichtbaarheidsoverzicht

Met de optionele parameter period (day, week of month) kies je de aggregatie.

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

Voorbeeldantwoord:

{
  "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
    }
  ]
}

De velden presenceCiLowBp en presenceCiHighBp zijn de onder- en bovengrens van het 95%-betrouwbaarheidsinterval, ook in basispunten. Uit het voorbeeld: 36% zichtbaar, interval 26 tot 47%.

Meer read-only endpoints

Onder hetzelfde authenticatie- en tenantmodel zijn ook deze GET's beschikbaar. Ze werken op dezelfde projecten:

MCP-server voor AI-assistenten

Dezelfde read-only data is ook beschikbaar als MCP-server (Model Context Protocol), zodat een AI-assistent als Claude, Cursor of ChatGPT je meetdata rechtstreeks kan opvragen zonder dat je zelf scripts schrijft. De server is een dunne, alleen-lezen laag over deze API en gebruikt dezelfde geony_-sleutel.

Hij biedt tools voor je werkruimtes en projecten, en per project voor het zichtbaarheidsoverzicht, de vragen, de bronnen, de geciteerde pagina's, sentiment, de werklijst, meldingen, de trend en de AI Readiness. Koppelen gaat via twee omgevingsvariabelen:

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

Omdat de sleutel alleen-lezen is, kan de assistent niets wijzigen: hij bevraagt de data en redeneert erover. Beta op het Bureau- en Enterprise-plan, net als de API.

Fouten

De API gebruikt gewone HTTP-statuscodes en een compacte foutvorm.

{ "error": "forbidden" }