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. Lots
      1. Get All Lots
      2. Get All Lots By Neighborhood
      3. Get All Online Lots
    2. Lot
    3. Avatars
      1. Get All Avatars By Page
      2. Get All Avatars By Neighborhood
      3. Get All Online Avatars
    4. Top 100
    5. Neighborhoods
    6. Neighborhood
    7. Bulletins
    8. Bulletin
    9. Elections
    10. City
      1. city.json
    11. 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

Lots

Get All Lots

Use city.json to retrieve all lots.

Get All 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 All 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

Avatars

Get All 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": 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
    }
  ]
}

Live Response

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

Get All 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": 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
    }
  ]
}

Live Response

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

Get All 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

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

Sunrise Crater Town Hall thumbnail

Live Response

https://api.freeso.org/userapi/city/1/13828397.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