Data Presentation
API Design
On the location search page, users only need to define a simple JSON format to display location data on the map. We have defined the relevant specifications, which are dynamically used in the UI rendering. You just need to follow the specifications during development.
There are two main ways to obtain data sources: open data API and static JSON. Please refer to the detailed explanation for usage.
The complete JSON format is as follows:
JSON
{
"list": [
{
"name": "交通運輸、停車場、充電站",
"places": [
{
"id": "pa-1",
"name": "微笑單車 2.0",
"icon": "",
"agency": "台北市政府交通局",
"type": "交通運輸、停車場、充電站",
"data_type": "api",
"request_url": "https://tcgbusfs.blob.core.windows.net/dotapp/youbike/v2/youbike_immediate.json",
"data_path": "",
"format_fields": {
"id": "sno",
"name": "sna",
"area": "sarea",
"address": "ar",
"lat": "latitude",
"lng": "longitude"
},
"service_infos": [
{
"title": "備註",
"value_fields": [
{
"title": "可借車輛",
"value_field": "available_rent_bikes"
},
{
"title": "可停空位",
"value_field": "available_return_bikes"
}
]
},
{
"title": "更新時間",
"value_field": "updateTime"
}
]
},
{
"id": "pa-3",
"name": "停車場",
"icon": "",
"agency": "台北市停車管理工程處",
"type": "交通運輸、停車場、充電站",
"data_type": "json",
"request_url": "/public/mock/find-place/TCMSV_alldesc.json",
"data_path": "",
"format_fields": {
"id": "id",
"name": "name",
"area": "area",
"address": "address",
"lat": "EntranceCoord.EntrancecoordInfo[0]?.Xcod",
"lng": "EntranceCoord.EntrancecoordInfo[0]?.Ycod"
},
"service_infos": [
{
"title": "概況",
"value_field": "summary"
},
{
"title": "費率",
"value_field": "payex"
}
]
}
]
},
{
"name": "飲水機、公廁、哺集乳室、AED場所",
"places": [
{
"id": "pb-1",
"name": "飲水機/提供飲水店家",
"icon": "/public/images/icon_drinking.svg",
"agency": "台北市政府環境保護局",
"type": "飲水機、公廁、哺集乳室、AED場所",
"data_type": "api",
"request_url": "https://data.taipei/api/v1/dataset/52538305-ed23-490c-8f67-3efff2d777c3?scope=resourceAquire",
"data_path": "result.results",
"format_fields": {
"id": "_id",
"name": "場所名稱",
"area": "行政區",
"address": "場所地址",
"lat": "緯度",
"lng": "經度"
},
"service_infos": [
{
"title": "場所開放時間",
"value_field": "場所開放時間"
},
{
"title": "飲水台數",
"value_field": "飲水台數"
}
]
},
{
"id": "pb-3",
"name": "公廁",
"icon": "/public/images/icon_toilet.svg",
"agency": "",
"type": "飲水機、公廁、哺集乳室、AED場所",
"data_type": "json",
"request_url": "/public/mock/find-place/public_toilet_taipei.json",
"data_path": "",
"format_fields": {
"id": "id",
"name": "name",
"area": "city",
"address": "address",
"lat": "latitude",
"lng": "longitude"
},
"service_infos": [
{
"title": "等級",
"value_field": "grade"
}
]
}
]
}
]
}Data Field Descriptions
Service Map - Data
| Field | Purpose | Example |
|---|---|---|
| name | Service map category, displayed as a header in the map menu | Transportation, Parking, Charging Stations |
| places | Service locations under this category | See table below |
Places
| Field | Purpose | Example |
|---|---|---|
| id | Key | pa-1 |
| name | Service map name | YouBike 2.0 |
| icon | Icon, place image files in the /public/images directory; if empty, no icon will be displayed | /public/images/icon_drinking.svg |
| agency | Service providing agency | Taipei City Government Department of Transportation |
| type | Category to which the map belongs | Transportation, Parking, Charging Stations |
| data_type | Data source format | api or json |
| request_url | Data retrieval URL If json, place the static json file in the /public/mock directory and reference it | api: https://tcgbusfs.blob.core.windows.net/dotapp/youbike/v2/youbike_immediate.json json: /public/mock/find-place/TCMSV_alldesc.json |
| data_path | If the data return value is not an array, specify the path to the data object; if the return value is an array, leave it blank | result.results (i.e., the data object is located in the responseData.result.results array) |
| format_fields | Data field mapping | See table below format_fields |
| service_infos | Detailed data information | See table below service_infos |
Format Fields
This section is mainly used to map fields from different data sources by filling in the field names of the data.
| Field | Purpose | Example |
|---|---|---|
| id | Key | Fill in the field name for the key value in the data Required |
| name | Location name | Fill in the field name for the location name in the data Required |
| area | Location area, e.g., district | Fill in the field name for the location area in the data Required |
| address | Detailed location address | Fill in the field name for the detailed location address in the data Required |
| lat | Latitude | Fill in the field name for the latitude in the data Required; without latitude, the location cannot be plotted on the map |
| lng | Longitude | Fill in the field name for the longitude in the data Required; without longitude, the location cannot be plotted on the map |
Service Infos
| Field | Purpose | Example |
|---|---|---|
| title | Title of the detailed information | Remarks |
| value_fields | Contains multiple sub-details; each item corresponds to a title and its associated value_field, presenting multiple related pieces of information under the same title | Choose between value_fields or value_field, see JSON above for details |
| value_field | Contains a single sub-detail, corresponding to a single data field, presenting a single piece of information | Choose between value_field or value_fields, see JSON above for details |