API
The Census API is a collection of data pulled directly from Planetside 2. It contains statistical and character-specific information for all players, server-specific territory status as well as names, descriptions and icons of all items within the game.
NB: On 11 Jun 2013 an email went out about the new version of the API, see Api Updates below
Contents |
[edit] Accessing the API
[edit] Service ID
A Service ID is a string that identifies clients who access the API. It is currently not mandatory to have a Service ID, but is recommended. To obtain a Service ID, visit http://census.daybreakgames.com/#service-id.
[edit] API Request
For more in-depth API documentation, visit http://census.daybreakgames.com/#url-pattern.
[edit] Requesting Information
All game data requests follow the format: http://census.daybreakgames.com/[s:service_id]/format/verb/game/collection[/identifier][?modifier]
All game image request follow the format: http://census.daybreakgames.com/[s:service_id]/img/game/collection/identifier[/imageType]
Where:
- service_id is a service id obtained from Daybreak. See Service ID for more information.
- format is either JSON or XML. Omitting this token defaults to JSON output. For CSV format use a JSON to CSV converter.
- verb informs the API as to what information is requested. There are currently two verbs available:
- get Returns all information that matches the request
- count Returns the total number of objects that match the request
- game selects which game the information is requested. It is currently recommended to use ps2-beta over ps2 as ps2-beta is guaranteed not to change while a final implementation is being finalized.
- collection selects which set of information to pull from. See API/Collections for a list of collections.
- identifier is a collection-specific, optional numeric parameter. Each entry in every collection has a unique unsigned integer number assigned to it. When specifying this parameter, the API will return specific entry correlating this number.
- imageType specifies the type of image
- paperdoll returns a full image of the character
- headshot returns an image of the character from the neck up
- modifier is a string of modifiers and query commands that modify what information is returned.
[edit] Return Information
The API returns all non-image request information in the form of a JSON object. The API returns all image requests in PNG format.
[edit] Collections
A list of each collection with their resolve lists and a brief description is available at API/Collections. The full list of collections is available from the API itself, located at http://census.daybreakgames.com/get/ps2/
[edit] Query Commands and Filtering
| Modifier | Example | Description | Notes |
|---|---|---|---|
| c:start | c:start=10 | Start with the Nth object within the results of the query | |
| c:limit | c:limit=20 | Limit results to N objects. Defaults to 1 when not set. | |
| c:show | c:show=item_list,name.en | Only provides fields from the object within the results. Multiple field separated by a comma. | |
| c:hide | c:hide=daily_stats,monthly_stats | Include all fields in the result except the specified ones. | |
| c:sort | c:sort=field[:1],field | Sort the results by the field(s) provided. Multiple fields separated by a comma. :1 indicates the sort direction. | |
| c:has | c:has=!deleted | Include objects where the specified field exists, regardless of the value within that field. | |
| c:resolve | c:resolve=item_list(name.en,description.en),online_status | Resolve information by merging data from other specified collections. If fields are specified within brackets, only that information will show. | |
| c:case | c:case=true | Set whether a search should be case sensitive. |
[edit] Query Command Modifiers
| Modifier | Description |
|---|---|
| < | Less than |
| [ | Less than or equal |
| > | Greater than |
| ] | Greater than or equal |
| ^ | Start with a string |
| * | String contains |
| ! | Not |
For example, to search for all consumable items use the query: http://census.daybreakgames.com/get/ps2-beta/item/?max_stack_size=>1
[edit] Best practices
When accessing the API, always filter your queries so they only return the data you're interested in. The API will work much faster if it needs to return less data.
Use the c:show and c:hide parameters to do this, and for c:resolve, you can use the format resolvename(resolvefield, resolvefield2, etc)
[edit] API Updates
[edit] ps2:v1
On 11 Jun 2013 an email went out to registered developers announcing "Developer Updates to the Census API for PlanetSide 2!". Contents of that email follow:
We are pleased to let you know that we have just released a new version of the PS2 API. Below is the information on what has changed, why we changed it, and how you will be able to access it.
Why?
In order to make Census more maintainable and accurate, we have implemented a new process to pull data directly from the Game's databases. This replaces the old method of syncing and translating data from the Game DB's into a non-relational DB. The new method will ensure that the data you are seeing in Census is the same exact data that the Game is using.
This initial release addresses the Character data specifically; all Static data (i.e. items, vehicles, etc.) remain in the non-relational DB; our next release version will encompass the transition of Static data to pull from the Game DB as well.
Keep in mind that caching of the Character data by the Game may cause Census data to be delayed up to 60 minutes. However, if you experience delays longer than this, please let us know so that we can investigate and minimize the delay.
The performance of the new system should be on par with the old system, if not faster in many cases.
New Namespace
- We have unlocked the new namespace; 'ps2' now replaces the existing 'ps2-beta'. For example: http://census.daybreakgames.com/get/ps2/
- 'ps2-beta' will continue to remain active for a short time; but once 'ps2' becomes stable, we will be transitioning it out and it will be removed completely. We will give ample notice before that happens.
Versioning
- In order to support on-going and future development we've come up with a versioning scheme. This will allow 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 we release will always be mapped to 'ps2' i.e. http://census.daybreakgames.com/get/ps2:v1/ is exactly the same as http://census.daybreakgames.com/get/ps2/. Use 'ps2' if you want to guarantee that you are always pointing at the latest and greatest.
New Character Format
- One of the biggest changes is the new formatting of the Character record. The Character record has been normalized/split into multiple types(this normalization was driven by the underlying database format.) :
- character
- characters_currency
- characters_stat
- characters_stat_by_faction
- characters_stat_history
- characters_weapon_stat
- characters_weapon_stat_by_faction
- characters_item.
- http://census.daybreakgames.com/get/ps2/ displays the list of all types available including the names of any resolves that can be used against that type. We have attempted to provide all the resolves necessary to supply data similar to 'ps2-beta': http://census.daybreakgames.com/get/ps2/character/5428013610387904065?c:resolve=currency,stat,stat_by_faction,weapon_stat,weapon_stat_by_faction,stat_history,item_full(name.en)
- 'single_character_by_id' has been added as a convenience (and optimized for speed). Returns a single character with Items/Stats already resolved: http://census.daybreakgames.com/get/ps2/single_character_by_id/?id=5428010618020696081
Expected Changes for next Version
- Static data types (items, vehicles, etc) will be pulled from relational databases as the character type did.
- A standard naming convention will be used for ids. Item will have item_id rather than id. Character will have character_id rather than id. This will help support dynamic joining of data types.
- Dynamic joining of data types. We plan to replace the resolve functionality with a more flexible join functionality. The join functionality will allow the query to specify what types to join and on what fields as well as what to show and any filtering terms. For example: join vehicle to items based on attachment id and only show items which type Weapon.
[edit] See also
