PlanetSide 2 Event Streaming Service 1.0.0

This is an unofficial specification for the PlanetSide 2 Event Streaming Service (ESS) API used to stream in-game events to clients in near real-time using a WebSocket connection.

The ESS API is subscription based, meaning that clients must subscribe to the events they want to receive.

Interoperability with the Census REST API

The ESS and the REST endpoints of the Census API are separate services with different data sources and update intervals. It is therefore possible for clients to receive events from the ESS API that reference objects that do not exist in the REST endpoints.

For example, newly created characters may not be available in the REST API until several minutes after they logged out of the game. Similarly, new outfits or changes to an outfit roster may take several minutes to be reflected in the REST API.

It is advisable to write clients that can handle such inconsistencies gracefully, either by discarding events that reference unknown objects, or by stashing these messages and retrying them at a later time when the REST API has caught up.

Available Events

The ESS supports the following events:

Event Name Description Character-centric World-centric
AchievementEarned A character has earned a new achievement (weapon medal or service ribbon). Yes No
BattleRankUp A character has gained a Battle Rank. Yes No
Death A character has been killed. Will be sent if either the killer or the victim are part of the subscription. Yes No
ItemAdded A character has been granted an item. This includes pseudo-items such as some terminal interactions or outfit war asset use. Yes No
SkillAdded A character has unlocked a new skill or certification. Yes No
VehicleDestroy A vehicle has been destroyed. Yes No
GainExperience A character has gained experience. It is recommended to filter for specific experience IDs where possible. Yes No
PlayerFacilityCapture A player has taken part in capturing a facility. Yes No
PlayerFacilityDefend A player has taken part in defending a facility. Yes No
ContinentLock A continent has been locked. No Yes
FacilityControl A facility has changed control. No Yes
MetagameEvent A metagame event (Alert, Outfit-Wars, etc.) has started or ended. No Yes
PlayerLogin A player has logged in. Yes Yes
PlayerLogout A player has logged out. Yes Yes

Character-centric and World-centric Events

Events in the ESS are character-centric (Death, GainExperience, BattleRankUp, etc.), world-centric (ContinentLock, FacilityControl, MetagameEvent, etc.), or both (PlayerLogin and PlayerLogout). Centricity determines whether a subscription is valid - for example, it is not possible to subscribe to MetagameEvent with a specific character.

By default, if both characters and worlds are specified in a subscription, the subscription will us OR logic to determine whether an event matches. However, it is possible to specify AND logic using the "logicalAndCharactersWithWorlds": true option of the subscription. This allows filtering character-centric events by world by subscribing to "all" characters while filtering for the desired world(s) in the subscription:

{
  "service": "event", "action": "subscribe", "eventNames": ["Death"],
  "characters": ["all"], "worlds": ["10", "13"], "logicalAndCharactersWithWorlds": true
}

Filtering GainExperience Events

Due to the large number of experience-related events, it is possible to filter GainExperience events further as part of the subscription. To do so, replace the GainExperience event name with GainExperience_experience_id_#, where # is the ID of the experience type to filter for:

{
  "service":"event","action":"subscribe","characters":["all"],"eventNames":["GainExperience_experience_id_1"]
}

Dynamic Zone IDs

Some zones, such as Sanctuary, tutorial zones or Outfit-Wars instances, are dynamically created and destroyed. They are therefore not available through the REST API and do not have a static zone ID, but they may still be referenced in ESS messages. The IDs of these zones are concatenated from two underlying IDs: a definition ID, which is constant for a given zone type (Nexus, Sanctuary, etc.), and an instance ID, which is used to identify the specific instance of the zone. The instance ID is unique for each instance of a zone type, but may be reused after the zone is destroyed.

More information and example code can be found on the PlanetSide 2 API Tracker Wiki on GitHub.

  • #subscriptions
  • #events
  • #system
  • #utilities

Servers

  • wss://push.planetside2.com/streaming/wssdaybreak-games

    Official event streaming endpoint maintained and operated by Daybreak Games.

    To connect, the following query parameters are required:

    • environment: The environment to connect to. This can be one of ps2, ps2ps4us, or ps2ps4eu. The former covers all PC servers, the latter is for the US and EU PS4 servers respectively. If you wish to track events from all servers, you will need to establish multiple concurrent WebSocket clients.
    • service-id: The unique ID used to identify your service.

    Example URL: wss://push.planetside2.com/streaming?environment=ps2&service-id=s:example

  • wss://push.nanite-systems.net/streaming/wssnanite-systems

    Unofficial community-maintained event streaming endpoint wrapping the official endpoint with a multi-connection manifold.

    This is a drop-in replacement that can help increase resilience against individual subscriptions dropping events for long-running services. For more information, see the Nanite Systems Website or check it out on GitHub.

    To connect, the same query parameters as the official endpoint are required (see above).

    Note that this endpoint is not operated by Daybreak Games. The service ID used to connect to this endpoint will be visible to the operator of the endpoint.

