Wanderer

Comprehensive Guide: Wanderer API Documentation

2025-03-05 - BY Wanderer Team

Complete documentation for Wanderer's public APIs, including map data, character information, and access control management. Includes interactive API documentation with Swagger UI.

Comprehensive Guide to Wanderer’s API

Introduction

Wanderer provides a comprehensive set of public APIs that allow you to programmatically interact with the platform. This guide consolidates all available API endpoints, authentication methods, and includes interactive documentation options.

With these APIs, you can:

  • Retrieve map data, including systems and their properties
  • Access system static information
  • Track character locations and activities
  • Monitor kill activity in systems
  • Manage Access Control Lists (ACLs) for permissions
  • Add, update, and remove ACL members

This guide provides step-by-step instructions, request/response examples, and details on how to authenticate each call.

Interactive API Documentation

For a more interactive experience, Wanderer provides a way to explore the API:

Swagger UI

Access our Swagger UI documentation at:

/swaggerui

This interactive interface allows you to:

  • Browse all available endpoints
  • See request parameters and response schemas
  • Test API calls directly from your browser
  • View authentication requirements

Swagger UI

Authentication

Wanderer uses Bearer token authentication for API access. There are two types of tokens in use:

  1. Map API Token: Available in the map settings. This token is used for map-specific endpoints.

    Generate Map API Key

  2. ACL API Token: Available in the create/edit ACL screen. This token is used for ACL member management endpoints.

    Generate ACL API Key

Pass the appropriate token in the Authorization header:

Authorization: Bearer <YOUR_TOKEN>

If the token is missing or invalid, you’ll receive a 401 Unauthorized error.

Note: Some “common” endpoints (like system static information) don’t require authentication.

Map Data Endpoints

1. List Systems

GET /api/map/systems?map_id=<UUID>
GET /api/map/systems?slug=<map-slug>
  • Description: Retrieves a list of systems associated with the specified map.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_id (optional if slug is provided) — the UUID of the map.
    • slug (optional if map_id is provided) — the slug identifier of the map.
    • all=true (optional) — if set, returns all systems instead of only “visible” systems.

Example Request

curl -H "Authorization: Bearer <REDACTED_TOKEN>" \
     "https://wanderer.example.com/api/map/systems?slug=some-slug"

Example Response

{
  "data": [
    {
      "id": "<REDACTED_ID>",
      "name": "<REDACTED_NAME>",
      "status": 0,
      "tag": null,
      "visible": false,
      "description": null,
      "labels": "<REDACTED_JSON>",
      "inserted_at": "2025-01-01T13:38:42.875843Z",
      "updated_at": "2025-01-01T13:40:16.750234Z",
      "locked": false,
      "solar_system_id": "<REDACTED_NUMBER>",
      "map_id": "<REDACTED_ID>",
      "custom_name": null,
      "position_x": 1125,
      "position_y": -285
    },
    ...
  ]
}

2. Show Single System

GET /api/map/system?id=<SOLAR_SYSTEM_ID>&map_id=<UUID>
GET /api/map/system?id=<SOLAR_SYSTEM_ID>&slug=<map-slug>
  • Description: Retrieves information for a specific system on the specified map.
  • Authentication: Requires Map API Token.
  • Parameters:
    • id (required) — the solar_system_id.
    • Either map_id or slug (required).

Example Request

curl -H "Authorization: Bearer <REDACTED_TOKEN>" \
     "https://wanderer.example.com/api/map/system?id=<REDACTED_NUMBER>&slug=<REDACTED_SLUG>"

Example Response

{
  "data": {
    "id": "<REDACTED_ID>",
    "name": "<REDACTED_NAME>",
    "status": 0,
    "tag": null,
    "visible": false,
    "description": null,
    "labels": "<REDACTED_JSON>",
    "inserted_at": "2025-01-03T06:30:02.069090Z",
    "updated_at": "2025-01-03T07:47:07.471051Z",
    "locked": false,
    "solar_system_id": "<REDACTED_NUMBER>",
    "map_id": "<REDACTED_ID>",
    "custom_name": null,
    "position_x": 1005,
    "position_y": 765
  }
}

