Wanderer

Guide: Systems and Connections API

2025-05-07 - BY Wanderer Team

Detailed guide for Wanderer's systems and connections API endpoints, including batch operations, updates, and deletions.

Guide to Wanderer’s Systems and Connections API

Introduction

This guide covers Wanderer’s dedicated API endpoints for managing systems and connections on your maps. These endpoints provide fine-grained control over individual systems and connections, as well as batch operations for efficient updates.

With these APIs, you can:

  • Create, update, and delete individual systems
  • Create, update, and delete individual connections
  • Perform batch operations on systems and connections
  • Query system and connection details

Authentication

All endpoints require a Map API Token, which you can generate in your map settings. Pass the token in the Authorization header:

Authorization: Bearer <YOUR_MAP_TOKEN>

Systems Endpoints

1. List Systems

GET /api/maps/:map_identifier/systems
  • Description: Retrieves all systems and their connections for the specified map.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.

Example Request

curl -H "Authorization: Bearer <YOUR_TOKEN>" \
     "https://wanderer.example.com/api/maps/your-map-slug/systems"

Example Response

{
  "data": {
    "systems": [
      {
        "id": "<SYSTEM_UUID>",
        "solar_system_id": 30000142,
        "solar_system_name": "Jita",
        "position_x": 100.5,
        "position_y": 200.3,
        "status": "clear",
        "visible": true,
        "description": "Trade hub",
        "tag": "TRADE",
        "locked": false,
        "labels": ["market", "highsec"],
        "map_id": "<MAP_UUID>"
      }
    ],
    "connections": [
      {
        "id": "<CONNECTION_UUID>",
        "solar_system_source": 30000142,
        "solar_system_target": 30000144,
        "type": 0,
        "mass_status": 0,
        "time_status": 0,
        "ship_size_type": 1,
        "wormhole_type": "K162",
        "count_of_passage": 0,
        "locked": false,
        "custom_info": "Fresh hole"
      }
    ]
  }
}

2. Show Single System

GET /api/maps/:map_identifier/systems/:id
  • Description: Retrieves details for a specific system.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.
    • id (required) — the system’s solar_system_id.

Example Request

curl -H "Authorization: Bearer <YOUR_TOKEN>" \
     "https://wanderer.example.com/api/maps/your-map-slug/systems/30000142"

Example Response

{
  "data": {
    "id": "<SYSTEM_UUID>",
    "solar_system_id": 30000142,
    "solar_system_name": "Jita",
    "position_x": 100.5,
    "position_y": 200.3,
    "status": "clear",
    "visible": true,
    "description": "Trade hub",
    "tag": "TRADE",
    "locked": false,
    "labels": ["market", "highsec"],
    "map_id": "<MAP_UUID>"
  }
}

3. Create/Update System

POST /api/maps/:map_identifier/systems
PUT /api/maps/:map_identifier/systems/:id
  • Description: Creates a new system or updates an existing one.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.
    • id (required for PUT) — the system’s solar_system_id.

Example Create Request

curl -X POST \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "solar_system_id": 30000142,
       "solar_system_name": "Jita",
       "position_x": 100.5,
       "position_y": 200.3,
       "status": "clear",
       "visible": true,
       "description": "Trade hub",
       "tag": "TRADE",
       "locked": false,
       "labels": ["market", "highsec"]
     }' \
     "https://wanderer.example.com/api/maps/your-map-slug/systems"

Example Update Request

curl -X PUT \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "status": "hostile",
       "description": "Hostiles reported",
       "tag": "DANGER"
     }' \
     "https://wanderer.example.com/api/maps/your-map-slug/systems/30000142"

4. Delete System

DELETE /api/maps/:map_identifier/systems/:id
  • Description: Deletes a specific system and its associated connections.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.
    • id (required) — the system’s solar_system_id.

Example Request

curl -X DELETE \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     "https://wanderer.example.com/api/maps/your-map-slug/systems/30000142"

5. Batch Delete Systems

DELETE /api/maps/:map_identifier/systems
  • Description: Deletes multiple systems and their connections in a single operation.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.

Example Request

curl -X DELETE \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "system_ids": [30000142, 30000144, 30000145]
     }' \
     "https://wanderer.example.com/api/maps/your-map-slug/systems"

Connections Endpoints

1. List Connections

GET /api/maps/:map_identifier/connections
  • Description: Retrieves all connections for the specified map.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.

Example Request

curl -H "Authorization: Bearer <YOUR_TOKEN>" \
     "https://wanderer.example.com/api/maps/your-map-slug/connections"

Example Response