Operations

  • SEND

    Operation IDsubscribe

    Available only on servers:

    Accepts the following message:

    Add Subscribtionsubscribe
    Message IDsubscribe

    Subscribe to one or more events for a given character and/or world.

    See the Available Events section for a list of valid event names.

    Refer to the section on Character-centric and World-centric Events for more information on how to handle mixed character and world subscriptions.

    object
    • #subscriptions

    Examples

    {
      "service": "event",
      "action": "subscribe",
      "eventNames": [
        "Death"
      ],
      "characters": [
        "all"
      ],
      "worlds": [
        "string"
      ],
      "logicalAndCharactersWithWorlds": true
    }
    
    This example has been generated automatically.
  • SEND

    Operation IDclearSubscribe

    Available only on servers:

    Accepts the following message:

    Add Subscribtionsubscribe
    Message IDsubscribe

    Subscribe to one or more events for a given character and/or world.

    See the Available Events section for a list of valid event names.

    Refer to the section on Character-centric and World-centric Events for more information on how to handle mixed character and world subscriptions.

    object
    • #subscriptions

    Examples

    {
      "service": "event",
      "action": "subscribe",
      "eventNames": [
        "Death"
      ],
      "characters": [
        "all"
      ],
      "worlds": [
        "string"
      ],
      "logicalAndCharactersWithWorlds": true
    }
    
    This example has been generated automatically.
  • SEND

    Operation IDecho

    Available only on servers:

    Accepts the following message:

    Echo Payloadecho
    Message IDecho

    Echoes the payload back to the client. Useful for testing the connection.

    The payload provided with the echo command will be echoed back unchanged by each ESS endpoint the client is connected to. That means that this mechanism can be used for integration testing if the client sends a valid ESS response payload through the echo command.

    object
    • #utilities

    Examples

    {
      "service": "event",
      "action": "echo",
      "payload": {
        "service": "event",
        "type": "serviceMessage",
        "payload": {
          "character_id": "5428010618035589553",
          "event_name": "FakeEvent",
          "timestamp": "1706357108",
          "world_id": "1"
        }
      }
    }
    
    This example has been generated automatically.
  • SEND

    Operation IDhelp

    Available only on servers:

    Accepts the following message:

    Send Helphelp
    Message IDhelp

    Return a brief help message via the ESS.

    object
    • #utilities

    Examples

    {
      "service": "event",
      "action": "help"
    }
    
    This example has been generated automatically.
  • SEND

    Operation IDrecentCharacterIds

    Available only on servers:

    Accepts the following message:

    Recent Character IDsrecentCharacterIds
    Message IDrecentCharacterIds

    Returns a list of character IDs that have been recently seen by the ESS.

    object
    • #utilities

    Examples

    {
      "service": "event",
      "action": "recentCharacterIds"
    }
    
    This example has been generated automatically.
  • SEND

    Operation IDrecentCharacterIdsCount

    Available only on servers:

    Accepts the following message:

    Recent Character IDs CountrecentCharacterIdsCount
    Message IDrecentCharacterIdsCount

    Returns the number of character IDs that have been recently seen by the ESS.

    object
    • #utilities

    Examples

    {
      "service": "event",
      "action": "recentCharacterIdsCount"
    }
    
    This example has been generated automatically.

Messages

  • #1Add Subscribtionsubscribe
    Message IDsubscribe

    Subscribe to one or more events for a given character and/or world.

    See the Available Events section for a list of valid event names.

    Refer to the section on Character-centric and World-centric Events for more information on how to handle mixed character and world subscriptions.

    object
    • #subscriptions
  • #2Clear SubscriptionclearSubscribe
    Message IDclearSubscribe

    Remove an active subscription.

    This follows the same rules as the subscribe command, but removes the subscription instead of adding it.

    Setting the all option to true will remove all active subscriptions for the current connection.

    object
    • #subscriptions
  • #3Echo Payloadecho
    Message IDecho

    Echoes the payload back to the client. Useful for testing the connection.

    The payload provided with the echo command will be echoed back unchanged by each ESS endpoint the client is connected to. That means that this mechanism can be used for integration testing if the client sends a valid ESS response payload through the echo command.

    object
    • #utilities
  • #4Send Helphelp
    Message IDhelp

    Return a brief help message via the ESS.

    object
    • #utilities
  • #5Recent Character IDsrecentCharacterIds
    Message IDrecentCharacterIds

    Returns a list of character IDs that have been recently seen by the ESS.

    object
    • #utilities
  • #6Recent Character IDs CountrecentCharacterIdsCount
    Message IDrecentCharacterIdsCount

    Returns the number of character IDs that have been recently seen by the ESS.

    object
    • #utilities

Schemas

  • object

    Event message for the AchievementEarned subscription.

  • object

    Event message for the BattleRankUp subscription.

  • object

    Event message for the Death subscription.

  • object

    Event message for the GainExperience subscription.

  • object

    Event message for the ItemAdded subscription.

  • object

    Event message for the PlayerFacilityCapture subscription.

  • object

    Event message for the PlayerFacilityDefend subscription.

  • object

    Event message for the PlayerLogin subscription.

  • object

    Event message for the PlayerLogout subscription.

  • object

    Event message for the SkillAdded subscription.

  • object

    Event message for the VehicleDestroy subscription.

  • object

    Event message for the ContinentLock subscription.

  • object

    Event message for the FacilityControl subscription.

  • object

    Event message for the MetagameEvent subscription.

  • object

    Heartbeat message sent by the ESS to show that the connection is still alive. Also contains status information about the available endpoints.

  • object

    System message sent by the ESS to indicate that the connection state has changed.

  • object

    System message sent by the ESS to indicate that the service state has changed.