3. System Static Information

GET /api/common/system-static-info?id=<SOLAR_SYSTEM_ID>
  • Description: Retrieves the static information for a specific system.
  • Authentication: No authentication required.
  • Parameters:
    • id (required) — the solar_system_id.

Example Request

curl "https://wanderer.example.com/api/common/system-static-info?id=31002229"

Example Response

{
  "data": {
    "solar_system_id": 31002229,
    "triglavian_invasion_status": "Normal",
    "solar_system_name": "J132946",
    "system_class": 5,
    "region_id": 11000028,
    "constellation_id": 21000278,
    "solar_system_name_lc": "j132946",
    "constellation_name": "E-C00278",
    "region_name": "E-R00028",
    "security": "-1.0",
    "type_description": "Class 5",
    "class_title": "C5",
    "is_shattered": false,
    "effect_name": null,
    "effect_power": 5,
    "statics": [
      "H296"
    ],
    "wandering": [
      "D792",
      "C140",
      "Z142"
    ],
    "sun_type_id": 38
  }
}

4. List Tracked Characters

GET /api/map/characters?map_id=<UUID>
GET /api/map/characters?slug=<map-slug>
  • Description: Retrieves a list of tracked characters for the specified map.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_id (optional if slug is provided) — the UUID of the map.
    • slug (optional if map_id is provided) — the slug identifier of the map.

Example Request

curl -H "Authorization: Bearer <REDACTED_TOKEN>" \
     "https://wanderer.example.com/api/map/characters?slug=some-slug"

Example Response

{
  "data": [
    {
      "id": "<REDACTED_ID>",
      "character": {
        "id": "<REDACTED_ID>",
        "name": "<REDACTED_NAME>",
        "inserted_at": "2025-01-01T05:24:18.461721Z",
        "updated_at": "2025-01-03T07:45:52.294052Z",
        "alliance_id": "<REDACTED>",
        "alliance_name": "<REDACTED>",
        "alliance_ticker": "<REDACTED>",
        "corporation_id": "<REDACTED>",
        "corporation_name": "<REDACTED>",
        "corporation_ticker": "<REDACTED>",
        "eve_id": "<REDACTED>"
      },
      "tracked": true,
      "map_id": "<REDACTED_ID>"
    },
    ...
  ]
}

5. Kills Activity

GET /api/map/systems-kills?map_id=<UUID>
GET /api/map/systems-kills?slug=<map-slug>
  • Description: Retrieves the kill activity for the specified map.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_id (optional if slug is provided) — the UUID of the map.
    • slug (optional if map_id is provided) — the slug identifier of the map.

Example Request

curl -H "Authorization: Bearer <REDACTED_TOKEN>" \
     "https://wanderer.example.com/api/map/systems-kills?slug=some-slug"

Example Response

{
  "data": [
    {
      "kills": [
        {
          "attacker_count": 1,
          "final_blow_alliance_id": 99013806,
          "final_blow_alliance_ticker": "TCE",
          "final_blow_char_id": 2116802670,
          "final_blow_char_name": "Bambi Bunny",
          "final_blow_corp_id": 98140648,
          "final_blow_corp_ticker": "GNK3D",
          "final_blow_ship_name": "Thrasher",
          "final_blow_ship_type_id": 16242,
          "kill_time": "2025-01-21T21:00:59Z",
          "killmail_id": 124181782,
          "npc": false,
          "solar_system_id": 30002768,
          "total_value": 10000,
          "victim_alliance_id": null,
          "victim_char_id": 2121725410,
          "victim_char_name": "Bill Drummond",
          "victim_corp_id": 98753095,
          "victim_corp_ticker": "KSTJK",
          "victim_ship_name": "Capsule",
          "victim_ship_type_id": 670,
          "zkb": {
            "awox": false,
            "destroyedValue": 10000,
            "droppedValue": 0,
            "fittedValue": 10000,
            "hash": "777148f8bf344bade68a6a0821bfe0a37491a7a6",
            "labels": ["cat:6","#:1","pvp","loc:highsec"],
            "locationID": 50014064,
            "npc": false,
            "points": 1,
            "solo": false,
            "totalValue": 10000
          }
        },
        ...
      ],
      "solar_system_id": 30002768
    },
    ...
  ]
}

