EF-Map API Access Examples

Examples below show representative requests and shortened responses for each access scope. They are intended to help builders decide which scope they need before requesting a key. For what the scopes are and how to request access, start at the API Access page.

How to read these examples:

Responses are shortened. Arrays are trimmed to one or two items and large lists are noted in text. Field names and values otherwise reflect the current production API.
Real calls need access. These endpoints require a granted API key with the matching scope, unless the request is same-origin browser traffic from EF-Map itself. Send your key as X-API-Key: <your-api-key>. Never share or embed your key.
Shapes may evolve. Fields can be added over time, but these samples reflect what the production API returns today. Treat indexed data as evidence, not absolute live truth.
All values shown are public EF-Map data already visible on the killboard, intelligence, and finder surfaces of the site. IDs are on-chain / in-game identifiers.

Scopes

Snapshots — snapshots.read
Assemblies List — assemblies.list.read
Assembly Detail — assemblies.detail.read
Player Bases — player-bases.read
Intel — intel.read
SSU Full Search — ssu.full

Snapshots

snapshots.read

Snapshot-style shared map feeds. This is a broad scope covering several read-only endpoints that publish on a schedule (typically every few minutes). All are GET requests with no required parameters — each returns the full current feed.

Covered endpoints: GET /api/killboard-snapshot GET /api/killboard-timeline GET /api/smart-gate-links GET /api/system-overlays GET /api/gate-access GET /api/structure-snapshot

Kill timeline — `GET /api/killboard-timeline`

A compact, replay-friendly list of every indexed kill. Each row is a fixed tuple [timestampMs, solarSystemId, lossType] where lossType is 1 for a structure loss and 0 for a ship loss.

Request

curl -H "X-API-Key: <your-api-key>" \
  "https://ef-map.com/api/killboard-timeline"

Response (shortened — 5428 rows total)

{
  "generatedAt": "2026-06-17T09:10:00.650Z",
  "schemaVersion": 1,
  "count": 5428,
  "oldest": 1773261241000,
  "newest": 1781672213000,
  "kills": [
    [1773261241000, 30013458, 1],
    [1773261809000, 30016355, 0],
    [1773262053000, 30016358, 0]
  ]
}

Killboard snapshot — `GET /api/killboard-snapshot`

Pre-aggregated leaderboards, per-system kill counts, and recent kills across rolling time windows (last1h, last3h, last6h, last24h, last7d, last30d, allTime).

Response (shortened — each window holds up to 50 characters and 50 tribes; the full payload also includes systemKills, recentKills, characterIndex, and tribeIndex)

{
  "generatedAt": "2026-06-17T09:10:00.650Z",
  "schemaVersion": 3,
  "meta": {
    "totalKills": 5428,
    "uniqueKillers": 193,
    "uniqueVictims": 1271,
    "uniqueSystems": 230,
    "totalFoamDestroyed": 15570.5,
    "totalStructureKills": 5110,
    "newestKillTimestamp": 1781672213000
  },
  "leaderboards": {
    "last6h": {
      "characters": [
        {
          "characterId": "2112077876",
          "name": "Brettius Maximus",
          "tribeId": "98000441",
          "tribeName": "The Ancients",
          "tribeTicker": "ANCT",
          "kills": 13,
          "deaths": 0,
          "uniqueVictims": 7,
          "structureKills": 13
        }
      ],
      "tribes": [
        {
          "tribeId": "98000441",
          "name": "The Ancients",
          "ticker": "ANCT",
          "uniqueKillers": 8,
          "kills": 14,
          "deaths": 0,
          "structureKills": 14
        }
      ]
    }
  },
  "recentKills": [
    {
      "killMailId": "27195:stillness",
      "killerName": "Cowboy",
      "killerTribeTicker": "ANCT",
      "victimName": "Xekka",
      "victimTribeTicker": "RR",
      "solarSystemId": "30000192",
      "lossType": 1,
      "timestamp": 1781672213000,
      "foamValue": 0
    }
  ]
}

Smart gate links — `GET /api/smart-gate-links`

Current smart-gate connections and their online/linked state, used for routing. Zero-cost edges represent traversable gate jumps.

