Public API
TODO - ToC
##### Table of Contents
[Headers](#headers)
[Emphasis](#emphasis)
...snip...
<a name="headers"/>
## Headers
This document describes the resources that make up FreeSO's public API. It is currently in beta and subject to change at any time.
The live server API, api.freeso.org can be accessed via HTTP or HTTPS. You should use HTTPS to access the live server API unless absolutely necessary. This documentation will include examples using the live server, but if you are building and testing new API features in a dev build, just replace api.freeso.org with whatever your API URL is (ex. localhost:9000/userapi/city/001/city.json).
/userapi/city/{shardId}/{lotLocation}.png
Returns a lot's thumbnail image.
| Name | Type | Description |
|---|---|---|
shardId |
integer |
The value of shard_id in fso_shards for a city. This will likely always be 1. |
lotLocation |
integer |
The location of a reserved lot. |
https://api.freeso.org/userapi/city/1/13828397.png
/userapi/city/{shardId}/city.json
Returns every reserved lot, its name, online lots, and all online lot's populations.
Warning: This endpoint may be deprecated in favor of recent API additions. You should only use this endpoint if you need every reserved lot.
| Name | Type | Description |
|---|---|---|
shardId |
integer |
The value of shard_id in fso_shards for a city. This will likely always be 1. |
| Name | Type | Description |
|---|---|---|
names |
array[string] |
An array of every lot name in alphabetical order. |
reservedLots |
array[integer] |
An array of every reserved lot's location (the index matches up with the names array). |
activeLots |
array[integer] |
An array of lot locations for lots that are open. |
onlineCount |
array[integer] |
An array of lot population for lots that are open (the index matches up with the activeLots array). |
{
"names": [
"Sunrise Crater Town Hall",
"M.O.M.I. Headquarters"
],
"reservedLots": [
13828397,
13828398
],
"activeLots": [
13828397
],
"onlineCount": [
10
]
}https://api.freeso.org/userapi/city/1/city.json
/userapi/city/{shardId}/avatars/page/{pageNum}
| Name | Type | Description |
|---|---|---|
shardId |
integer |
The value of shard_id in fso_shards for a city. This will likely always be 1. |
pageNum |
integer |
The page of avatars you'd like to request. pageNum 1 will give you the total number of pages. |
{
"page": 1,
"total_pages": 1,
"total_avatars": 1,
"avatars_on_page": 1,
"avatars": [
{
"avatar_id": 1,
"shard_id": 1,
"name": "burglar cop",
"gender": 0,
"date": 1483660800,
"description": " the law is a suggestion\r\n but its a pretty good one tbh\r\n\r\n -me\r\n\r\ndont freak out if im just standing there starving im probably developing something worth dying for\r\n",
"current_job": 5,
"mayor_nhood": null
}
]
}https://api.freeso.org/userapi/city/1/avatars/page/1
/userapi/city/{shardId}/avatars/neighborhood/{nhoodId}
Get all avatars that live in a neighborhood.
| Name | Type | Description |
|---|---|---|
shardId |
integer |
The value of shard_id in fso_shards for a city. This will likely always be 1. |
nhoodId |
integer |
The value of neighborhood_id in fso_neighborhoods for a neighborhood. |
{
"avatars": [
{
"avatar_id": 1,
"shard_id": 1,
"name": "burglar cop",
"gender": 0,
"date": 1483660800,
"description": " the law is a suggestion\r\n but its a pretty good one tbh\r\n\r\n -me\r\n\r\ndont freak out if im just standing there starving im probably developing something worth dying for\r\n",
"current_job": 5,
"mayor_nhood": null
}
]
}https://api.freeso.org/userapi/city/1/avatars/neighborhood/54
/userapi/avatars/online
{
"avatars_online_count": 1,
"avatars": [
{
"avatar_id": 1,
"name": "burglar cop",
"privacy_mode": 0,
"location": 13828398
}
]
}https://api.freeso.org/userapi/avatars/online
If the API is missing some data you think would be beneficial, you can open an issue to discuss it, but the best solution would be to submit a pull request yourself. This PR by @Cowplant-Simmer-Collin is a great example of how to add new API features.
The following are popular projects known to consume the API. They should be notified of any breaking changes. Feel free to add your own to this list.