Welcome!

All API Services are operating normally.

Welcome to the Extended Planetside 2 Census API Documentation! Here, you will find documented examples and JSON formats for the various feeds provided by the API service, and the additional subscription/filter features that you can use to customize the events you receive.

API Keys & API Support/Requests

For those interested in writing applications using the API, please email api@blackfeatherproductions.com with information regarding your application, to receive your API Key. If you are experiencing issues with the service, or have a feature/improvement request, please remember to provide your API key when contacting us. You will typically receive a response within 48 hours.

Connecting to the API/Authetication

Connecting to the API

// Open Websocket ConnectionvarapiKey="example";varurl="ws://push.api.blackfeatherproductions.com/?apikey="+apiKey;ws=newWebSocket(url);// Set event handlers.ws.onopen=function(evt){console.log("Websocket Connection Established!");};ws.onmessage=function(evt){// All messages sent by the API are JSON. Parse it so we can work with it.vardata=JSON.parse(evt.data);if(data.websocket_event!=undefined&&data.websocket_event=="connectionStateChange"&&data.online=="true"){console.log("Websocket API Ready.");//The API is ready to receive messages.}};ws.onclose=function(evt){console.log("Websocket Connection Closed.");};ws.onerror=function(evt){console.log("Websocket Error: "+evt.data);};

The Extended Census Websocket uses API keys for authentication and access (which you can get via emailing us). The API key “example” can also be used for experimenting with the API, although use of this key may be limited in the future.

Always use your API key in production applications. Do not use “example”.

This is the probably the most common action. Use it to add filtered events to your subscription.

“field_xx” represents any combination of fields for an event. For more information on the filter system, see the Filter Section.
Subscriptions are additive, but please note that each event DOES NOT share the same filter list for each event. (i.e. specifying worlds for 1 event will not set worlds for all other subscriptions.)

Sent Payload

Field

JSON Type

Description

action

String

The action we want to perform. In this case, subscribe.

event

String

The event that contains the fields we want to unsubscribe from.

field_xx

String/Array

The field, and associated value/s to add to the subscription.

Response Payload

Field

JSON Type

Description

subscriptions

Object

Contains a mapped list of your current subscriptions, and their respective filtered fields.

Allows you to clear all subscribed events, both globally and on an event level.

Sent Payload

Field

JSON Type

Description

action

String

The action we want to perform. In this case, unsubscribeAll.

event

String

(Optional) The event that you wish to remove all subscriptions from. Not specifying an event clears all subscriptions.

Response Payload

Field

JSON Type

Description

subscriptions

Object

Contains a mapped list of your current subscriptions, and their respective filtered fields.

action

String

An echo of the action that modified “subscriptions”.

Status Actions

These actions return information/data that might be useful if you are reconnecting and missed the original associated event.

activeMetagameEvents (previously activeAlerts)

Returns all active metagame events/alerts (and their respective facilities) across all servers. Optionally, you can provide an array of world_id’s to get metagame event information for only the specified servers.

If a world does not contain any running metagame events, it WILL NOT appear in the worlds node.

Sent

{"action":"activeMetagameEvents","worlds":["1002"]}

Response
(Please note this has been truncated, the facilities and metagame_events arrays have more than 1 element)

Sent Payload

(Optional) A single or list of world ID’s (PCPS4-USPS4-EU) that you want Metagame info for. Not specifying any worlds gets all metagame events across all worlds.

Response Payload

root node

Field

JSON Type

Description

action

String

An echo of the action that generated “worlds”

worlds

Object

The parent node containing all worlds valid for the sent request. JSON keys/properties match the “world_id” found on Census (PCPS4-USPS4-EU).

metagame_events node

Field

JSON Type

Description

instance_id

String

Represents the WORLD unique instance ID of this metagame event. This is not globally unique, and can clash with other servers/worlds. Use this to match up start/update/end metagame events that come through the “MetagameEvent” subscription. Matches the “instance_id” found on Census

Introduction to Filters

All events can be filtered through the subscription system. Each event inherits all global filters, and implements multiple filters of their own. Use these filters to refine the events and data you receive.

Global Filters and Subscription Options

all

Disables all event-specific filters for the specified event, therefore receiving all events for the given event type. As David from SOE describes it, “it’s like drinking from a firehose of events”

environments

“environments”: [“pc”,“ps4_us”]

Only includes events from the selected platforms/environments. Valid values are “pc”, “ps4_us”, and “ps4_eu”.

show

“show”: [“timestamp”,“facility_id”]

Only include the provided fields from the event within the message.

hide

“hide”: [“facility_id”, “world_id”]

Includes all fields except the provided fields from the event within the message.
NOTE: Overrides fields in show. If a field is in both hide and show, it will be hidden from the event’s messages.

useAND

“useAND”: [“property1”, “property2”]

By default, the server checks each property with an OR statement. This setting allows you to mark properties that have both an attacker and victim type as AND.

VehicleCombat example: Getting air vehicle vs air vehicle combat

This subscription would return all air vehicle kills where the attacking vehicle, OR the victim’s vehicle were an air vehicle. So if an aircraft destroyed a tank, the event would still be sent to the client.

This subscription would return all air vehicle kills where the attacking vehicle, AND the victim’s vehicle were an air vehicle. So if an aircraft destroyed a tank, the event would NOT be sent to the client.