{
  "updatedAt": "2026-06-17T09:14:00.173Z",
  "links": [
    {
      "gateId": "0xf301fe4b914134b9db8c8e6dcb400c544f440b6fe55faa1a561f2b6a0534d658",
      "origin": 30020644,
      "destination": 30020642,
      "linked": true,
      "online": true,
      "cost": 0
    }
  ],
  "gateMeta": {},
  "source": "sui"
}

Gate access — `GET /api/gate-access`

Per-gate access rules (public vs. restricted) that pair with the smart-gate links for routing permissions.

{
  "updatedAt": "2026-06-17T09:14:00.173Z",
  "rules": [
    {
      "gate_id": "0xf301fe4b914134b9db8c8e6dcb400c544f440b6fe55faa1a561f2b6a0534d658",
      "fromSystemId": 30020644,
      "toSystemId": 30020642,
      "appliedSystemId": "0x0000000000000000000000000000000000000000",
      "isPublic": true
    }
  ],
  "gateMeta": {}
}

System overlays — `GET /api/system-overlays`

A lightweight map keyed by solar-system id, used to colour the map by tribe ownership / sovereignty overlays.

{
  "version": 1,
  "type": "tribe",
  "updatedAt": "2025-09-19T00:00:00.000Z",
  "data": {
    "10001001": "tribe_alpha",
    "10002002": "tribe_beta"
  }
}

Structure snapshot — `GET /api/structure-snapshot`

Aggregate counts of anchored assemblies by status, type, size, and per-system breakdown. Useful for overlays and statistics without pulling individual records.

Response (shortened — systems holds ~150 entries; meta includes several more breakdowns)

{
  "meta": {
    "generatedAt": "2026-06-17T09:00:00.543Z",
    "totalAssemblies": 55627,
    "statuses": { "2": 37986, "3": 5631, "4": 12010 },
    "types": { "NWN": 7618, "SG": 92, "SSU": 4665, "ST": 8092, "manufacturer": 29150, "relay": 3280, "smart_hangar": 2730 },
    "sizes": { "L": 2923, "M": 16893, "S": 18493 }
  },
  "systems": {
    "30000004": {
      "counts": { "SG": { "4": 1 }, "manufacturer": { "2": 1, "4": 3 }, "SSU": { "4": 1 }, "NWN": { "4": 1 } },
      "confidence": { "exact": 1, "inferred": 6 },
      "tribes": { "1000167": { "NWN": { "4": 1 }, "SG": { "4": 1 }, "SSU": { "4": 1 }, "manufacturer": { "2": 1, "4": 3 } } }
    }
  }
}

Status codes seen above: 2 = Anchored, 3 = Online/Unanchoring stages, 4 = Online (labels are surfaced as status_label in the assembly endpoints below).

Assemblies List

assemblies.list.read

The computed per-system assembly listing. Answers "what assemblies are in this system?" Good for search and summary views.

Endpoint: GET /api/assemblies?systemId=<numericSystemId>

Required parameter: systemId (numeric). A system with no indexed assemblies returns { "count": 0, "assemblies": [] }.

Request

curl -H "X-API-Key: <your-api-key>" \
  "https://ef-map.com/api/assemblies?systemId=30000004"

Response

{
  "system_id": "30000004",
  "count": 1,
  "assemblies": [
    {
      "assembly_id": "0xb9f1a678480f50645f788259fcea1700b150569410f6ca889526057cfd91a520",
      "type_id": 87120,
      "type_name": "Heavy Printer",
      "assembly_type": "manufacturer",
      "status": 2,
      "status_label": "Anchored",
      "character_name": "MacDolo",
      "character_address": "0x8d6f94462469b78bf2f7def5854f02316d233cfc28451544e994aa24c9a4d03b",
      "tribe_id": 1000167,
      "tribe_name": "Clonebank 86",
      "tribe_ticker": "CO86",
      "x": 17598339836241182,
      "y": -4253820206506453,
      "z": 75660107471647400000,
      "location_source": "inferred"
    }
  ]
}

location_source is exact when coordinates are known and inferred when they are estimated. Responses cache for a few minutes.

Assembly Detail

assemblies.detail.read

The same per-system assembly records as Assemblies List, addressed by a path parameter and gated by its own scope. Grant this to tools that read one known system at a time (click-through detail views) rather than browsing broadly.

