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.
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.
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 |
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
}
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"]
}
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.
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
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.
Accepts the following message:
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.
{
"service": "event",
"action": "subscribe",
"eventNames": [
"Death"
],
"characters": [
"all"
],
"worlds": [
"string"
],
"logicalAndCharactersWithWorlds": true
}
Accepts the following message:
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.
{
"service": "event",
"action": "subscribe",
"eventNames": [
"Death"
],
"characters": [
"all"
],
"worlds": [
"string"
],
"logicalAndCharactersWithWorlds": true
}
Accepts the following message:
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.
{
"service": "event",
"action": "echo",
"payload": {
"service": "event",
"type": "serviceMessage",
"payload": {
"character_id": "5428010618035589553",
"event_name": "FakeEvent",
"timestamp": "1706357108",
"world_id": "1"
}
}
}
Accepts the following message:
Return a brief help message via the ESS.
{
"service": "event",
"action": "help"
}
Accepts the following message:
Returns a list of character IDs that have been recently seen by the ESS.
{
"service": "event",
"action": "recentCharacterIds"
}
Accepts the following message:
Returns the number of character IDs that have been recently seen by the ESS.
{
"service": "event",
"action": "recentCharacterIdsCount"
}
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.
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.
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.
Return a brief help message via the ESS.
Returns a list of character IDs that have been recently seen by the ESS.
Returns the number of character IDs that have been recently seen by the ESS.
Event message for the AchievementEarned
subscription.
Event message for the BattleRankUp
subscription.
Event message for the Death
subscription.
Event message for the GainExperience
subscription.
Event message for the ItemAdded
subscription.
Event message for the PlayerFacilityCapture
subscription.
Event message for the PlayerFacilityDefend
subscription.
Event message for the PlayerLogin
subscription.
Event message for the PlayerLogout
subscription.
Event message for the SkillAdded
subscription.
Event message for the VehicleDestroy
subscription.
Event message for the ContinentLock
subscription.
Event message for the FacilityControl
subscription.
Event message for the MetagameEvent
subscription.
Heartbeat message sent by the ESS to show that the connection is still alive. Also contains status information about the available endpoints.
System message sent by the ESS to indicate that the connection state has changed.
System message sent by the ESS to indicate that the service state has changed.