{
  "data": [
    {
      "id": "<CONNECTION_UUID>",
      "solar_system_source": 30000142,
      "solar_system_target": 30000144,
      "type": 0,
      "mass_status": 0,
      "time_status": 0,
      "ship_size_type": 1,
      "wormhole_type": "K162",
      "count_of_passage": 0,
      "locked": false,
    }
  ]
}

2. Create Connection

POST /api/maps/:map_identifier/connections
  • Description: Creates a new connection between two systems.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.

Example Request

curl -X POST \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "solar_system_source": 30000142,
       "solar_system_target": 30000144,
       "type": 0,
       "mass_status": 0,
       "time_status": 0,
       "ship_size_type": 1,
       "locked": false,
     }' \
     "https://wanderer.example.com/api/maps/your-map-slug/connections"

3. Update Connection

PATCH /api/maps/:map_identifier/connections
  • Description: Updates an existing connection’s properties.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.
    • Query parameters:
      • solar_system_source (required) — source system ID
      • solar_system_target (required) — target system ID

Example Request

curl -X PATCH \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "mass_status": 1,
       "time_status": 1,
     }' \
     "https://wanderer.example.com/api/maps/your-map-slug/connections?solar_system_source=30000142&solar_system_target=30000144"

4. Delete Connection

DELETE /api/maps/:map_identifier/connections
  • Description: Deletes a connection between two systems.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.
    • Query parameters:
      • solar_system_source (required) — source system ID
      • solar_system_target (required) — target system ID

Example Request

curl -X DELETE \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     "https://wanderer.example.com/api/maps/your-map-slug/connections?solar_system_source=30000142&solar_system_target=30000144"

Batch Operations

1. Batch Upsert Systems and Connections

POST /api/maps/:map_identifier/systems
  • Description: Creates or updates multiple systems and connections in a single operation.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.

Example Request

curl -X POST \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "systems": [
         {
           "solar_system_id": 30000142,
           "solar_system_name": "Jita",
           "position_x": 100.5,
           "position_y": 200.3,
           "status": "clear"
         },
         {
           "solar_system_id": 30000144,
           "solar_system_name": "Perimeter",
           "position_x": 150.5,
           "position_y": 250.3,
           "status": "clear"
         }
       ],
       "connections": [
         {
           "solar_system_source": 30000142,
           "solar_system_target": 30000144,
           "type": 0,
           "mass_status": 0,
           "ship_size_type": 1
         }
       ]
     }' \
     "https://wanderer.example.com/api/maps/your-map-slug/systems"

Example Response

{
  "data": {
    "systems": {
      "created": 2,
      "updated": 0
    },
    "connections": {
      "created": 1,
      "updated": 0,
      "deleted": 0
    }
  }
}

The response includes counts for:

  • Systems created and updated
  • Connections created, updated, and deleted (if any)

Note: The deleted count in connections will be 0 for batch operations as deletion is handled through separate endpoints.

Practical Examples

Backup and Restore Map State

We provide a utility script that demonstrates how to use these endpoints to backup and restore your map state:

#!/bin/bash
# backup_restore_test.sh

# 1. Backup current state
curl -H "Authorization: Bearer <YOUR_TOKEN>" \
     "https://wanderer.example.com/api/maps/your-map-slug/systems" \
     > map_backup.json

# 2. Delete everything (after confirmation)
read -p "Delete all systems? (y/N) " confirm
if [[ "$confirm" =~ ^[Yy]$ ]]; then
  # Get system IDs
  systems=$(cat map_backup.json | jq -r '.data.systems[].solar_system_id')
  
  # Create deletion payload
  payload=$(jq -n --argjson ids "$(echo "$systems" | jq -R . | jq -s .)" \
           '{system_ids: $ids}')
  
  # Delete all systems
  curl -X DELETE \
       -H "Authorization: Bearer <YOUR_TOKEN>" \
       -H "Content-Type: application/json" \
       -d "$payload" \
       "https://wanderer.example.com/api/maps/your-map-slug/systems"
fi

# 3. Restore from backup (after confirmation)
read -p "Restore from backup? (y/N) " confirm
if [[ "$confirm" =~ ^[Yy]$ ]]; then
  # Extract systems and connections
  backup_data=$(cat map_backup.json)
  systems=$(echo "$backup_data" | jq '.data.systems')
  connections=$(echo "$backup_data" | jq '.data.connections')
  
  # Create restore payload
  payload="{\"systems\": $systems, \"connections\": $connections}"
  
  # Restore everything
  curl -X POST \
       -H "Authorization: Bearer <YOUR_TOKEN>" \
       -H "Content-Type: application/json" \
       -d "$payload" \
       "https://wanderer.example.com/api/maps/your-map-slug/systems"
