Bwendi Context API

x-api-key: YOUR_API_KEY

Examples

curl https://api.bwendi.com/context/CM/3.8667/11.5167 \
  -H "x-api-key: YOUR_API_KEY"

fetch('https://api.bwendi.com/context/CM/3.8667/11.5167', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
})

Tip: click Test on any endpoint page to pre-fill and auto-send.

Full geographic context for a coordinate. Returns the named place, admin region, nearby markets, country info, and more.

Parameters

Query options

Example request

GET /context/CM/3.8667/11.5167

Example response

{
  "hubs": [
    {
      "name": "Yaoundé",
      "type": "city",
      "context": "574m SW of Yaoundé"
    }
  ],
  "hotspot": {
    "name": "CCA Marché central",
    "type": "bank",
    "context": "11m E of CCA Marché central"
  },
  "metro": {
    "name": "Yaoundé",
    "type": "city",
    "context": "574m SW of Yaoundé"
  },
  "nearby": [
    {
      "name": "CCA Marché central",
      "type": "bank",
      "context": "11m E of CCA Marché central"
    },
    {
      "name": "Agence de Régulation des Télécommunications",
      "type": "government",
      "context": "85m NE of Agence de Régulation des Télécommunications"
    }
  ],
  "name": "Pharmacie du Soleil",
  "ascii_name": "Pharmacie du Soleil",
  "lat": 3.8671,
  "lng": 11.51714,
  "type": "pharmacy",
  "within": {
    "name": "Centre Commercial",
    "label": "Chefferie",
    "type": "quarter",
    "level": 10,
    "within": {
      "name": "Yaoundé I",
      "label": "Arrondissement",
      "type": "district",
      "level": 8,
      "within": {
        "name": "Communauté urbaine de Yaoundé",
        "label": "Communauté Urbaine",
        "type": "council",
        "level": 7,
        "within": {
          "name": "Mfoundi",
          "label": "Département",
          "type": "department",
          "level": 6,
          "within": {
            "name": "Centre",
            "label": "Région",
            "type": "region",
            "level": 4
          }
        }
      }
    }
  },
  "dem": 734,
  "anchors": {
    "immediate": ["mall", "marketplace", "supermarket", "pharmacy"],
    "local": ["city"],
    "reachable": ["town"]
  },
  "context": "Dans l'orbite commerciale principale de Yaoundé. Accès immédiat à centre commercial, marché, supermarché et pharmacie.",
  "country": {
    "name": "Cameroon",
    "localName": "Cameroun",
    "code": "CM",
    "callingCode": "237",
    "flag": "🇨🇲",
    "lang": "fr",
    "currency": {
      "symbol": "F",
      "code": "XAF",
      "name": "CFA",
      "localName": "FCFA"
    }
  }
}

Fuzzy place-name search within a country. Results ranked by population — great for autocomplete inputs.

Parameters

Example request

GET /search/CM?q=Douala

Example response

{
  "country_code": "CM",
  "query": "Douala",
  "count": 3,
  "results": [
    {
      "name": "Douala", "type": "city",
      "lat": 4.0483, "lng": 9.7043,
      "population": 2768400,
      "economic_tier": "dominant",
      "within": "Littoral"
    }
  ]
}

List all markets at or above an economic tier for a country. Use hubs as the tier to get the top market hubs by gravity (80/20 rule).

Parameters

Example request

GET /markets/prime/CM

Example response

{
  "tier": "prime",
  "country_code": "CM",
  "count": 8,
  "markets": [
    { "name": "Douala", "type": "city", "lat": 4.0483, "lng": 9.7043,
      "population": 2768400, "economic_tier": "dominant", "market_score": 11.5 }
  ]
}

Country info — no backend round-trip. Resolves from three sources:

Example response

{
  "name": "Cameroon",
  "localName": "Cameroun",
  "code": "CM",
  "callingCode": "+237",
  "flag": "🇨🇲",
  "lang": "fr",
  "currency": { "symbol": "FCFA", "code": "XAF", "name": "Central African CFA Franc" }
}

