2. [Get Avatars By Neighborhood](#get-avatars-by-neighborhood)
3. [Get Online Avatars](#get-online-avatars)
4. [Get Avatars By IDs](#get-avatars-by-ids)
5. [Get Avatars By User ID (Protected)](#get-avatars-by-user-id-protected)
2. [Avatar](#avatar)
1. [Get Avatar By ID](#get-avatar-by-id)
2. [Get Avatar By Name](#get-avatar-by-name)
3. [Lots](#lots)
1. [Get Lots By Page](#get-lots-by-page)
2. [Get Lots By Neighborhood](#get-lots-by-neighborhood)
3. [Get Online Lots](#get-online-lots)
4. [Lot](#lot)
1. [Get Lot By ID](#get-lot-by-id)
2. [Get Lot By Location](#get-lot-by-location)
3. [Get Lot By Name](#get-lot-by-name)
5. [Top 100](#top-100)
1. [Get All Top 100s](#get-all-top-100s)
2. [Get Top 100 By Category](#get-top-100-by-category)
6. [Neighborhoods](#neighborhoods)
1. [Get Neighborhoods](#get-neighborhoods)
7. [Neighborhood](#neighborhood)
1. [Get Neighborhood By ID](#get-neighborhood-by-id)
2. [Get Neighborhood By Name](#get-neighborhood-by-name)
8. [Bulletins](#bulletins)
1. [Get Bulletins By Neighborhood](#get-bulletins-by-neighborhood)
2. [Get Bulletins By Type](#get-bulletins-by-type)
9. [Bulletin](#bulletin)
1. [Get Bulletin By ID](#get-bulletin-by-id)
10. [Election](#election)
1. [Get Election By Neighborhood](#get-election-by-neighborhood)
11. [OAuth](#oauth)
1. [Get Token](#get-token)
12. [City](#city)
1. [city.json](#cityjson)
13. [Media](#media)
1. [Get Lot Thumbnail](#get-lot-thumbnail)
3. [Extending The API](#extending-the-api)
4. [Notable Projects Using The API](#notable-projects-using-the-api)
# Overview
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/1/city.json`).
Feel free to update missing/incorrect information by [editing this page](https://github.com/riperiperi/FreeSO/wiki/Public-API/_edit).
**For more information about some of the data returned by the API, please see [Public API Data Definitions](https://github.com/riperiperi/FreeSO/wiki/Public-API-Data-Definitions)**
| `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. |
| `avatarsPerPage` | `integer` (Optional) | The number of avatars to return per page. Default is `100`, max is `500`. |
#### Response
```json
{
"page": 1,
"total_pages": 1,
"total_avatars": 1,
"avatars_on_page": 1,
"avatars": [
{
"avatar_id": 887,
"shard_id": 1,
"name": "burglar cop",
"gender": 0,
"date": 1486420929,
"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",
| `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. |
#### Response
```json
{
"avatars": [
{
"avatar_id": 887,
"shard_id": 1,
"name": "burglar cop",
"gender": 0,
"date": 1486420929,
"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",
| `compact` | `boolean` (Optional) | Compact returns `avatars_online_count` and an empty `avatars` array. Default is false. |
#### Response
```json
{
"avatars_online_count": 1,
"avatars": [
{
"avatar_id": 1,
"name": "burglar cop",
"privacy_mode": 0,
"location": 13828398
}
]
}
```
#### Live Response
<https://api.freeso.org/userapi/avatars/online>
### Get Avatars By IDs
```
/userapi/avatars/?ids={avatarIds}
```
#### Parameters
| Name | Type | Description |
| ---- | ---- | ----------- |
| `avatarIds` | `string` | A list of `avatar_id`s from `fso_avatars` separated by commas. |
#### Response
```json
{
"avatars": [
{
"avatar_id": 887,
"shard_id": 1,
"name": "burglar cop",
"gender": 0,
"date": 1486420929,
"description": " the law is a suggestion\n but its a pretty good one tbh\r\n\r\n -me\r\n\ndont freak out if im just standing there starving im probably developing something worth dying for\n",
Returns an array of the avatars associated with a User ID. Requires a [valid token](#get-token) for authorization.
#### Response
```json
{
"avatars": [
{
"avatar_id": 887,
"shard_id": 1,
"name": "burglar cop",
"gender": 0,
"date": 1486420929,
"description": " the law is a suggestion\n but its a pretty good one tbh\r\n\r\n -me\r\n\ndont freak out if im just standing there starving im probably developing something worth dying for\n",
"current_job": 5,
"mayor_nhood": null
}
]
}
```
#### Live Response
Send a GET request using something like [Postman](https://www.getpostman.com/downloads/) with an authorization header of type bearer token and a [valid token](#get-token) to <https://api.freeso.org/userapi/user/avatars>
## Avatar
### Get Avatar By ID
```
/userapi/avatars/{avatarId}
```
#### Parameters
| Name | Type | Description |
| ---- | ---- | ----------- |
| `avatarId` | `integer` | The value of `avatar_id` in `fso_avatars` for an avatar. |
#### Response
```json
{
"avatar_id": 887,
"shard_id": 1,
"name": "burglar cop",
"gender": 0,
"date": 1486420929,
"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
}
```
#### Live Response
<https://api.freeso.org/userapi/avatars/887>
### Get Avatar By Name
```
/userapi/city/{shardId}/avatars/name/{avatarName}
```
#### Parameters
| Name | Type | Description |
| ---- | ---- | ----------- |
| `shardId` | `integer` | The value of `shard_id` in `fso_shards` for a city. This will likely always be `1`. |
| `avatarName` | `string` | The value of `name` in `fso_avatars` for an avatar. **Warning: Make sure this string is URL encoded** |
#### Response
```json
{
"avatar_id": 887,
"shard_id": 1,
"name": "burglar cop",
"gender": 0,
"date": 1486420929,
"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",
| `shardId` | `integer` | The value of `shard_id` in `fso_shards` for a city. This will likely always be `1`. |
#### Response
```json
{
"neighborhoods": [
{
"neighborhood_id": 54,
"name": "D.A.M.N.",
"description": "Fully known as the D.A.D.D.I. And M.O.M.I. Neighborhood. The home of the Sunrise Crater government, who have the final say over all decisions and neighborhoods despite never being elected.\r\n\r\nFamous for its huge annual events, incredibly high rate of arson and non-existent firefighter response, this location has a higher mortality rate for visitors than any other mountain on the planet.",
| `nhoodId` | `integer` | The value of `neighborhood_id` in `fso_neighborhoods` for a neighborhood. |
#### Response
```json
{
"neighborhood_id": 54,
"name": "D.A.M.N.",
"description": "Fully known as the D.A.D.D.I. And M.O.M.I. Neighborhood. The home of the Sunrise Crater government, who have the final say over all decisions and neighborhoods despite never being elected.\r\n\r\nFamous for its huge annual events, incredibly high rate of arson and non-existent firefighter response, this location has a higher mortality rate for visitors than any other mountain on the planet.",
"color": 0,
"town_hall_id": 6634,
"icon_url": null,
"mayor_id": 108523,
"mayor_elected_date": 1565012163,
"election_cycle_id": null
}
```
#### Live Response
<https://api.freeso.org/userapi/neighborhoods/54>
### Get Neighborhood By Name
```
/userapi/neighborhoods/{nhoodName}
```
#### Parameters
| Name | Type | Description |
| ---- | ---- | ----------- |
| `nhoodName` | `string` | The value of `name` in `fso_neighborhoods` for a neighborhood. **Warning: Make sure this string is URL encoded** |
#### Response
```json
{
"neighborhood_id": 54,
"name": "D.A.M.N.",
"description": "Fully known as the D.A.D.D.I. And M.O.M.I. Neighborhood. The home of the Sunrise Crater government, who have the final say over all decisions and neighborhoods despite never being elected.\r\n\r\nFamous for its huge annual events, incredibly high rate of arson and non-existent firefighter response, this location has a higher mortality rate for visitors than any other mountain on the planet.",
| `nhoodId` | `integer` | The value of `neighborhood_id` in `fso_neighborhoods` for a neighborhood. |
| `bulletinType` | `integer` | `0` - Mayor posts, `1` - System messages, `2` - Community posts. **Warning: System messages may reference game assets instead of providing a human readable bulletin.** |
Send a `form-data` POST containing the parameters using something like [Postman](https://www.getpostman.com/downloads/) to <https://api.freeso.org/userapi/oauth/token>
## City
### city.json
```
/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 migrate existing projects to use them.
#### Parameters
| Name | Type | Description |
| ---- | ---- | ----------- |
| `shardId` | `integer` | The value of `shard_id` in `fso_shards` for a city. This will likely always be `1`. |
#### Response Description
| 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). |
#### Response
```json
{
"names": [
"Sunrise Crater Town Hall",
"M.O.M.I. Headquarters"
],
"reservedLots": [
13828397,
13828398
],
"activeLots": [
13828397
],
"onlineCount": [
10
]
}
```
#### Live Response
<https://api.freeso.org/userapi/city/1/city.json>
## Media
### Get Lot Thumbnail
```
/userapi/city/{shardId}/{lotLocation}.png
```
#### Parameters
| 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. |
If the API is missing some data you think would be beneficial, you can open an [issue](https://github.com/riperiperi/FreeSO/issues) to discuss it, but the best solution would be to submit a [pull request](https://github.com/riperiperi/FreeSO/pulls) yourself. [This PR](https://github.com/riperiperi/FreeSO/pull/152) by [@Cowplant-Simmer-Collin](https://github.com/Cowplant-Simmer-Collin) is a great example of how to add new API features.
# Notable Projects Using The API
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.
