Census API

Welcome!

SOE Data Services API Policy

We encourage players to use the SOE Data Services API to increase their engagement with SOE's games and to create websites and mobile apps for other players to use and enjoy. Players are free to monetize their websites and apps by displaying banners and other forms of advertising. Players can also sell their apps and/or charge for premium functionality and content.

The following rules apply to the use of our API…

Comply with this policy and applicable laws

Your website or app must comply with this policy and all applicable laws. Be sure it does not include any content that infringes somebody else's rights. If your website or app includes content that is owned by somebody else, you will need to get their permission first.

Service ID Policy

You'll need to apply for a service ID in order to access the API. The service ID "s:example" is available for casual use--it is throttled to 10 requests per minute per client IP address. Please don't share your service ID with others. Always use a service ID in your applications, whether they access the Census API from the users client machine or from your server. SOE may terminate your service ID access without notice if you do not comply with the SOE API Policy. We may also terminate your access to the API if your website or app makes excessive requests or disrupts SOE's games.

SOE Intellectual Property

SOE reserves all rights and title to its games, game data, and intellectual property. The title of a mobile app using SOE's API may not include the name of an SOE game or any other SOE trademark. All use of game data and other content must comply with this policy and SOE's Terms of Service. Your website or app must not suggest or imply any sponsorship, endorsement, or association with SOE.

No Warranty

SOE's API and game data are provided "AS IS."" SOE may choose, in its discretion, what data to make available through the API. SOE may, in its discretion, modify, revoke access to, or discontinue the API, and/or may remove access to any portion of the game data, or all of the game data, at any time without notice.

SOE MAKES NO WARRANTIES, EXPRESS, IMPLIED, ARISING FROM COURSE OF DEALING OR USAGE OF TRADE, OR STATUTORY, AS TO THE API OR GAME DATA, AND EXPRESSLY EXCLUDES ANY AND ALL WARRANTIES OF TITLE, MERCHANTABILITY, NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE. SOE DOES NOT ENSURE THE CONTINUOUS, ERROR-FREE, BUG FREE, SECURE OR VIRUS FREE ACCESS TO OR OPERATION OF THE API OR GAME DATA.

Updates

SOE will make a best effort to document API changes in the "Developer Notes" forum at: https://forums.station.sony.com/soe/index.php?forums/developer-notes.31/.

SOE reserves the right to update our Policies and APIs at any time.

Contact

Please use SOE's API forums as a platform to ask questions, contribute feedback, and get help at: http://forums.station.sony.com/soe/index.php?categories/data-api.14/. You can also send an email to data-feedback@soe.sony.com.

General Info

Endpoints

The following URL is to be used to access the REST interface: http://census.soe.com

URL Pattern

All requests to the REST interface follow a pattern. There are different patterns for different types of data:

Game Data:

Game Images:

The REST interface will return all results that match the attributes provided within the query string. The data returned is in the form of a list containing zero or more items from the dataset provided in the URL.

When using the XML format, the results will be provided in a parent <{collection}_list> element. In JSON, the results will be in an array ([ ]). If no results are found, this container will be empty.

Service ID

The service ID is used to identify the customer of the Census API for tracking and quality of service issues. The service ID is an alphanumeric value. All service IDs will be of the format s:<the service id>.

For example, here is a query for the world information with the service id (s:example) attached:

https://census.soe.com/s:example/get/ps2:v2/world/

The service ID should be used when making queries to the Census API. Always use a service ID in your applications, whether they access the Census API from the users client machine or from your server. The IP Address is optional. Providing it allows the Census API to ensure others are not misusing your registered Service ID.

To change or update your registered email addresses and IP addresses, please email data-feedback@soe.sony.com.

The service ID "s:example" is available for casual use--it is throttled to 10 requests per minute per client IP address.

Please note that Census API requests without valid Service IDs will be throttled and may be completely blocked in the future.

Sign up for a Service ID Below

Fields marked with an asterisk* are required.

Personal Info

App Info

You choose whatever value you like for your Service ID.

The server IP(s) you will connect from. Leave blank if connecting from clients.

Website link, etc.

Thanks for your submission! You should receive an email from us shortly.

There was a problem with your submission. Try again later or contact us at data-feedback@soe.sony.com

Detailed URL Options

format

The results of a call to the REST interface will be in either JavaScript Object Notation (json) or xml. Json is the default. It was chosen as it is a very efficient way to access data for most applications.

The format may be specified immediately after the service id, i.e. http://census.soe.com/s:example/xml/get/ps2:v2/character/ or http://census.soe.com/s:example/json/get/ps2:v2/character/. Specifying no format will result in the default of json.

Note: For developers, please install a json plugin (like JSONView) on your preferred browser. This will greatly aid in readability and formatting of json.

In order to access data across the domain boundary, one may want to use JSON Padding (jsonp). To do this, append a callback attribute to the query string of the request.

