From 7f002f664ffe0f15d1083909b705284645aec957 Mon Sep 17 00:00:00 2001 From: Neil Goldader Date: Thu, 23 Jan 2020 14:44:30 -0500 Subject: [PATCH 1/3] Add agency stops definition --- agency/README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/agency/README.md b/agency/README.md index 5abccedd..059c0ae9 100644 --- a/agency/README.md +++ b/agency/README.md @@ -251,6 +251,67 @@ A standard point of vehicle telemetry. References to latitude and longitude impl | `gps.satellites` | Integer | Required if Available | Number of GPS or GNSS satellites | `charge` | Float | Required if Applicable | Percent battery charge of vehicle, expressed between 0 and 1 | +## Stops + +The `/stops` endpoint allows an agency to register Stops. + +Endpoint: `/stops` +Method: `POST` + +| Field | Type | Required/Optional | Description | +|---------------------|-----------------------------------------------------------------------------------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| stop_id | UUID | Required | Unique ID for stop | +| stop_name | String | Required | Name of stop | +| lat | Double | Required | Latitude of the location | +| lng | Double | Required | Longitude of the location | +| capacity | {vehicle_type: number} | Required | Number of total spots per vehicle_type | +| geography_id | UUID | Optional | Pointer to the Geography that represents the stop geospatially | +| region_id | string | Optional | ID of the region where station is located, see [GBFS Station Information](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson) | +| short_name | String | Optional | Abbreviated stop name | +| address | String | Optional | Postal address (useful for directions) | +| post_code | String | Optional | Postal code (e.g. `10036`) | +| rental_methods | [Enum](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson) | Optional | Payment methods accepted at stop, see [GBFS Rental Methods](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson) | +| timezone | String | Optional | Timezone stop is located in | +| cross_street | String | Optional | Cross street of where the station is located. | +| wheelchair_boarding | Boolean | Optional | Is this stop handicap accessible? | +| parent_stop | UUID | Optional | Describe a basic hierarchy of stops (e.g.a stop inside of a greater stop) | + +Endpoint: `/stops` +Method: `PUT` + +| Field | Type | Required/Optional | Description | +|---------------------|------------------------|-------------------|-------------------------------------------------------------------------| +| stop_id | UUID | Required | Unique ID for stop | +| num_spots_available | {vehicle_type: number} | Optional | How many spots are free to be populated with vehicles at this stop? | +| num_spots_disabled | {vehicle_type: number} | Optional | How many docks are disabled and unable to accept vehicles at this stop? | + +Endpoint: `/stops/{stop_id}` +Method: `GET` + +| Field | Type | Required/Optional | Description | +|------------------------|-----------------------------------------------------------------------------------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| stop_id | UUID | Required | Unique ID for stop | +| stop_name | String | Required | Name of stop | +| lat | Double | Required | Latitude of the location | +| lng | Double | Required | Longitude of the location | +| capacity | {vehicle_type: number} | Required | Number of total spots per vehicle_type | +| num_vehicles_available | {vehicle_type: number} | Required | How many vehicles are available per vehicle_type at this stop? | +| num_vehicles_disabled | {vehicle_type: number} | Required | How many vehicles are unavailable/reserved per vehicle_type at this stop? | +| geography_id | UUID | Optional | Pointer to the Geography that represents the stop geospatially | +| region_id | string | Optional | ID of the region where station is located, see [GBFS Station Information](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson) | +| short_name | String | Optional | Abbreviated stop name | +| address | String | Optional | Postal address (useful for directions) | +| post_code | String | Optional | Postal code (e.g. `10036`) | +| rental_methods | [Enum](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson) | Optional | Payment methods accepted at stop, see [GBFS Rental Methods](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson) | +| cross_street | String | Optional | Cross street of where the station is located. | +| num_spots_available | {vehicle_type: number} | Optional | How many spots are free to be populated with vehicles at this stop? | +| num_spots_disabled | {vehicle_type: number} | Optional | How many docks are disabled and unable to accept vehicles at this stop? | +| wheelchair_boarding | Boolean | Optional | Is this stop handicap accessible? | +| parent_stop | UUID | Optional | Describe a basic hierarchy of stops (e.g.a stop inside of a greater stop) | + +### GBFS Compatibility +Some of the fields in the `Stops` definition are using notions which are currently not in MDS, such as `rental_methods`. These fields are included for compatibility with GBFS. + ## Enum Definitions ### Area Types From fedbe23e4e13f7622030c5e2c5ae6dd3127f50af Mon Sep 17 00:00:00 2001 From: Neil Goldader Date: Wed, 10 Jun 2020 11:20:58 -0400 Subject: [PATCH 2/3] Alignment with recent changes in Provider version --- agency/README.md | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/agency/README.md b/agency/README.md index 059c0ae9..d97e13c0 100644 --- a/agency/README.md +++ b/agency/README.md @@ -255,8 +255,10 @@ A standard point of vehicle telemetry. References to latitude and longitude impl The `/stops` endpoint allows an agency to register Stops. -Endpoint: `/stops` -Method: `POST` +**Endpoint:** `/stops` +**Method:** `POST` +**[Beta feature](/general-information.md#beta-features):** Yes (as of 1.0.0) + | Field | Type | Required/Optional | Description | |---------------------|-----------------------------------------------------------------------------------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -276,17 +278,21 @@ Method: `POST` | wheelchair_boarding | Boolean | Optional | Is this stop handicap accessible? | | parent_stop | UUID | Optional | Describe a basic hierarchy of stops (e.g.a stop inside of a greater stop) | -Endpoint: `/stops` -Method: `PUT` +**Endpoint:** `/stops` +**Method:** `PUT` +**[Beta feature](/general-information.md#beta-features):** Yes (as of 1.0.0) | Field | Type | Required/Optional | Description | |---------------------|------------------------|-------------------|-------------------------------------------------------------------------| | stop_id | UUID | Required | Unique ID for stop | +| status | Enum | Required | Status of the Stop. See [Stop Statuses](#stop-statuses) table. | | num_spots_available | {vehicle_type: number} | Optional | How many spots are free to be populated with vehicles at this stop? | | num_spots_disabled | {vehicle_type: number} | Optional | How many docks are disabled and unable to accept vehicles at this stop? | -Endpoint: `/stops/{stop_id}` -Method: `GET` +**Endpoint:** `/stops/:stop_id` +**Method:** `GET` +**[Beta feature](/general-information.md#beta-features):** Yes (as of 1.0.0) +**`data` Payload:** `{ "stops": [] }`, an array of objects with the following structure | Field | Type | Required/Optional | Description | |------------------------|-----------------------------------------------------------------------------------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -294,10 +300,11 @@ Method: `GET` | stop_name | String | Required | Name of stop | | lat | Double | Required | Latitude of the location | | lng | Double | Required | Longitude of the location | +| status | Enum | Required | Status of the Stop. See [Stop Statuses](#stop-statuses) table. | | capacity | {vehicle_type: number} | Required | Number of total spots per vehicle_type | | num_vehicles_available | {vehicle_type: number} | Required | How many vehicles are available per vehicle_type at this stop? | | num_vehicles_disabled | {vehicle_type: number} | Required | How many vehicles are unavailable/reserved per vehicle_type at this stop? | -| geography_id | UUID | Optional | Pointer to the Geography that represents the stop geospatially | +| geography_id | UUID | Optional | Pointer to the Geography that represents the Stop geospatially | | region_id | string | Optional | ID of the region where station is located, see [GBFS Station Information](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson) | | short_name | String | Optional | Abbreviated stop name | | address | String | Optional | Postal address (useful for directions) | @@ -306,8 +313,17 @@ Method: `GET` | cross_street | String | Optional | Cross street of where the station is located. | | num_spots_available | {vehicle_type: number} | Optional | How many spots are free to be populated with vehicles at this stop? | | num_spots_disabled | {vehicle_type: number} | Optional | How many docks are disabled and unable to accept vehicles at this stop? | -| wheelchair_boarding | Boolean | Optional | Is this stop handicap accessible? | -| parent_stop | UUID | Optional | Describe a basic hierarchy of stops (e.g.a stop inside of a greater stop) | +| parent_stop | UUID | Optional | Describe a basic hierarchy of stops (e.g.a stop inside of a greater stop) | + +In the case that a `stop_id` query parameter is specified, the `stops` array returned will only have one entry. In the case that no `stop_id` query parameter is specified, all stops will be returned. + +#### Stop Statuses + +| `status` | Description | +| ---------------- | ---------------------------------------------------------------------------------------- | +| `open` | The station is open and available to rent out or accept vehicles | +| `closed` | The station is closed. Either because of operating hours, repairs, or a seasonal closure | +| `decommissioned` | The station is permanently closed and will be removed from the system | | ### GBFS Compatibility Some of the fields in the `Stops` definition are using notions which are currently not in MDS, such as `rental_methods`. These fields are included for compatibility with GBFS. From 5ef7383c04e71ee2b5face37c0176e84d1cc8eee Mon Sep 17 00:00:00 2001 From: Neil Goldader Date: Thu, 11 Jun 2020 08:44:36 -0400 Subject: [PATCH 3/3] Add stop_id to telemetry payload --- agency/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/agency/README.md b/agency/README.md index d97e13c0..01724371 100644 --- a/agency/README.md +++ b/agency/README.md @@ -250,6 +250,7 @@ A standard point of vehicle telemetry. References to latitude and longitude impl | `gps.hdop` | Float | Required if Available | Horizontal GPS or GNSS accuracy value (see [hdop](https://support.esri.com/en/other-resources/gis-dictionary/term/358112bd-b61c-4081-9679-4fca9e3eb926)) | | `gps.satellites` | Integer | Required if Available | Number of GPS or GNSS satellites | `charge` | Float | Required if Applicable | Percent battery charge of vehicle, expressed between 0 and 1 | +| `stop_id` | UUID | Required if Applicable | Stop that the vehicle is currently located at. Only applicable for _docked_ Micromobility. See [Stops](#stops) | ## Stops