6. Structure Timers

GET /api/map/structure-timers?map_id=<UUID>
GET /api/map/structure-timers?slug=<map-slug>
  • Description: Retrieves structure timers for the specified map.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_id (optional if slug is provided) — the UUID of the map.
    • slug (optional if map_id is provided) — the slug identifier of the map.

Character and ACL Endpoints

1. List All Characters

GET /api/characters
  • Description: Returns a list of all characters known to Wanderer.
  • Authentication: Requires a valid API token.
  • Toggle: Controlled by the environment variable WANDERER_CHARACTER_API_DISABLED (default is false).

Example Request

curl -H "Authorization: Bearer <REDACTED_TOKEN>" \
     "https://wanderer.example.com/api/characters"

Example Response

{
  "data": [
    {
      "id": "b374d9e6-47a7-4e20-85ad-d608809827b5",
      "name": "Some Character",
      "eve_id": "2122825111",
      "corporation_name": "School of Applied Knowledge",
      "alliance_name": null
    },
    {
      "id": "6963bee6-eaa1-40e2-8200-4bc2fcbd7350",
      "name": "Other Character",
      "eve_id": "2122019111",
      "corporation_name": "Some Corporation",
      "alliance_name": null
    },
    ...
  ]
}

Use the eve_id when referencing a character in ACL operations.

2. List ACLs for a Map

GET /api/map/acls?map_id=<UUID>
GET /api/map/acls?slug=<map-slug>
  • Description: Lists all ACLs associated with a map.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_id (optional if slug is provided) — the UUID of the map.
    • slug (optional if map_id is provided) — the slug identifier of the map.

Example Request

curl -H "Authorization: Bearer <REDACTED_TOKEN>" \
     "https://wanderer.example.com/api/map/acls?slug=mapname"

Example Response

{
  "data": [
    {
      "id": "19712899-ec3a-47b1-b73b-2bae221c5513",
      "name": "aclName",
      "description": null,
      "owner_eve_id": "11111111111",
      "inserted_at": "2025-02-13T03:32:25.144403Z",
      "updated_at": "2025-02-13T03:32:25.144403Z"
    }
  ]
}

3. Show a Specific ACL

GET /api/acls/:id
  • Description: Fetches a single ACL by ID, with its members preloaded.
  • Authentication: Requires ACL API Token.
  • Parameters:
    • id (required) — the ACL ID.

Example Request

curl -H "Authorization: Bearer <REDACTED_TOKEN>" \
     "https://wanderer.example.com/api/acls/19712899-ec3a-47b1-b73b-2bae221c5513"

Example Response

{
  "data": {
    "id": "19712899-ec3a-47b1-b73b-2bae221c5513",
    "name": "aclName",
    "description": null,
    "owner_id": "d43a9083-2705-40c9-a314-f7f412346661",
    "api_key": "REDACTED_API_KEY",
    "inserted_at": "2025-02-13T03:32:25.144403Z",
    "updated_at": "2025-02-13T03:32:25.144403Z",
    "members": [
      {
        "id": "8d63ab1e-b44f-4e81-8227-8fb8d928dad8",
        "name": "Character Name",
        "role": "admin",
        "eve_character_id": "2122019111",
        "inserted_at": "2025-02-13T03:33:32.332598Z",
        "updated_at": "2025-02-13T03:33:36.644520Z"
      },
      {
        "id": "7e52ab1e-c33f-5e81-9338-7fb8d928ebc9",
        "name": "Corporation Name",
        "role": "viewer",
        "eve_corporation_id": "98140648",
        "inserted_at": "2025-02-13T03:33:32.332598Z",
        "updated_at": "2025-02-13T03:33:36.644520Z"
      },
      {
        "id": "6f41bc2f-d44e-6f92-8449-8ec9e039fad7",
        "name": "Alliance Name",
        "role": "viewer",
        "eve_alliance_id": "99013806",
        "inserted_at": "2025-02-13T03:33:32.332598Z",
        "updated_at": "2025-02-13T03:33:36.644520Z"
      }
    ]
  }
}