Send a question about a location. We resolve the full context first, then pass it to Gemini for a grounded answer. Great for analysis, reports, or smart location descriptions.

Parameters

Request body

Example request

POST /interpret/CM/3.8667/11.5167
Content-Type: application/json

{ "prompt": "What is the commercial potential?" }

AI response field

"ai": {
  "prompt": "What is the commercial potential?",
  "response": "Yaoundé is Cameroon's political capital (pop. 2.8M). The dominant tier indicates strong commercial integration. Douala, the economic hub, is 194km SW..."
}

Device location verification using solar shadow analysis. Upload a capture and challenge data — we compute the expected sun position, analyse the visual evidence, and return a pass, fail, or inconclusive verdict on whether the device was actually at the claimed GPS location.

Request body (multipart/form-data)

Example request

curl -X POST https://api.bwendi.com/verify \
  -H "x-api-key: YOUR_KEY" \
  -F "image=@shadow.jpg" \
  -F "challengeId=550e8400-e29b-41d4-a716-446655440000" \
  -F "claimedLat=4.05" \
  -F "claimedLng=9.7" \
  -F "issuedAt=2026-03-22T12:34:56Z" \
  -F "signature=abc123..."

Example response

{
  "challengeId": "550e8400-e29b-41d4-a716-446655440000",
  "verdict": "pass",
  "solarElevation": 86.2,
  "solarAzimuth": 175.3,
  "geminiAssessment": {
    "shadows_visible": "yes",
    "shadow_length": "short",
    "shadow_direction_consistent": true,
    "outdoor_natural_light": true,
    "artificial_light_signs": {
      "detected": false,
      "indicators": []
    },
    "signs_of_manipulation": false,
    "confidence": 0.85,
    "notes": "Very short shadows consistent with near-overhead sun."
  }
}

Verdicts

Error responses

Turnkey Flow

Don't want to build the capture flow yourself? Use the turnkey flow — create a challenge, redirect users to verify.bwendi.com, and poll for the result. The hosted flow currently costs 400 credits, which is as little as 18 cents USD on the Star plan.

Step 1 — Create challenge

Example response

{
  "challengeId": "550e8400-e29b-41d4-a716-446655440000",
  "verifyUrl": "https://verify.bwendi.com/c/550e8400-e29b-41d4-a716-446655440000",
  "issuedAt": "2026-03-22T12:34:56.000Z",
  "expiresAt": "2026-03-22T12:36:26.000Z"
}

Step 2 — Redirect user

Send your user to the verifyUrl. Append ?callback=https://yourapp.com/done to redirect back after verification.

Or embed it: <iframe src="https://verify.bwendi.com/c/UUID">

Step 3 — Poll for result

Example response (pending)

{ "challengeId": "550e8400...", "status": "pending" }

Example response (complete)

{
  "challengeId": "550e8400-e29b-41d4-a716-446655440000",
  "verdict": "pass",
  "solarElevation": 86.2,
  "solarAzimuth": 175.3,
  "frames": 3,
  "frameVerdicts": ["pass", "pass", "pass"]
}

Returns the top-N places near a coordinate, ranked by gravity score. Country code is auto-resolved from the coordinate by the gateway — no CC param needed. Searches a ~33 km radius (3×3 big-zone grid) by default.

Path parameters

Query options

Example request

GET /hotspots/3.8667/11.5167/places/5

Example response

{
  "lat": 3.8667,
  "lng": 11.5167,
  "country_code": "CM",
  "place_type": "places",
  "limit": 5,
  "count": 5,
  "hotspots": [
    {
      "name": "Yaoundé",
      "type": "city",
      "lat": 3.8667,
      "lng": 11.5167,
      "distance_km": 0.412,
      "score": 0.9823,
      "population": 2765568,
      "gravity": 0.9823
    },
    {
      "name": "Mballa II",
      "type": "suburb",
      "lat": 3.8741,
      "lng": 11.5093,
      "distance_km": 1.127,
      "score": 0.4102
    }
  ]
}

