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.

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
• Community Map Names — community-map.names.read

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 latest published feed, which can lag its underlying source.

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. Schema v2 rows are a fixed tuple [timestampMs, solarSystemId, lossType, killerCharacterId, killerTribeId] where lossType is 1 for a structure loss and 0 for a ship loss. killerCharacterId is the killer-side pilot id (a string; "" when unattributed) and killerTribeId is that pilot's tribe id (a string, or null when tribeless / unknown). The two trailing fields are killer-side attribution only — they enable replaying a single player's or tribe's kills. Older clients may treat each row as a 3-tuple [timestampMs, solarSystemId, lossType] and ignore the extra fields.

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": 2,
  "count": 5428,
  "oldest": 1773261241000,
  "newest": 1781672213000,
  "kills": [
    [1773261241000, 30013458, 1, "2112077764", "98000513"],
    [1773261809000, 30016355, 0, "2112080435", null],
    [1773262053000, 30016358, 0, "2112077764", "98000513"]
  ]
}

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".

Community Map Names

community-map.names.read

The Cycle 7 system names players have charted on the EF-Map community map, as system ID and name pairs. Only names are shared: no positions, gate links, system contents or who reported them.

Endpoint: GET /api/community-map/system-names, with an optional ?since=<ms epoch> that returns only systems updated after that time, for incremental syncs.

Request

curl -H "X-API-Key: <your-api-key>"   "https://ef-map.com/api/community-map/system-names"

Response

{
  "ok": true,
  "ns": "live",
  "generatedAt": 1790716000000,
  "count": 2,
  "systems": [
    { "id": 30021369, "name": "T.22G.4D1", "nameStatus": "confirmed", "updatedAt": 1790710000000 },
    { "id": 30021370, "name": "D.ZTG.T91", "nameStatus": "reported", "updatedAt": 1790712000000 }
  ]
}

nameStatus is reported (one player so far), confirmed (two or more players agree) or conflict (players disagree, and the most-reported name is returned). Responses are cached for about a minute, so poll no faster than that, passing the largest updatedAt you have seen as since.

Each name is published for one system only: a submission that reuses a name already charted on a different system is refused. When a moderator removes a wrong submission, that system drops out of the list instead of appearing as an update, so an incremental since sync will not see the removal. Do a full fetch without since now and then (once an hour is plenty) and drop IDs that are no longer listed.