http://census.soe.com/get/ps2:v2/item/?item_id=70966&callback=foo

The results from this request will be padded within the function name, foo(), so that they may be evaluated by the requesting web site within the correct domain.

verb

This informs the REST interface about the type of request that is being made. The following values are supported across all games, however, as each game has its own data needs, different verbs may be made available on a per game basis. Some collections like 'characters_online_status', for example, do not support the count verb.

Supported Value Description
get Retrieve the game data that matches the request criteria
count Retrieve the number of game data objects that match the request criteria

Namespace

The following values are supported for values. At this time, only the games eq2 and ps2 are supported, but others will be added when each game team is ready. Additional values are specified for unannounced games, but are not listed in this document.

A note about versions:
In order to support on-going and future development the Census API uses a versioning scheme.  This allows us to make changes that are not backwards compatible without breaking third-party developed sites. Our first version is 'ps2:v1', however the latest stable version that will always be mapped to 'ps2' i.e. http://census.soe.com/get/ps2:v1/ is exactly the same as http://census.soe.com/get/ps2:v2/. Use 'ps2' if you want to guarantee that you are always pointing at the latest and greatest. Explicitly stating the version will avoid the API suddenly changing out from under your code, i.e. 'ps2:v1'.

Supported Value Game Notes
eq2 EverQuest II Not complete. You may use data.soe.com instead.
ps2:v1 PlanetSide 2 Deprecated. Please move to ps2:v2 by October 1st 2013.
ps2:v2 PlanetSide 2 Stable version, alias is ps2.
dcuo:v1 DC Univese Online Alias is dcuo. New as of 9/3/2014. Should be considered BETA.

collection

Supported collections are dynamic and dependent on the game providing data to the service.

Some objects may be omitted from a collection due to certain policies set by each game team to protect player privacy and/or business requirements.

Examples of these policies might include:

  • Characters may be marked as private so that they are omitted from searches and rankings
  • Items may be hidden until they are "discovered" naturally by a customer

Listing Available Collections

A list of all collections available for a the ps2 game can be found at the following url: http://census.soe.com/get/ps2:v2/

A list of all collections available for a the eq2 game can be found at the following url: http://census.soe.com/get/eq2/

identifier

Most objects have a unique identifier, which is used for a direct link to the information about that object. This can be found within the structure by the top-level "[collection]_id" field. All results will have this identifier, even if all other information is hidden.

There are also identifiers that are used in reference to other collections. For example, consider the following collection information from ps2 returned by this query http://census.soe.com/get/ps2/characters_item/?character_id=5428010618020694593:

characters_item_list: [
{
character_id: "5428010618020694593",
item_id: "16"
},
...

The item_id value is a reference to a particular object within the "item" collection. When presenting this information, one can put a link to another query to the REST interface or to join that information within its parent object. For more information on how to do this, see the Query Commands section for c:join. http://census.soe.com/get/ps2/characters_item/?character_id=5428010618020694593&c:join=item^show:name.en

query string

Each request for data may take an additional query string that allows one to specify parameters for a particular query. These take the standard form of "field=value". Multiple values may be provided separated by the ampersand ("&") character. The "field" portion of a query string corresponds to a particular field within a particular object within the collection. Please refer to the game specific documentation for a description of available fields.

If the field has a hierarchy, it can be referenced using a dot (".") notation. For example, considering the following data:

item_list: [
	{
		name: {
			en: "Mag-Cutter"
		},
		faction_id: "2",
		image_path: "/files/ps2/images/static/963.png",
		item_id: "1"
	}
],

In order to find all items that have the value "Force-Blade" within name.en, one would use the following query string:

?name.en=Force-Blade
http://census.soe.com/get/ps2/item?name.en=Force-Blade

If multiple search conditions are provided within the query string, they will be combined as a Boolean 'AND' operation. For instance, consider the following values within the following query string:

?field=]10&field=[50

This request would return data where the value of the "field" attribute was between 10 and 50 (inclusively).


A regex search can be combined with c:exactMatchFirst=true in order to show exact matches at the top of the result list. This is useful for character name searches:

http://census.soe.com/s:example/get/dcuo/character?name=*joe&c:case=false&c:show=name,character_id&c:limit=10&c:exactMatchFirst=true

search modifier

A modifier may be used in front of the value portion of the Query String to further enhance the results provided. Only one modifier may be used - the second modifier character would be considered to be part of the value.

Supported Modifier Description
< Values that are "less than" to the attributeValue
[ Values that are "less than or equal" to the attributeValue
> Values that are "greater than" the attributeValue
] Values that are "greater than or equal" the attributeValue
^ Values that start with a string in the attributeValue (like 'value%')
* Values that contain a string in the attributeValue (like '%value%')
! Values that do NOT have the given attributeValue

Query Commands

A Query Command is a particular query string that instructs the REST service on how to organize the results that are to be returned. These are provided as query string attributes but are namespaced with "c:" to distinguish them from a search on a particular field. Depending on the query, not all of these commands may be implemented.

Command Example Description
c:show c:show=field,field Only include the provided fields from the object within the result (multiple field names separated by a comma).
c:hide c:hide=field,field Include all field except the provided fields from the object within the result (multiple field names separated by a comma).
c:sort c:sort=field,field:1,field:-1 Sort the results by the field(s) provided (multiple field names separated by a comma). The value after the : is the sort direction.
c:has c:has=field Include objects where the specified field exists, regardless of the value within that field (multiple field names separated by a comma).
c:resolve c:resolve=field,field "Resolve" information by merging data from another collection and include the detailed object information for the provided fields from the object within the result (multiple field names separated by a comma).
*Please note that the resolve will only function if the initial query contains the field to be resolved on. For instance, resolving leader on outfit requires that leader_character_id be in the initial query.
c:case c:case=true Set whether a search should be case-sensitive, c:case=true means case-sensitive. true is the default. Note that using this command may slow down your queries. If a lower case version of a field is available use that instead for faster performance.
c:limit c:limit=20 Limit the results to at most N objects.
c:limitPerDB c:limitPerDB=20 Limit the results to at most (N * number of databases) objects. *The data type ps2/character is distributed randomly across 20 databases. Using c:limitPerDb will have more predictable results on ps2/character than c:limit will.
c:start c:start=10 Start with the Nth object within the results of the query. *Please note that c:start will have unusual behavior when querying ps2/character which is distributed randomly across 20 databases.
c:includeNull c:includeNull=true Include NULL values in the result. By default this is false. For example, if the name.fr field of a vehicle is NULL the field name.fr will not be included in the response by default. Add the c:includeNull=true command if you want the value name.fr : NULL to be returned in the result.
*Please note this command will not be applied to all collections until ps2:v2.
c:lang c:lang=en For internationalized strings, remove all translations except the one specified.
c:join c:join=characters_world Meant to replace c:resolve, useful for dynamically joining (resolving) multiple data types in one query. See below for details.
c:tree c:tree=type_id^prefix:type_^list:1 Useful for rearranging lists of data into trees of data. See below for details.
c:timing c:timing=true Shows the time taken by the involved server-side queries and resolves.
c:exactMatchFirst c:exactMatchFirst=true When using a regex search (=^ or =*) c:exactMatchFirst=true will cause exact matches of the regex value to appear at the top of the result list despite the value of c:sort.
c:distinct c:distinct=max_stack_size Get the distinct values of the given field. For example to get the distinct values of ps2.item.max_stack_size use http://census.soe.com/get/ps2/item?c:distinct=max_stack_size. Results are capped at 20,000 values.
c:retry c:retry=false If true, query will be retried one time. Default value is true. If you prefer your query to fail quickly pass c:retry=false.

Using c:show to filter returned data

It is often useful to get only a portion of the total data available for a particular collection. In this case, one can specifically ask for information using the c:show query command:

http://census.soe.com/get/ps2:v2/character/?character_id=5428010618020694593&c:show=name,faction_id,battle_rank

"character_list": [

	{
		"name": {
			"first": "Dreadnaut",
			"first_lower": "dreadnaut"
		},
		"battle_rank": {
			"percent_to_next": "0",
			"value": "100"
		},
		"faction_id": "1"
	}

]

Using c:resolve to join collections

*Note that the new c:join command can do anything c:resolve can do and more! c:join described below.

Census provides the c:resolve command in order to join the queried collection with another related collection or collections.

Say you wanted to get the names of all the items owned by a character. You could make this query to get all the item ids for a given character id: http://census.soe.com/get/ps2:v2/characters_item?character_id=5428010618020694593&c:limit=5000. Using these ids you could make a second query to get the names of those items: http://census.soe.com/get/ps2:v2/item?item_id=7,13,17,24,28,60&c:show=name.en (not all 2000 ids listed for brevity). Doing 3 queries to get a character, his item ids, and then the names of those items is not exactly simple. In order to simplify the process you can use the predefined resolves.

To find the list of resolves available on a collection look at the section of that collection under http://census.soe.com/get/ps2:v2/

{
	"name": "character",
	"count": 6279787,
	"hidden": false,
	"resolve_list": [
		"item",
		"item_full",
		"profile",
		"faction",
		"stat",
		"stat_by_faction",
		"weapon_stat",
		"weapon_stat_by_faction",
		"stat_history",
		"online_status",
		"friends",
		"world",
		"outfit",
		"outfit_member",
		"outfit_member_extended",
		"currency"
	]
}

What each resolve does can be found by experimenting. The 'item' resolve joins to 'characters_item' giving you a list of 'item_id', 'stack_count', etc. The 'item_full' resolve joins first to the 'characters_item' collection and then again to the 'item' collection. Since the returned document would be very large let's limit what fields are returned from the resolve using parentheses and listing the fields we want shown: http://census.soe.com/get/ps2:v2/character/?character_id=5428010618020694593&c:resolve=item_full(name.en,description.en)

To restrict the visible fields from the resolved collection, they can be specified within parentheses (as displayed with name.en,description.en).

Using c:join to join collections dynamically

Meant to replace c:resolve, useful for resolving or joining multiple data types in one query. Think of it as a scriptable c:resolve- c:join can do everything c:resolve does plus more, since it does not have to be configured into the API. The join is made up of key value pairs key:value^key:value etc. Each value may be top-comma delimited key:value'value^key:value etc.

Possible keys are:

Key Description
type The collection name to join to (type: is optional on this one).
on The field on this type to join on, i.e. item_id. Will default to {this_type}_id or {other_type}_id if not provided.
to The field on the joined type to join to, i.e. attachment_item_id. Will default to on if on is provide, otherwise will default to {this_type}_id or {other_type}_id if not provided.
list 0 if joined data is not a list, 1 if it is a list. Defaults to 0- not a list.
show Single quote (top comma) delimited list of fields to show
hide Single quote (top comma) delimited list of fields to hide
inject_at The field name where the joined data should be injected into the returned document.
terms Filter terms for the join query. Multiple expressions can be divided by the ' character. For example: http://census.soe.com/get/ps2/item_attachment?c:limit=100&c:join=item^terms:faction_id=1'skill_set_id=129
outer 1 if you wish to do an outer join (include non-matches), 0 if you wish to do an inner join (exclude non-matches). Defaults to 1- do an outer join, include non-matches.

c:join=type:{other_type}^on:{this_type_field}^to:{other_type_field}^list:{0|1}^show:{field}'{field}^hide:{field}'{field}^inject_at:{inject_at_field_name}^terms:{x=1}

Multiple joins can be used comma-delimited. c:join=join1,join2,join3

A join can be nested by using parens, i.e. c:join=join1...(join1a...(join1b...))

Examples:

Output Query
Join an item to profiles that can use it http://census.soe.com/get/ps2:v2/item?item_id=26003&c:join=type:profile^list:1^inject_at:profile^show:name.en
Join an item to attachments to item details http://census.soe.com/get/ps2:v2/item?item_id=26003&c:join=item_attachment^list:1^inject_at:attachments^hide:item_id(item^on:attachment_item_id^to:item_id^hide:item_id)
Join an item to weapon datasheet, primary fire mode and secondary fire mode http://census.soe.com/get/ps2:v2/item?item_id=26003&c:join=weapon_datasheet^inject_at:weapon.datasheet,primary_fire_mode^inject_at:weapon.primary_fire_mode,secondary_fire_mode^inject_at:weapon.secondary_fire_mode
Join a zone to map regions to map hexes http://census.soe.com/get/ps2:v2/zone/?zone_id=2&c:join=map_region^list:1^inject_at:regions^hide:zone_id(map_hex^list:1^inject_at:hex^hide:zone_id'map_region_id)
Join a zone to map regions excluding warp gates which have facility type 7 http://census.soe.com/get/ps2:v2/zone/?zone_id=2&c:join=map_region^list:1^inject_at:regions^hide:zone_id^terms:facility_type_id=!7
Join a characters item list to item showing the name http://census.soe.com/get/ps2:v2/characters_item?character_id=5428010618015189713&c:join=item^inject_at:weapons^terms:item_type_id=26^show:name&c:lang=en
Join a characters item list to item showing the name removing non-matching elements from the original query (not an outer join) http://census.soe.com/get/ps2:v2/characters_item?character_id=5428010618015189713&c:join=item^inject_at:weapons^terms:item_type_id=26^outer:0^show:name&c:lang=en

Using c:tree to reformat lists into trees

Useful for rearranging lists of data into trees of data. The tree is made up of key value pairs key:value^key:value etc. Each value may be top-comma delimited key:value'value^key:value etc.

Possible keys are:

Key Description
field The field to remove and use as in the data structure, or tree.
list 0 if tree data is not a list, 1 if it is a list. Defaults to 0.
prefix A prefix to add to the field value to make it more readable. For example, if the field is "faction_id" and prefix is "f_", path will be f_1, f_2, f_3 etc.
start Used to tell the tree where to start. By default, the list of objects at the root will be formatted as a tree.

Examples:

Organize a list of vehicles by type:

http://census.soe.com/get/ps2:v2/vehicle?c:limit=500&c:tree=type_id^prefix:type_^list:1&c:lang=en

Organize zones, map_regions, map_hexes by facility_type:

http://census.soe.com/get/ps2:v2/zone/?zone_id=2&c:join=map_region^list:1^inject_at:regions^hide:zone_id(map_hex^list:1^inject_at:hex^hide:zone_id'map_region_id)&c:tree=start:regions^field:facility_type^list:1&c:lang=en

Item Icons

Items have an icon_id field that can be used to get an image of that item: https://census.soe.com/s:example/get/ps2:v2/item/?item_id=7256&c:show=name.en,image_id,image_path shows the image_id is 5391 for item 7256 and the path is /files/ps2/images/static/5391.png. Here is the icon: https://census.soe.com/files/ps2/images/static/5391.png

Dates / Timestamps

Many collections have date / timestamp fields. The date is UTC (Coordinated Universal Time) timezone. The timestamp is seconds since midnight, January 1st 1970 UTC. We try to provide both a date and a timestamp representing the same value--such as times.last_save and times.last_save_date on the ps2/character collection. In some cases it may be faster to query by timestamp rather than date, or vice versa, depending on which is the native representation.

Exceptions/Limitations

"Special" PS2 Collections

Not all collections behave the same way due to technical limitations. Here is a list of the collections that only support a subset of the Census query API.

*Note: c:resolve may not be supported by the collections below. Refer to the list of resolves at http://census.soe.com/get/ps2:v2/

Collection Limitations
map Can only be queried by 'world_id = x' and 'zone_ids = x,y,z...'. None of the 'c:' commands are supported (except c:join, c:tree). Only 'get' is supported, 'count' is not.
characters_world Can only be queried by 'character_id = x,y,z...' or equivalently 'id = x,y,z...'. None of the 'c:' commands are supported (except c:join, c:tree). Only 'get' is supported, 'count' is not.
characters_online_status Can only be queried by 'character_id = x,y,z...' or equivalently 'id = x,y,z...'. None of the 'c:' commands are supported (except c:join, c:tree). Only 'get' is supported, 'count' is not.
characters_friend Can only be queried by 'character_id = x,y,z...' or equivalently 'id = x,y,z...'. None of the 'c:' commands are supported (except c:join, c:tree). Only 'get' is supported, 'count' is not.
leaderboard Can only be queried by 'name = x' (required), 'period = x' (required), 'world = [world_id]' (optional). Possible values for name are: Kills, Score, Time, Deaths. Possible value for period are: Forever, Monthly, Weekly, Daily, OneLife. The only 'c:' commands supported are c:start and c:limit (also c:join, c:tree). Only 'get' is supported, 'count' is not.
characters_leaderboard Limitations are the same as those for leaderboard except 'character_id = x,y,z...' or equivalently 'id = x,y,z...' are used to limit the characters returned. Please note that only the top 10,000 characters are in the leaderboard data, many characters will not have a leaderboard row. Only 'get' is supported, 'count' is not.
event Can only be queried by before, after and type. 'before = [timestamp]', 'after = [timestamp]'. The default value of after is 0. The after query field is provided for polling purposes. The before query field can be used to pull all rows by stepping through them backwards. 'type = [BATTLE_RANK | ITEM | ACHIEVEMENT | DEATH | KILL | VEHICLE_DESTROY]'. Multiple types can be provided comma-delimited. The default value type is 'BATTLE_RANK,ACHIEVEMENT,ITEM'. The only 'c:' command supported is c:limit (also c:join, c:tree). Only 'get' is supported, 'count' is not.
characters_event Limitations are the same as those for event except 'character_id = x,y,z...' or equivalently 'id = x,y,z...' are used to limit the rows returned.
world_event Limitations are the same as those for event except 'world_id = x,y,z...' or equivalently 'id = x,y,z...' are used to limit the rows returned.
characters_event_grouped Can only be queried by 'character_id = x,y,z...' or equivalently 'id = x,y,z...' and 'type = [DEATH | KILL]'. Multiple types can be provided comma-delimited. The default value type is 'DEATH,KILL'. The only 'c:' commands supported are c:start and c:limit (also c:join, c:tree). Only 'get' is supported, 'count' is not.
single_character_by_id Can only be queried by 'character_id = x' or equivalently 'id = x'. None of the 'c:' commands are supported (except c:join, c:tree). Only 'get' is supported, 'count' is not.
characters_item Can only be queried by 'character_id = x,y,z...' or equivalently 'id = x,y,z...'. None of the 'c:' commands are supported (except c:join, c:tree).
world Querying by name.en, name.fr, etc is not supported.

Examples

Each example will require an intimate understanding of the data provided by the game team, but the mechanism for requesting the data should be consistent from game to game. To illustrate some common concepts for the API, consider the following requests.

Game-Specific Structure

This section of the document describes the data structure used for PlanetSide 2. This is useful for those starting to use the REST interface. Where possible, it should also establish patterns and best practices for other games providing game data through this service.

A list of collections available for namespace 'ps2' can be found here:

http://census.soe.com/get/ps2:v2/

For example, in the list mentioned above, the "character" collection has the following information:

{
	"name": "character",
	"count": 6279787,
	"hidden": false,
	"resolve_list": [
		"item",
		"item_full",
		"profile",
		"faction",
		"stat",
		"stat_by_faction",
		"weapon_stat",
		"weapon_stat_by_faction",
		"stat_history",
		"online_status",
		"friends",
		"world",
		"outfit",
		"outfit_member",
		"outfit_member_extended",
		"currency"
	]
}

Notice the "resolve_list" shows what fields can be expanded with more information via the c:resolve query string parameter. Here's an example of how you can show the "world_id" information for a character using a resolve:

http://census.soe.com/get/ps2:v2/character/?character_id=5428010618020694593&c:resolve=world&c:show=character_id,world_id. The field 'world_id' refers to the 'world' collection: http://census.soe.com/get/ps2:v2/world?c:limit=100

Example Queries

Output Query
Get Character by ID http://census.soe.com/get/ps2:v2/character/?character_id=5428010618020694593
Get Two Characters by ID http://census.soe.com/get/ps2:v2/character/?character_id=5428010618020694593,5428010618035589553
Get Character by Name http://census.soe.com/get/ps2:v2/character/?name.first_lower=litebrite
Search for Character by partial name (The character_name collection is optimized for name searches) https://census.soe.com/get/ps2:v2/character_name/?name.first_lower=^lite&c:limit=10&c:show=name.first&c:sort=name.first_lower
Get Friends by character ID http://census.soe.com/get/ps2:v2/characters_friend/?character_id=5428010618020694593
Get online status by character ID http://census.soe.com/get/ps2:v2/characters_online_status/?character_id=5428010618020694593
Get Historical Events https://census.soe.com/get/ps2:v2/event/?type=DEATH
The values for type include: BATTLE_RANK, ITEM, ACHIEVEMENT, DEATH and VEHICLE_DESTROY
Get Historical Events by character ID http://census.soe.com/get/ps2:v2/characters_event/?character_id=5428010618020694593&c:limit=10&type=DEATH
The values for type include: BATTLE_RANK, ITEM, ACHIEVEMENT, DEATH, and VEHICLE_DESTROY
Get Historical Events by character ID grouped https://census.soe.com/get/ps2:v2/characters_event_grouped/?character_id=5428010618020694593&c:limit=10
  1. You can sort by group descending
  2. The values for type include: KILL, DEATH
  3. Supports c:limit and c:start commands
Get Historical World Events https://census.soe.com/get/ps2:v2/world_event/?type=FACILITY&c:limit=10
  1. The values for type include: FACILITY. Leave type param off and default will be FACILITY
Get Historical World Events by World ID https://census.soe.com/get/ps2:v2/world_event/?world_id=1&c:limit=10
Get Worlds (aka servers) http://census.soe.com/get/ps2:v2/world/?c:limit=100
Get World by character ID http://census.soe.com/get/ps2:v2/characters_world/?character_id=5428010618020694593
Get Dynamic Zone info by world ID and zone ID http://census.soe.com/get/ps2:v2/map/?world_id=1&zone_ids=2
Get Static Zone info per continent http://census.soe.com/get/ps2:v2/zone/?c:join=map_region^list:1^inject_at:regions^hide:zone_id%28map_hex^list:1^inject_at:hex^hide:zone_id%27map_region_id%29&c:tree=start:regions^field:facility_type^list:1&c:lang=en&c:limit=10
Leaderboards https://census.soe.com/s:example/get/ps2:v2/leaderboard/?name=Kills&period=Forever&c:limit=5
You can use c:resolve to make this call more informative:
https://census.soe.com/s:example/get/ps2:v2/leaderboard/?name=Kills&period=Forever&c:limit=5&c:resolve=character%28name,stats.kills.value,stats.deaths.value,experience.score,times.minutes_played,type.faction,stats.kill_death_ratio.value,stats.hit_count.value,stats.fire_count.value%29
Outfit https://census.soe.com/get/ps2:v2/outfit/?outfit_id=37509488620601345
Resolve leader https://census.soe.com/get/ps2:v2/outfit/?outfit_id=37509488620601345&c:resolve=leader(name,type.faction)
Resolve custom ranks https://census.soe.com/get/ps2:v2/outfit/?name=^666&c:resolve=rank
Resolve member https://census.soe.com/get/ps2:v2/outfit/?outfit_id=37509488620601345&c:resolve=member
Resolve members full character https://census.soe.com/get/ps2:v2/outfit/?name=^Industrial&c:resolve=member_character(name,type.faction)
Find by name http://census.soe.com/get/ps2:v2/outfit/?name=IndustrialLightAndMagic
Find for a given character http://census.soe.com/get/ps2:v2/outfit_member_extended/?character_id=5428010618020694593
Outfit member's online status http://census.soe.com/get/ps2:v2/outfit_member/?outfit_id=37509488620604330&c:limit=100&c:resolve=online_status
All Outfit members online statuses http://census.soe.com/get/ps2:v2/outfit?alias=666&c:resolve=member_online_status

Good luck exploring the API! Remember you can always ask for help on the forums at: http://forums.station.sony.com/soe/index.php?categories/data-api.14/, or by sending an email to data-feedback@soe.sony.com.

PS2 Event Streaming

There is now a WebSocket service streaming live PlanetSide 2 game events! (The only game supported at this time is PS2)

Many developers have been interested in obtaining PlanetSide 2 events in real-time. Polling the ps2/characters_event type is possible, but not preferred. Polling in general should be avoided due to the fact that it causes a high load on the Census API. The PS2 WebSocket service is a far more efficient way to listen for PS2 game events.

Here is a brief description of the current types of events which are available. The list of fields per event can be found below.

Character-centric events:

Event Description
AchievementEarned The given character has earned a new achievement (medal or ribbon)
BattleRankUp The given character has achieved a new battle rank
Death The given character has been killed
ItemAdded A character has been granted a new item
SkillAdded A character has been granted a skill/certification
VehicleDestory A vehicle has been destroyed

World-centric events:

Event Description
ContinentLock A continent has been locked
ContinentUnlock A continent has been unlocked
FacilityControl A facility has changed hands
MetagameEvent A metagame event (alert) has started or ended

Character-centric and world-centric events:

Event Description
PlayerLogin A character has logged into game
PlayerLogout A character has logged out of game

Details

A test page that allows you to subscribe to events and see them printed on the page can be found here.

The endpoint for the WebSocket service is: wss://push.planetside2.com/streaming?service-id=s:[your service id]

Basic Instructions:
  1. Open a websocket connection to wss://push.planetside2.com/streaming?service-id=s:[your service id]. Making the connection will trigger some JSON status messages to be sent down to your client. You can send {"service":"event","action":"help"}} up to the server to receive a rough usage guide.
  2. Subscribe to the types of events you want. This example will subscribe to death/kills for a character...
    {
    	"service":"event",
    	"action":"subscribe",
    	"characters":["5428010618015189713"],
    	"eventNames":["Death"]
    }
    ...and this example will subscribe to login events for world 1...
    {
    	"service":"event",
    	"action":"subscribe",
    	"worlds":["1"],
    	"eventNames":["PlayerLogin"]
    }
    The value "all" can also be used in place of characters, worlds or eventNames values. To save bandwidth, it is recommended that you not use "all" unless it absolutely makes sense for your purposes.
    {
    	"service":"event",
    	"action":"subscribe",
    	"characters":["all"],
    	"worlds":["all"],
    	"eventNames":["all"]
    }
  3. Event messages should begin arriving. Process them as they flow in. Examples:
    {
    	"payload":{
    		"attacker_character_id":"5428010618015189713",
    		"attacker_fire_mode_id":"26103",
    		"attacker_loadout_id":"15",
    		"attacker_vehicle_id":"0",
    		"attacker_weapon_id":"26003",
    		"character_id":"5428168624838258657",
    		"character_loadout_id":"6",
    		"event_name":"Death",
    		"is_headshot":"1",
    		"timestamp":"1392056954",
    		"vehicle_id":"0",
    		"world_id":"1",
    		"zone_id":"2"
    	},
    	"service":"event",
    	"type":"serviceMessage"
    }
    {
    	"payload":{
    		"character_id":"5428057349740067905",
    		"event_name":"PlayerLogin",
    		"timestamp":"1397251287",
    		"world_id":"1"
    	},
    	"service":"event",
    	"type":"serviceMessage"
    }
  4. If your connection is dropped, reconnect and resubscribe to the events you are interested in.

Commands to event service:

"1) Echo test. Echoes back payload. Payload must be a json object.":
	{
		"action":"echo",
		"payload":{
			"test":"test"
		},
		"service":"event"
	},
"2) Subscribe to events. Specify one or more of worlds, characters, eventNames. Calls are additive.":
	{
		"action":"subscribe",
		"characters":[
			"1",
			"2"
		],
		"eventNames":[
			"BattleRankUp",
			"Death",
			"FacilityControl",
			"ItemAdded",
			"MetagameEvent",
			"PlayerLogin",
			"PlayerLogout",
			"SkillAdded",
			"VehicleDestroy"
		],
		"service":"event",
		"worlds":[
			"1",
			"2"
		]
	},
"3) Clear subscribe. Specify one or more of worlds, characters, eventNames.":
	{
		"action":"clearSubscribe",
		"characters":[
			"1",
			"2"
		],
		"eventNames":[
			"BattleRankUp",
			"Death",
			"FacilityControl",
			"ItemAdded",
			"MetagameEvent",
			"PlayerLogin",
			"PlayerLogout",
			"SkillAdded",
			"VehicleDestroy"
		],
		"service":"event",
		"worlds":[
			"1",
			"2"
		]
	},
"4) Clear subscribe on all.":
	{
		"action":"clearSubscribe",
		"all":"true",
		"service":"event"
	},
"5) Get a list of character ids for which events have been encountered recently.":
	{
		"action":"recentCharacterIds",
		"service":"event"
	},
"6) Get a count of character ids for which events have been encountered recently.":
	{
		"action":"recentCharacterIdsCount",
		"service":"event"
	}	

Subscriptions are additive - sending multiple subscribe events add to your total set of subscribed events. Use clearSubscribe to remove from your set of subscribed events.

Example command to subscribe to FacilityControl and MetagameEvent on all worlds:

{
	"service":"event",
	"action":"subscribe",
	"worlds":["1","9","10","11","13","17","18","19","25"],
	"eventNames":["FacilityControl",
	"MetagameEvent"]
}

Example character-level event payloads:

"AchievementEarned":{
		"event_name":"",
		"character_id":"",
		"timestamp":"",
		"world_id":"",
		"achievement_id":"",
		"zone_id":""
	},
"BattleRankUp":{
		"battle_rank":"",
		"character_id":"",
		"event_name":"BattleRankUp",
		"timestamp":"",
		"world_id":"",
		"zone_id":""
	},
"Death":{
		"attacker_character_id":"",
		"attacker_fire_mode_id":"",
		"attacker_loadout_id":"",
		"attacker_vehicle_id":"",
		"attacker_weapon_id":"",
		"character_id":"",
		"character_loadout_id":"",
		"event_name":"Death",
		"is_critical":"",
		"is_headshot":"",
		"timestamp":"",
		"vehicle_id":"",
		"world_id":"",
		"zone_id":""
	},
"FacilityControl":{
		"duration_held":"",
		"event_name":"FacilityControl",
		"facility_id":"",
		"new_faction_id":"",
		"old_faction_id":"",
		"timestamp":"",
		"world_id":"",
		"zone_id":""
	},
"ItemAdded":{
		"character_id":"",
		"context":"",
		"event_name":"ItemAdded",
		"item_count":"",
		"item_id":"",
		"timestamp":"",
		"world_id":"",
		"zone_id":""
	},
"MetagameEvent":{
		"event_name":"MetagameEvent",
		"experience_bonus":"",
		"faction_nc":"",
		"faction_tr":"",
		"faction_vs":"",
		"metagame_event_id":"",
		"metagame_event_state":"",
		"timestamp":"",
		"world_id":"",
		"zone_id":""
	},
"PlayerLogin":{
		"character_id":"",
		"event_name":"PlayerLogin",
		"timestamp":"",
		"world_id":""
	},
"PlayerLogout":{
		"character_id":"",
		"event_name":"PlayerLogout",
		"timestamp":"",
		"world_id":""
	},
"SkillAdded":{
		"character_id":"",
		"event_name":"SkillAdded",
		"skill_id":"",
		"timestamp":"",
		"world_id":"",
		"zone_id":""
	},
"VehicleDestroy":{
		"attacker_character_id":"",
		"attacker_loadout_id":"",
		"attacker_vehicle_id":"",
		"attacker_weapon_id":"",
		"character_id":"",
		"event_name":"VehicleDestroy",
		"facility_id":"",
		"faction_id":"",
		"timestamp":"",
		"vehicle_id":"",
		"world_id":"",
		"zone_id":""
	}
}

Example world-level event payloads:

"ContinentLock":{
		"event_name":"",
		"timestamp":"",
		"world_id":"",
		"zone_id":"",
		"triggering_faction":"",
		"previous_faction":"",
		"vs_population":"",
		"nc_population":"",
		"tr_population":"",
		"metagame_event_id":"",
		"event_type":""
	},
"ContinentUnlock":{
		"event_name":"",
		"timestamp":"",
		"world_id":"",
		"zone_id":"",
		"triggering_faction":"",
		"previous_faction":"",
		"vs_population":"",
		"nc_population":"",
		"tr_population":"",
		"metagame_event_id":"",
		"event_type":""
	},	
"FacilityControl":{
		"event_name":"",
		"timestamp":"",
		"world_id":"",
		"old_faction_id":"",
		"new_faction_id":"",
		"facility_id":"",
		"duration_held":"",
		"zone_id":""
	},
"MetagameEvent":{
		"event_name":"",
		"timestamp":"",
		"world_id":"",
		"experience_bonus":"",
		"faction_nc":"",
		"faction_tr":"",
		"faction_vs":"",
		"metagame_event_id":"",
		"metagame_event_state":"",
		"zone_id":""
	}	
}