Note: The response for each member will include only one of eve_character_id, eve_corporation_id, or eve_alliance_id depending on the type of member.

4. Create a New ACL

POST /api/map/acls
  • Description: Creates a new ACL for a map and generates a new ACL API key.
  • Authentication: Requires Map API Token.
  • Required Query Parameter: Either map_id (UUID) or slug (map slug).
  • Request Body Example: 
{
  "acl": {
    "name": "New ACL",
    "description": "Optional description",
    "owner_eve_id": "EXTERNAL_EVE_ID"
  }
}
  • owner_eve_id must be the external EVE id (the eve_id from /api/characters).

Example Request

curl -X POST \
  -H "Authorization: Bearer <MAP_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "acl": {
          "name": "New ACL",
          "description": "Optional description",
          "owner_eve_id": "EXTERNAL_EVE_ID"
        }
      }' \
  "https://wanderer.example.com/api/map/acls?slug=mapname"

Example Response

{
  "data": {
    "id": "NEW_ACL_UUID",
    "name": "New ACL",
    "description": "Optional description",
    "owner_id": "OWNER_ID",
    "api_key": "GENERATED_ACL_API_KEY",
    "inserted_at": "2025-02-14T17:00:00Z",
    "updated_at": "2025-02-14T17:00:00Z",
    "members": []
  }
}

5. Update an ACL

PUT /api/acls/:id
  • Description: Updates an existing ACL (e.g., name, description).
  • Authentication: Requires ACL API Token.
  • Parameters:
    • id (required) — the ACL ID.
  • Request Body Example: 
{
  "acl": {
    "name": "Updated ACL Name",
    "description": "This is the updated description"
  }
}

Example Request

curl -X PUT \
  -H "Authorization: Bearer <ACL_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "acl": {
          "name": "Updated ACL Name",
          "description": "This is the updated description"
        }
      }' \
  "https://wanderer.example.com/api/acls/ACL_UUID"

Example Response

{
  "data": {
    "id": "ACL_UUID",
    "name": "Updated ACL Name",
    "description": "This is the updated description",
    "owner_id": "OWNER_ID",
    "api_key": "ACL_API_KEY",
    "inserted_at": "2025-02-14T16:49:13.423556Z",
    "updated_at": "2025-02-14T17:22:51.343784Z",
    "members": []
  }
}

6. Add a Member to an ACL

POST /api/acls/:acl_id/members
  • Description: Adds a new member (character, corporation, or alliance) to the specified ACL.
  • Authentication: Requires ACL API Token.
  • Parameters:
    • acl_id (required) — the ACL ID.
  • Request Body Example:

For character membership:

{
  "member": {
    "eve_character_id": "EXTERNAL_EVE_ID",
    "role": "viewer"
  }
}

For corporation membership:

{
  "member": {
    "eve_corporation_id": "CORPORATION_ID",
    "role": "viewer"
  }
}

For alliance membership:

{
  "member": {
    "eve_alliance_id": "ALLIANCE_ID",
    "role": "viewer"
  }
}

Example Request for Character

curl -X POST \
  -H "Authorization: Bearer <ACL_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "member": {
          "eve_character_id": "EXTERNAL_EVE_ID",
          "role": "viewer"
        }
      }' \
  "https://wanderer.example.com/api/acls/ACL_UUID/members"

Example Response for Character