fi

This script demonstrates a practical application of the batch operations endpoints for backing up and restoring map data.

Structures Endpoints

1. List Structures

GET /api/maps/:map_identifier/structures
  • Description: Retrieves all structures for the specified map.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.

Example Request

curl -H "Authorization: Bearer <YOUR_TOKEN>" \
     "https://wanderer.example.com/api/maps/your-map-slug/structures"

Example Response

{
  "data": [
    {
      "id": "<STRUCTURE_UUID>",
      "system_id": "<SYSTEM_UUID>",
      "solar_system_id": 30000142,
      "solar_system_name": "Jita",
      "structure_type_id": "35832",
      "structure_type": "Astrahus",
      "character_eve_id": "123456789",
      "name": "Jita Trade Hub",
      "notes": "Main market structure",
      "owner_name": "Wanderer Corp",
      "owner_ticker": "WANDR",
      "owner_id": "corp-uuid-1",
      "status": "anchoring",
      "end_time": "2025-05-01T12:00:00Z",
      "inserted_at": "2025-04-30T10:00:00Z",
      "updated_at": "2025-04-30T10:00:00Z"
    }
  ]
}

2. Show Structure

GET /api/maps/:map_identifier/structures/:id
  • Description: Retrieves details for a specific structure.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.
    • id (required) — the structure’s UUID.

Example Request

curl -H "Authorization: Bearer <YOUR_TOKEN>" \
     "https://wanderer.example.com/api/maps/your-map-slug/structures/<STRUCTURE_UUID>"

Example Response

{
  "data": {
    "id": "<STRUCTURE_UUID>",
    "system_id": "<SYSTEM_UUID>",
    "solar_system_id": 30000142,
    "solar_system_name": "Jita",
    "structure_type_id": "35832",
    "structure_type": "Astrahus",
    "character_eve_id": "123456789",
    "name": "Jita Trade Hub",
    "notes": "Main market structure",
    "owner_name": "Wanderer Corp",
    "owner_ticker": "WANDR",
    "owner_id": "corp-uuid-1",
    "status": "anchoring",
    "end_time": "2025-05-01T12:00:00Z",
    "inserted_at": "2025-04-30T10:00:00Z",
    "updated_at": "2025-04-30T10:00:00Z"
  }
}

3. Create Structure

POST /api/maps/:map_identifier/structures
  • Description: Creates a new structure.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.

Example Request

curl -X POST \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "solar_system_id": 30000142,
       "solar_system_name": "Jita",
       "structure_type_id": "35832",
       "structure_type": "Astrahus",
       "character_eve_id": "123456789",
       "name": "Jita Trade Hub",
       "notes": "Main market structure",
       "owner_name": "Wanderer Corp",
       "owner_ticker": "WANDR",
       "owner_id": "corp-uuid-1",
       "status": "anchoring",
       "end_time": "2025-05-01T12:00:00Z"
     }' \
     "https://wanderer.example.com/api/maps/your-map-slug/structures"

Example Response

{
  "data": {
    "id": "<STRUCTURE_UUID>",
    "system_id": "<SYSTEM_UUID>",
    "solar_system_id": 30000142,
    "solar_system_name": "Jita",
    "structure_type_id": "35832",
    "structure_type": "Astrahus",
    "character_eve_id": "123456789",
    "name": "Jita Trade Hub",
    "notes": "Main market structure",
    "owner_name": "Wanderer Corp",
    "owner_ticker": "WANDR",
    "owner_id": "corp-uuid-1",
    "status": "anchoring",
    "end_time": "2025-05-01T12:00:00Z",
    "inserted_at": "2025-04-30T10:00:00Z",
    "updated_at": "2025-04-30T10:00:00Z"
  }
}

4. Update Structure

PUT /api/maps/:map_identifier/structures/:id
  • Description: Updates an existing structure.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.
    • id (required) — the structure’s UUID.

Example Request

curl -X PUT \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "status": "anchored",
       "notes": "Updated via API"
     }' \
     "https://wanderer.example.com/api/maps/your-map-slug/structures/<STRUCTURE_UUID>"

Example Response

{
  "data": {
    "id": "<STRUCTURE_UUID>",
    "status": "anchored",
    "notes": "Updated via API"
    // ... other fields ...
  }
}

5. Delete Structure

DELETE /api/maps/:map_identifier/structures/:id
  • Description: Deletes a specific structure.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.
    • id (required) — the structure’s UUID.

Example Request

curl -X DELETE \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     "https://wanderer.example.com/api/maps/your-map-slug/structures/<STRUCTURE_UUID>"

Signatures Endpoints

1. List Signatures

