API quickstart

This takes about five minutes. You need to be the account owner, on Pro or above.

1. Create a key

   Open Settings and find API keys. Press Create key and fill in:

   • Name: something you will recognise later, such as the tool that uses it.
   • Brands: every brand, including ones added later, or only the ones you tick.
   • Expires: 30, 90, and 365 days, or never.

   The key is shown once. Copy it, tick I've saved this key somewhere safe and press Done. Ranqo keeps only a fingerprint of the key and cannot show it again.

2. Keep it out of your code

   Store the key where your tool reads secrets, not in source control. The examples below read it from an environment variable:

   Shell

   export RANQO_API_KEY="paste-your-key-here"

3. Make your first request

   Ask for the account the key belongs to. A working key answers with your plan, its rate limit and the key's own details:

   curlPythonJavaScript

   curl https://api.ranqo.ai/v1/account \
     -H "Authorization: Bearer $RANQO_API_KEY"

   import os, requests
   
   response = requests.get(
       "https://api.ranqo.ai/v1/account",
       headers={"Authorization": f"Bearer {os.environ['RANQO_API_KEY']}"},
   )
   print(response.json())

   const response = await fetch("https://api.ranqo.ai/v1/account", {
     headers: { Authorization: `Bearer ${process.env.RANQO_API_KEY}` },
   });
   console.log(await response.json());

4. Find your brand's id

   List the brands the key can read. Each one carries its id, which every brand endpoint takes in its path:

   curl

   curl https://api.ranqo.ai/v1/brands \
     -H "Authorization: Bearer $RANQO_API_KEY"

5. Read its visibility

   Ask for the last 30 days, with day boundaries in your own time zone:

   curl

   curl "https://api.ranqo.ai/v1/brands/BRAND_ID/visibility?period=30d&tz=Europe/Berlin" \
     -H "Authorization: Bearer $RANQO_API_KEY"

   The answer holds visibility, share of voice, average position and sentiment, each as its current value, its previous value over the window before and the change between them. A value is null when there was nothing to measure, never a made-up zero.

Next#