{
  "data": {
    "id": "MEMBERSHIP_UUID",
    "name": "Character Name",
    "role": "viewer",
    "eve_character_id": "EXTERNAL_EVE_ID",
    "inserted_at": "2025-02-15T12:30:45.123456Z",
    "updated_at": "2025-02-15T12:30:45.123456Z"
  }
}

Example Request for Corporation

curl -X POST \
  -H "Authorization: Bearer <ACL_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "member": {
          "eve_corporation_id": "CORPORATION_ID",
          "role": "viewer"
        }
      }' \
  "https://wanderer.example.com/api/acls/ACL_UUID/members"

Example Response for Corporation

{
  "data": {
    "id": "MEMBERSHIP_UUID",
    "name": "Corporation Name",
    "role": "viewer",
    "eve_corporation_id": "CORPORATION_ID",
    "inserted_at": "2025-02-15T12:30:45.123456Z",
    "updated_at": "2025-02-15T12:30:45.123456Z"
  }
}

Example Request for Alliance

curl -X POST \
  -H "Authorization: Bearer <ACL_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "member": {
          "eve_alliance_id": "ALLIANCE_ID",
          "role": "viewer"
        }
      }' \
  "https://wanderer.example.com/api/acls/ACL_UUID/members"

Example Response for Alliance

{
  "data": {
    "id": "MEMBERSHIP_UUID",
    "name": "Alliance Name",
    "role": "viewer",
    "eve_alliance_id": "ALLIANCE_ID",
    "inserted_at": "2025-02-15T12:30:45.123456Z",
    "updated_at": "2025-02-15T12:30:45.123456Z"
  }
}

Note: The response will include only one of eve_character_id, eve_corporation_id, or eve_alliance_id depending on the type of member being added.

7. Change a Member’s Role

PUT /api/acls/:acl_id/members/:member_id
  • Description: Updates an ACL member’s role.
  • Authentication: Requires ACL API Token.
  • Parameters:
    • acl_id (required) — the ACL ID.
    • member_id (required) — the external EVE id (or corp/alliance id) used when creating the membership.
  • Request Body Example: 
{
  "member": {
    "role": "admin"
  }
}

Example Request

curl -X PUT \
  -H "Authorization: Bearer <ACL_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "member": {
          "role": "admin"
        }
      }' \
  "https://wanderer.example.com/api/acls/ACL_UUID/members/EXTERNAL_EVE_ID"

Example Response for Character

{
  "data": {
    "id": "MEMBERSHIP_UUID",
    "name": "Character Name",
    "role": "admin",
    "eve_character_id": "EXTERNAL_EVE_ID",
    "inserted_at": "2025-02-15T12:30:45.123456Z",
    "updated_at": "2025-02-15T12:35:22.654321Z"
  }
}

Note: The response will include only one of eve_character_id, eve_corporation_id, or eve_alliance_id depending on the type of member being updated.

8. Remove a Member from an ACL

DELETE /api/acls/:acl_id/members/:member_id
  • Description: Removes the member with the specified external EVE id (or corp/alliance id) from the ACL.
  • Authentication: Requires ACL API Token.
  • Parameters:
    • acl_id (required) — the ACL ID.
    • member_id (required) — the external EVE id (or corp/alliance id) used when creating the membership.

Example Request

curl -X DELETE \
  -H "Authorization: Bearer <ACL_API_TOKEN>" \
  "https://wanderer.example.com/api/acls/ACL_UUID/members/EXTERNAL_EVE_ID"

Example Response

{ "ok": true }

Conclusion

This guide provides a comprehensive overview of Wanderer’s API capabilities. With these endpoints, you can:

  1. Explore the API using interactive documentation at /swaggerui
  2. Retrieve map data including systems, characters, and kill activity
  3. Access system information with or without authentication
  4. Manage Access Control Lists (ACLs) for permissions
  5. Add, update, and remove ACL members with different roles

For the most up-to-date and interactive documentation, we recommend using the Swagger UI at /swaggerui which allows you to explore and test endpoints directly from your browser.

If you have any questions or need assistance with the API, please reach out to the Wanderer Team.

Fly safe,
WANDERER TEAM