With ?admin=true

GET /hotspots/3.8667/11.5167/places/5?admin=true

// Additional field in response:
"admin": [
  { "name": "Centre", "label": "Région", "type": "region", "level": 1 },
  { "name": "Cameroon", "label": "Country", "type": "country", "level": 0 }
]

Hotspot fields

Returns nearby anchor candidates ordered strictly by distance. Country code is auto-resolved from the coordinate by the gateway, so there is no CC parameter in the path.

Path parameters

Example requests

GET /anchors/local/2.888527176989689/9.89871021523016/village/10
GET /anchors/immediate/2.888527176989689/9.89871021523016/places/30

Example response

{
  "lat": 2.888527176989689,
  "lng": 9.89871021523016,
  "country_code": "CM",
  "range": "local",
  "bucket_width_m": 3300,
  "place_type": "village",
  "limit": 10,
  "count": 3,
  "anchors": [
    {
      "name": "Bwambé",
      "type": "village",
      "lat": 2.88846,
      "lng": 9.90369,
      "distance_m": 553,
      "distance_km": 0.553,
      "gravity": 287.34
    },
    {
      "name": "Mbeka'a",
      "type": "village",
      "lat": 2.88317,
      "lng": 9.90009,
      "distance_m": 615,
      "distance_km": 0.615,
      "gravity": 287.34
    },
    {
      "name": "Lobé",
      "type": "village",
      "lat": 2.88193,
      "lng": 9.89304,
      "distance_m": 967,
      "distance_km": 0.967,
      "gravity": 2254.71
    }
  ]
}

Response fields

Returns the dominant metro (city or town) nearest to a coordinate, scored by a gravity-weighted population model. Unlike /context, this is a focused single-object response that always includes the full within administrative chain — useful for resolving the regional hierarchy of any point without the overhead of full context resolution.

Parameters

Example request

GET /metro/CM/3.9500/11.4800

Example response

{
  "lat": 3.95,
  "lng": 11.48,
  "country_code": "CM",
  "metro": {
    "name": "Yaoundé",
    "type": "city",
    "distance": 11240,
    "direction": "SE",
    "lat": 3.8667,
    "lng": 11.5167,
    "population": 2765568,
    "economic_tier": "dominant",
    "within": {
      "name": "Centre",
      "label": "Région",
      "type": "region",
      "within": {
        "name": "Cameroon",
        "label": "Country",
        "type": "country"
      }
    },
    "context": "11240m SE of Yaoundé"
  }
}

Metro fields

Returns an 8-character hex channel that two nearby users will share. Use it as a pub/sub topic, WebSocket room, or proximity bucket.

Query options

Range presets

Example response

{
  "channel": "6b099229",
  "tier": "local",
  "cell_size_m": 1100,
  "range_m": 500
}

Country-based address composer. Returns the default hyperlocal address, a formatted customAddress, and the resolved metro, market, and nearby anchor used to build it.

Path parameters

Query options

Example request

GET /customAddress/CM/2.888527176989689/9.89871021523016?includeCountry=true&includeMetro=true&metroLength=3&includeMarket=true&marketLength=3&range=50

Example response

{
  "address": "f935cdb5",
  "customAddress": "CM-KRI-BEN-MBEKA-f935cdb5",
  "metro": {
    "code": "KRI",
    "name": "Kribi",
    "type": "city",
    "distance": 6297,
    "direction": "S"
  },
  "market": {
    "code": "BEN",
    "name": "Bengandwé",
    "type": "village",
    "distance": 4628,
    "direction": "S"
  },
  "nearby_anchor": {
    "code": "MBEKA",
    "name": "Mbeka'a",
    "type": "village",
    "distance": 615,
    "direction": "N"
  }
}

Response fields

Structured address for any coordinate. Returns a hyperlocal address string, an Open Location Code (Plus Code), the full admin hierarchy, elevation, metro anchor, anchors, and the human-readable context string — all in one authenticated call.

