Skip to content

Public API

Jump to bottom Edit New page
dotequals edited this page Aug 13, 2019 · 19 revisions
Table of Contents
  1. Overview
  2. API
    1. Avatars
      1. Get Avatars By Page
      2. Get Avatars By Neighborhood
      3. Get Online Avatars
    2. Avatar
      1. Get Avatar By ID
      2. Get Avatar By Name
    3. Lots
      1. Get Lots
      2. Get Lots By Neighborhood
      3. Get Online Lots
    4. Lot
      1. Get Lot By ID
      2. Get Lot By Location
      3. Get Lot By Name
    5. Top 100
      1. Get All Top 100s
      2. Get Top 100 By Category
    6. Neighborhoods
      1. Get Neighborhoods
    7. Neighborhood
      1. Get Neighborhood By ID
      2. Get Neighborhood By Name
    8. Bulletins
      1. Get Bulletins By Neighborhood
      2. Get Bulletins By Type
    9. Bulletin
      1. Get Bulletin By ID
    10. Election
      1. Get Election By Neighborhood
    11. City
      1. city.json
    12. Media
      1. Get Lot Thumbnail
  3. Extending The API
  4. 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).

API

Avatars

Get Avatars By Page

/userapi/city/{shardId}/avatars/page/{pageNum}

Parameters

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.

Response

{
  "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",
      "current_job": 5,
      "mayor_nhood": null
    }
  ]
}

Live Response

https://api.freeso.org/userapi/city/1/avatars/page/1

Get Avatars By Neighborhood

/userapi/city/{shardId}/avatars/neighborhood/{nhoodId}

Parameters

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.

Response

{
  "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",
      "current_job": 5,
      "mayor_nhood": null
    }
  ]
}

Live Response

https://api.freeso.org/userapi/city/1/avatars/neighborhood/54

Get Online Avatars

/userapi/avatars/online

Response