Endpoint: GET /api/assemblies/<numericSystemId>

Request

curl -H "X-API-Key: <your-api-key>" \
  "https://ef-map.com/api/assemblies/30000004"

Response (same record shape as Assemblies List)

{
  "system_id": "30000004",
  "count": 1,
  "assemblies": [
    {
      "assembly_id": "0xb9f1a678480f50645f788259fcea1700b150569410f6ca889526057cfd91a520",
      "type_id": 87120,
      "type_name": "Heavy Printer",
      "assembly_type": "manufacturer",
      "status": 2,
      "status_label": "Anchored",
      "character_name": "MacDolo",
      "tribe_id": 1000167,
      "tribe_name": "Clonebank 86",
      "tribe_ticker": "CO86",
      "location_source": "inferred"
    }
  ]
}

Player Bases

player-bases.read

Where a character or tribe has anchored network nodes (player bases), grouped by system. Useful for settlement tracking and presence overlays.

Endpoint: GET /api/player-bases?tribeId=<numeric> or GET /api/player-bases?characterId=<numeric>

Required parameter: one of tribeId or characterId (numeric). Without either, the endpoint returns 400.

Request

curl -H "X-API-Key: <your-api-key>" \
  "https://ef-map.com/api/player-bases?tribeId=1000167"

Response (shortened — systems holds 287 entries here)

{
  "characterId": null,
  "tribeId": "1000167",
  "systems": [
    { "systemId": "30013574", "nodeCount": 7 },
    { "systemId": "30016295", "nodeCount": 4 }
  ],
  "systemCount": 287,
  "totalNodes": 377
}

Intel

intel.read

Search and summary intelligence for players, tribes, and assemblies. This scope is for "find and summarize" lookups — combat windows, activity mix, likely systems, base and structure context. It is indexed evidence, not live presence, online status, or a sovereignty authority, and it never exposes private/admin data.

Covered endpoints: GET /api/intel/search?q=<text>&limit=<n> GET /api/intel/players/<characterIdSui>/summary GET /api/intel/tribes/<tribeId>/summary GET /api/intel/assemblies/<assemblyId>/inventory

Search — `GET /api/intel/search`

Type-ahead search across players and tribes. The returned id values are what you pass to the summary endpoints (players use a Sui character id, tribes use a numeric tribe id).

Request

curl -H "X-API-Key: <your-api-key>" \
  "https://ef-map.com/api/intel/search?q=Ancients&limit=5"

Response (shortened)

{
  "query": "Ancients",
  "results": [
    {
      "type": "tribe",
      "id": "98000441",
      "name": "The Ancients",
      "ticker": "ANCT",
      "subtitle": "[ANCT] • #98000441",
      "memberCountCurrent": 16,
      "signals": { "hasCombat": true, "hasActivity": false, "hasMembers": true, "hasBases": false },
      "match": { "field": "name", "kind": "prefix" }
    }
  ]
}

Tribe summary — `GET /api/intel/tribes/<tribeId>/summary`

Request

curl -H "X-API-Key: <your-api-key>" \
  "https://ef-map.com/api/intel/tribes/98000441/summary"

Response (heavily shortened — the full summary also includes activity, members, bases, structureIntel, likelySystems, freshness, and caveats)

{
  "entity": {
    "type": "tribe",
    "id": "98000441",
    "name": "The Ancients",
    "ticker": "ANCT",
    "description": "The source of truth"
  },
  "overview": {
    "memberCountCurrent": 16,
    "lastIndexedAt": "2026-06-17T09:14:59Z",
    "lastObservedActivityAt": "2026-06-16T23:00:00Z",
    "coverage": { "combat": true, "activity": false, "members": true, "bases": false }
  },
  "combat": {
    "windows": {
      "24h": { "kills": 134, "deaths": 0, "uniqueVictims": 30, "foamDestroyed": 26, "structureKills": 134 }
    },
    "topSystems": [
      { "systemId": "30013490", "kills": 414, "deaths": 25 }
    ],
    "recent": [
      {
        "killId": "27195:stillness",
        "timestamp": "2026-06-17T04:56:53Z",
        "systemId": "30000192",
        "role": "killer",
        "opponentName": "Xekka",
        "opponentTribeName": "Rift Riders",
        "lossType": "structure"
      }
    ]
  }
}

