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.
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.soe.com/#service-id.
[edit] API Request
For more in-depth API documentation, visit http://census.soe.com/#url-pattern.
[edit] Requesting Information
All game data requests follow the format: http://census.soe.com/[s:service_id]/format/verb/game/collection[/identifier][?modifier]
All game image request follow the format: http://census.soe.com/[s:service_id]/img/game/collection/identifier[/imageType]
Where:
- service_id is a service id obtained from SOE. See Service ID for more information.
- format is either JSON or XML. Omitting this token defaults to JSON output.
- 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.soe.com/get/ps2-beta/
[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.soe.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] See also