{
  "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

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

{
  "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

{
  "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/city/1/avatars/burglar%20cop

Lots

Get Lots

Use city.json to retrieve all lots.

Get Lots By Neighborhood

/userapi/city/{shardId}/lots/neighborhood/{nhoodId}

Parameters

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.

Response

{
  "lots": [
    {
      "location": 13828398,
      "name": "M.O.M.I. Headquarters",
      "description": "",
      "category": 5,
      "neighborhood_id": 54,
      "avatars_in_lot": 0
    }
  ]
}

Live Response

https://api.freeso.org/userapi/city/1/lots/neighborhood/54

Get Online Lots

/userapi/city/{shardId}/online

Parameters

Name Type Description
shardId integer The value of shard_id in fso_shards for a city. This will likely always be 1.

Response

{
  "total_lots_online": 1,
  "total_avatars_in_lots_online": 1,
  "lots": [
    {
      "location": 13828398,
      "name": "M.O.M.I. Headquarters",
      "description": "",
      "category": 5,
      "neighborhood_id": 54,
      "avatars_in_lot": 0
    }
  ]
}

Live Response

https://api.freeso.org/userapi/city/1/lots/online

Lot

Get Lot By ID

/userapi/lots/{lotId}

Parameters

Name Type Description
lotId integer The value of lot_id in fso_lots for a lot.

Response

{
  "shard_id": 1,
  "owner_id": 887,
  "roommates": [
    887
  ],
  "name": "M.O.M.I. Headquarters",
  "description": "",
  "location": 13828398,
  "neighborhood_id": 54,
  "created_date": 1518961270,
  "category": 5,
  "skill_mode": 0,
  "admit_mode": 1
}

Live Response

https://api.freeso.org/userapi/lots/6634

Get Lot By Location

/userapi/city/{shardId}/lots/location/{locationId}

Parameters

Name Type Description
shardId integer The value of shard_id in fso_shards for a city. This will likely always be 1.
locationId integer The value of location in fso_lots for a lot.

Response

{
  "shard_id": 1,
  "owner_id": 887,
  "roommates": [
    887
  ],
  "name": "M.O.M.I. Headquarters",
  "description": "",
  "location": 13828398,
  "neighborhood_id": 54,
  "created_date": 1518961270,
  "category": 5,
  "skill_mode": 0,
  "admit_mode": 1
}

Live Response

https://api.freeso.org/userapi/city/1/lots/location/13828398

Get Lot By Name

/userapi/city/{shardId}/lots/name/{lotName}

Parameters

Name Type Description
shardId integer The value of shard_id in fso_shards for a city. This will likely always be 1.
lotName string The value of name in fso_lots for a lot. Warning: Make sure this string is URL encoded

Response

{
  "shard_id": 1,
  "owner_id": 887,
  "roommates": [
    887
  ],
  "name": "M.O.M.I. Headquarters",
  "description": "",
  "location": 13828398,
  "neighborhood_id": 54,
  "created_date": 1518961270,
  "category": 5,
  "skill_mode": 0,
  "admit_mode": 1
}

Live Response

https://api.freeso.org/userapi/city/1/lots/name/M.O.M.I.%20Headquarters

Top 100

Get All Top 100s

/userapi/city/{shardId}/lots/top100/all

Parameters

Name Type Description
shardId integer The value of shard_id in fso_shards for a city. This will likely always be 1.

Response

{
  "lots": [
    {
      "category": 5,
      "rank": 1,
      "shard_id": 1,
      "lot_name": "M.O.M.I. Headquarters",
      "lot_location": 13828398
    }
  ]
}

Live Response

https://api.freeso.org/userapi/city/1/lots/top100/all

Get Top 100 By Category

/userapi/city/{shardId}/lots/top100/category/{lotCategory}

Parameters

Name Type Description
shardId integer The value of shard_id in fso_shards for a city. This will likely always be 1.
lotCategory integer The category type (1-11)

Response

{
  "lots": [
    {
      "category": 5,
      "rank": 1,
      "shard_id": 1,
      "lot_name": "M.O.M.I. Headquarters",
      "lot_location": 13828398
    }
  ]
}

Live Response

https://api.freeso.org/userapi/city/1/lots/top100/category/5

Neighborhoods

Get Neighborhoods

/userapi/city/{shardId}/neighborhoods/all

Parameters

Name Type Description
shardId integer The value of shard_id in fso_shards for a city. This will likely always be 1.

Response

{
  "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.",
      "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/city/1/neighborhoods/all

Neighborhood

Get Neighborhood By ID

/userapi/neighborhoods/{nhoodId}

Parameters

Name Type Description
nhoodId integer The value of neighborhood_id in fso_neighborhoods for a neighborhood.

Response

{
  "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

{
  "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/D.A.M.N.

Bulletins

Get Bulletins By Neighborhood

/userapi/neighborhood/{nhoodId}/bulletins

Parameters

Name Type Description
nhoodId integer The value of neighborhood_id in fso_neighborhoods for a neighborhood.

Response

{
  "bulletins": [
    {
      "bulletin_id": 241,
      "neighborhood_id": 54,
      "avatar_id": 887,
      "title": "Why are we still here?",
      "body": "Just to Suffer?",
      "date": 1561318161,
      "flags": 0,
      "lot_id": 13828399,
      "type": 0
    }
  ]
}

Live Response

https://api.freeso.org/userapi/neighborhood/54/bulletins

Get Bulletins By Type

/userapi/neighborhood/{nhoodId}/bulletins/type/{bulletinType}

Parameters

Name Type Description
nhoodId integer The value of neighborhood_id in fso_neighborhoods for a neighborhood.
bulletinType integer 0 - Mayor posts, 1 - System messages, 2 - Community posts

Response

{
  "bulletins": [
    {
      "bulletin_id": 241,
      "neighborhood_id": 54,
      "avatar_id": 887,
      "title": "Why are we still here?",
      "body": "Just to Suffer?",
      "date": 1561318161,
      "flags": 0,
      "lot_id": 13828399,
      "type": 0
    }
  ]
}

Live Response

https://api.freeso.org/userapi/neighborhood/1/bulletins/type/0

Bulletin

Get Bulletin By ID

/userapi/neighborhood/{nhoodId}/bulletins/{bulletinId}

Parameters

Name Type Description
nhoodId integer The value of neighborhood_id in fso_neighborhoods for a neighborhood.
bulletinId integer The value of bulletin_id in fso_bulletin_posts for a bulletin.

Response

{
  "bulletin_id": 241,
  "neighborhood_id": 54,
  "avatar_id": 887,
  "title": "Why are we still here?",
  "body": "Just to Suffer?",
  "date": 1561318161,
  "flags": 0,
  "lot_id": 13828399,
  "type": 0
}

Live Response

https://api.freeso.org/userapi/neighborhood/54/bulletins/241

Election

Get Election By Neighborhood

/userapi/neighborhood/{nhoodId}/elections

Parameters

Name Type Description
nhoodId integer The value of neighborhood_id in fso_neighborhoods for a neighborhood.

Response

{
  "current_state": 1,
  "neighborhood_id": 54,
  "start_date": 1565630999,
  "end_date": 1566062999,
  "candidates": []
}
{
  "error": "Election cycle not found"
}

Live Response

https://api.freeso.org/userapi/neighborhood/54/elections

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 only use this endpoint if you need every reserved lot.

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

{
  "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.

Response

M.O.M.I. Headquarters thumbnail

Live Response

https://api.freeso.org/userapi/city/1/13828398.png

Extending The API

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.

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.

Add a custom footer
Add a custom sidebar
Clone this wiki locally