GET /api/maps/:map_identifier/signatures
  • Description: Retrieves all signatures for the specified map.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.

Example Request

curl -H "Authorization: Bearer <YOUR_TOKEN>" \
     "https://wanderer.example.com/api/maps/your-map-slug/signatures"

Example Response

{
  "data": [
    {
      "id": "<SIGNATURE_UUID>",
      "system_id": "<SYSTEM_UUID>",
      "eve_id": "ABC-123",
      "name": "Wormhole K162",
      "description": "Leads to unknown space",
      "type": "Wormhole",
      "linked_system_id": 30000144,
      "kind": "cosmic_signature",
      "group": "wormhole",
      "custom_info": "Fresh",
      "solar_system_id": 31001394,
      "solar_system_name": "J214811",
      "character_eve_id": "123456789",
      "inserted_at": "2025-04-30T10:00:00Z",
      "updated_at": "2025-04-30T10:00:00Z"
    }
  ]
}

2. Show Signature

GET /api/maps/:map_identifier/signatures/:id
  • Description: Retrieves details for a specific signature.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.
    • id (required) — the signature’s UUID.

Example Request

curl -H "Authorization: Bearer <YOUR_TOKEN>" \
     "https://wanderer.example.com/api/maps/your-map-slug/signatures/<SIGNATURE_UUID>"

Example Response

{
  "data": {
    "id": "<SIGNATURE_UUID>",
    "system_id": "<SYSTEM_UUID>",
    "eve_id": "ABC-123",
    "name": "Wormhole K162",
    "description": "Leads to unknown space",
    "type": "Wormhole",
    "linked_system_id": 30000144,
    "kind": "cosmic_signature",
    "group": "wormhole",
    "custom_info": "Fresh",
    "solar_system_id": 31001394,
    "solar_system_name": "J214811",
    "character_eve_id": "123456789",
    "inserted_at": "2025-04-30T10:00:00Z",
    "updated_at": "2025-04-30T10:00:00Z"
  }
}

3. Create Signature

POST /api/maps/:map_identifier/signatures
  • Description: Creates a new signature.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.

Example Request

curl -X POST \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "eve_id": "ABC-123",
       "name": "Wormhole K162",
       "description": "Leads to unknown space",
       "type": "Wormhole",
       "linked_system_id": 30000144,
       "kind": "cosmic_signature",
       "group": "wormhole",
       "custom_info": "Fresh",
       "solar_system_id": 31001394,
       "solar_system_name": "J214811"
     }' \
     "https://wanderer.example.com/api/maps/your-map-slug/signatures"

Example Response

{
  "data": {
    "id": "<SIGNATURE_UUID>",
    "eve_id": "ABC-123",
    "name": "Wormhole K162",
    "description": "Leads to unknown space",
    "type": "Wormhole",
    "linked_system_id": 30000144,
    "kind": "cosmic_signature",
    "group": "wormhole",
    "custom_info": "Fresh",
    "solar_system_id": 31001394,
    "solar_system_name": "J214811",
    "character_eve_id": "123456789",
    "inserted_at": "2025-04-30T10:00:00Z",
    "updated_at": "2025-04-30T10:00:00Z"
  }
}

4. Update Signature

PUT /api/maps/:map_identifier/signatures/:id
  • Description: Updates an existing signature.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.
    • id (required) — the signature’s UUID.

Example Request

curl -X PUT \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "description": "Updated via API",
       "custom_info": "Updated info"
     }' \
     "https://wanderer.example.com/api/maps/your-map-slug/signatures/<SIGNATURE_UUID>"

Example Response

{
  "data": {
    "id": "<SIGNATURE_UUID>",
    "description": "Updated via API",
    "custom_info": "Updated info"
    // ... other fields ...
  }
}

5. Delete Signature

DELETE /api/maps/:map_identifier/signatures/:id
  • Description: Deletes a specific signature.
  • Authentication: Requires Map API Token.
  • Parameters:
    • map_identifier (required) — the map’s slug or UUID.
    • id (required) — the signature’s UUID.

Example Request

curl -X DELETE \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     "https://wanderer.example.com/api/maps/your-map-slug/signatures/<SIGNATURE_UUID>"

Conclusion

These endpoints provide powerful tools for managing your map’s systems and connections programmatically. Key features include:

  1. Individual system and connection management
  2. Efficient batch operations
  3. Flexible update options
  4. Robust error handling
  5. Consistent response formats

For the most up-to-date and interactive documentation, remember to check the Swagger UI at /swaggerui.

If you have questions about these endpoints or need assistance, please reach out to the Wanderer Team.

Fly safe, The Wanderer Team