Schema

CityIO Data Structure Standard version 2.1 [2018]

cityIO example data format

{"error":"","grid":[[1,0,270],[0,7,270]...[0,8,90],[4,5,90]],"id":"","objects":{},"timestamp":1528717938368,"meta":{"id":"hnkyCam","timestamp":1528717938347,"apiv":2},"header":{"spatial":{"physical_longitude":-71.087264,"cellsize":10,"longitude":-71.087264,"rotation":217,"nrows":5,"latitude":42.360357,"ncols":7,"physical_latitude":42.360357},"name":"virtual_table","block":["type","height","rotation"],"mapping":{"type":{"0":"RL","1":"RM","2":"RS","3":"OL","4":"OM","5":"OS","6":"ROAD"}},"owner":{"name":"Yasushi Sakai","title":"Research Assistant","institute":"MIT Media Lab"}}}

Example of 20 x 20 grid

An example of this version could be found here (online) and here (offline) Note that this format is a minimal protocol. It's ok to have additional information in different tables. fields with * are optional.

Fields

Note: * before a field reflects optional/suggested data

`header` (dictionary)

Contains global data that explains the rest of the data. The header data should be defined for each table, and it is unlikely to change through different states.

`name` (string)

the name of the table. It is the unique key and should match the regex /\w+/g ([0-9a-zA-Z_]).

`spatial` (dictionary)

Contains spatial data that indicates the size, location and the physical resolution of the table data.

row (unsigned short): the number of rows for the table
column (unsigned short): the number of columns for the table
latitude (double): latitude value in decimals. The table's origin is the north west corner.
longitude (double): longitude value in decimals. The table's origin is the north west corner.
physical_latitude (double): longitude of the physical location where the table is situated.
physical_longitude (double): latitude of the physical location where the table is situated.
rotation (double): the clockwise rotation of table in degrees. It is x axis relative to the latitude and longitude.
cellSize (float): the physical size in meters of one cell's edge.

`owner` (array) new*

field indicating the owner of the table. An object that has, "name, title, institution" (all strings).

`block` (array)

An array of strings to indicate the representation of elements in grid. Note it is an array, which is takes account on the order of the information. A Typical block element will start with "type", "height", "rotation", but may different across tables.

`mapping*` (dictionary)

A breakdown containing the necessary mapping of data inside each block. This can be taken as the enumerator field, that you can have a verbose explanation of data types. Often, the "type" field has a mapping of what each block indicates. Note that you can have multiple mappings, for things like mask.

"type": {"0": "RL", "1": "RM", "2": "RS"}

`meta [auto-generated by server]`

users should avoid sending this

meta data reserved for the backend. The server will insert these values.

id (GUID): hash(sha256, overkill) of the grid_data
timestamp (int): UNIX epoch timestamp indicating when the table was received in the server. Milliseconds.
apiv (string): api's version (which is 2)

`grid`(Array or arrays)

The meat part of the data. A grid field could be: "grid":[[1,0,0],[0,7,3]] where:

i[0][0] is the type of the gridcell
i[0][1] is the height of the gridcell
i[0][2] is the rotation of the gridcell

Note: the specifics of each grid object are specified in the block field

The direction of the data is illustrated below. The order of each single block is defined according to the header/block section.

|  0 |  1 |  2 |  3 |
|  4 |  5 |  6 |  7 |
|  8 |  9 | 10 | 11 |
| 12 | 13 | 14 | 15 |

`objects`

Flexible area that you can put whatever field you want. This is a place you want for global variables could potentially change.

Previous API version [should not be used]

version 1.0

This is the 1.0 format the cityIO table (only used in CityScope Volpe for now)

{
    "grid": [{ "type": -2, "x": 13, "y": 0, "rot": 180 }],
    "objects": {
        "toggle4": 0,
        "density": [1, 1, 12, 19, 19, 3],
        "IDMax": 15,
        "pop_young": 0,
        "dockID": -1,
        "slider1": 0.95,
        "dockRotation": 0,
        "pop_old": 0,
        "pop_mid": 0,
        "toggle1": 5,
        "toggle2": 0,
        "toggle3": 0
    },
    "id": "-Kj4L11NdrdbhHCcGGPo",
    "timestamp": 1493664538794
}

The following is an example of the mapping of ids and block representations.

starting from [API v2.0](Data Format) different tables may have different mappings.

Data typeId is a signed int.

the mapping is also provided as a JSON format

Id	Type
-2	MASK_TABLE_BOUNDS
-1	MASK_INTERACTIVE
0	RL
1	RM
2	RS
3	OL
4	OM
5	OS
6	ROAD
7	AMENITIES
8	PARK
9	PARKING