Parameters

Query options

Range presets

Example request

GET /address/CM/3.8667/11.5167

Example response

{
  "lat": 3.8667,
  "lng": 11.5167,
  "country_code": "CM",
  "address": "6b099229",
  "plus_code": "6FMHVG88+MM",
  "tier": "local_zone",
  "range_m": 1100,
  "place": {
    "name": "Etoa-Meki",
    "type": "locality",
    "label": "Localité",
    "lat": 3.8621,
    "lng": 11.5203,
    "distance": 540,
    "direction": "SE"
  },
  "dem": 734,
  "within": {
    "name": "Centre Commercial",
    "type": "quarter",
    "within": {
      "name": "Yaoundé I",
      "type": "district",
      "within": {
        "name": "Mfoundi",
        "type": "department",
        "within": { "name": "Centre", "type": "region" }
      }
    }
  },
  "anchors": {
    "immediate": ["mall", "marketplace", "pharmacy"],
    "local": ["city"],
    "reachable": ["town"]
  },
  "metro": {
    "name": "Yaoundé",
    "type": "city",
    "context": "574m SW of Yaoundé"
  },
  "context": "Dans l'orbite commerciale principale de Yaoundé...",
  "country": {
    "name": "Cameroon",
    "code": "CM",
    "flag": "\uD83C\uDDE8\uD83C\uDDF2",
    "lang": "fr",
    "currency": { "symbol": "F", "code": "XAF", "name": "CFA" }
  }
}

Response fields

Returns an SVG QR code for a coordinate. The code encodes the hyperlocal address channel, the nearest place name, lat/lng, and the dominant metro anchor — everything needed to identify and share a physical location in a single scan.

Scan me

3.8667° N · 11.5167° E · CM · range 1100 m

Parameters

Range presets

QR payload (newline-separated)

6b099229          ← hyperlocal address channel
Etoa-Meki         ← nearest place name
3.8667,11.5167    ← lat,lng
Yaoundé           ← metro anchor (omitted if none)

Example request

GET /qr/CM/3.8667/11.5167/1100

Example usage in HTML

<img src="https://api.bwendi.com/qr/CM/3.8667/11.5167/1100"
     alt="Location QR code"
     width="200" height="200">

Response

An image/svg+xml document. Embed directly in <img src="...">, <object>, or save as .svg. Cached at the edge for 24 hours.

Returns the caller's IP-derived geolocation — coordinates, country code, city, and full country object — using Cloudflare's edge geolocation. The gateway enriches every request with x-cf-* headers before forwarding to the origin.

Example request

GET /geo

Example response

{
  "lat": 47.2017,
  "lng": 7.5665,
  "cc": "CH",
  "city": "Zuchwil",
  "country": {
    "name": "Switzerland",
    "localName": "Schweiz",
    "code": "CH",
    "callingCode": "41",
    "flag": "🇨🇭",
    "lang": "de",
    "currency": {
      "symbol": "Fr.",
      "code": "CHF",
      "name": "Franc",
      "localName": "Schweizer Franken"
    }
  }
}

Fields

Server health check. Returns process uptime, memory, and loaded-country count.

{
  "status": "ok",
  "uptime": 84210,
  "countries_loaded": 47,
  "memory_mb": 128,
  "timestamp": "2026-03-12T12:00:00.000Z"
}

List all available countries, or get detailed info for one.

// GET /countries
{ "built": ["AD","AE","CM","NG", ...], "built_count": 47 }

// GET /countries/CM
{ "country_code": "CM", "has_data": true, "db_size_mb": 12.4 }

Returns a map of every built country code to its default language, plus the sorted list of unique language codes.

{
  "languages": {
    "CM": "fr",
    "NG": "en",
    "ET": "am",
    "...": "..."
  },
  "country_count": 174,
  "unique_languages": ["am", "ar", "de", "en", "es", "fr", "..." ],
  "unique_count": 72
}