Player summary — `GET /api/intel/players/<characterIdSui>/summary`

Same summary shape as a tribe, keyed by the Sui character id returned from search. The entity also carries the legacy killboardCharacterId so you can cross-reference the killboard feeds.

Response (heavily shortened)

{
  "entity": {
    "type": "player",
    "id": "0xe7c9f9bd9623ee05a9341f9615cb2e122fa7781bbba4c2f883e66696ded070fc",
    "name": "Cowboy",
    "killboardCharacterId": "2112077899",
    "tribe": { "id": "98000441", "name": "The Ancients", "ticker": "ANCT" }
  },
  "overview": {
    "lastIndexedAt": "2026-06-17T09:14:58Z",
    "coverage": { "combat": true, "activity": false, "bases": false }
  },
  "combat": {
    "windows": {
      "24h": { "kills": 58, "deaths": 0, "uniqueVictims": 1, "foamDestroyed": 26, "structureKills": 58 }
    },
    "topSystems": [
      { "systemId": "30000192", "kills": 58, "deaths": 0 }
    ]
  }
}

SSU Full Search

ssu.full

Full Smart Storage Unit search through the Worker, returning the actual matching SSUs and their item contents. This is not the public demo search (POST /api/ssu-demo-search, which is aggregate-only); the full search requires the ssu.full scope on your key. It is one of the heavier scopes and is granted deliberately.

Endpoint: POST /api/ssu-search (JSON body)

Request body fields: type_ids (array of item type ids from the public /api/item-types list), logic ("OR" or "AND"), min_quantity, and either search_all: true to scan every system or system_ids (array) to scope the search.

Request

curl -X POST \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type_ids": [82128],
    "logic": "OR",
    "min_quantity": 1,
    "search_all": true,
    "system_ids": []
  }' \
  "https://ef-map.com/api/ssu-search"

Response (shortened — 731 SSUs across 16 systems here; results are grouped by system_id)

{
  "search_params": {
    "type_ids": [82128],
    "logic": "OR",
    "min_quantity": 1,
    "search_all": true,
    "system_ids": []
  },
  "systems_searched": 0,
  "ssus_found": 731,
  "results": [
    {
      "system_id": "30016295",
      "assemblies": [
        {
          "assembly_id": "0x419928309f9643591732972a9ea180f670086ebc134e653966ee086e7769ec8c",
          "assembly_type_id": 88083,
          "type_name": "Storage",
          "system_id": "30016295",
          "status": 1,
          "status_label": "Anchored",
          "character_name": "TrulyLux",
          "tribe_name": "Clonebank 86",
          "tribe_ticker": "CO86",
          "items": [
            { "item_object_id": "0", "type_id": 82128, "type_name": "AC Gyrojet Ammo 1 (S)", "quantity": 666 }
          ]
        }
      ]
    }
  ]
}

When search_all is true, systems_searched is reported as 0 because the search spans the whole index rather than a supplied system list. Results with an unknown system are bucketed under system_id: "0".

Ready to build something? Head back to API Access for the scope overview and how to request a key, then email [email protected] with your project details and the scopes you need.

EF-Map API Access Examples

Snapshots

Kill timeline — GET /api/killboard-timeline

Killboard snapshot — GET /api/killboard-snapshot

Smart gate links — GET /api/smart-gate-links

Gate access — GET /api/gate-access

System overlays — GET /api/system-overlays

Structure snapshot — GET /api/structure-snapshot

Assemblies List

Assembly Detail

Player Bases

Intel

Search — GET /api/intel/search

Tribe summary — GET /api/intel/tribes/<tribeId>/summary

Player summary — GET /api/intel/players/<characterIdSui>/summary

SSU Full Search

Kill timeline — `GET /api/killboard-timeline`

Killboard snapshot — `GET /api/killboard-snapshot`

Smart gate links — `GET /api/smart-gate-links`

Gate access — `GET /api/gate-access`

System overlays — `GET /api/system-overlays`

Structure snapshot — `GET /api/structure-snapshot`

Search — `GET /api/intel/search`

Tribe summary — `GET /api/intel/tribes/<tribeId>/summary`

Player summary — `GET /api/intel/players/<characterIdSui>/summary`