Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

MDS-Agency Stops Specification #430

Closed
wants to merge 3 commits into from
Closed

MDS-Agency Stops Specification #430

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7f002f6
Add agency stops definition
avatarneil Jan 23, 2020
fedbe23
Alignment with recent changes in Provider version
avatarneil Jun 10, 2020
5ef7383
Add stop_id to telemetry payload
avatarneil Jun 11, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 78 additions & 0 deletions agency/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,84 @@ 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

The `/stops` endpoint allows an agency to register Stops.

**Endpoint:** `/stops`
**Method:** `POST`
**[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 |
| 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`
**[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`
**[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 |
|------------------------|-----------------------------------------------------------------------------------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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 |
| 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 |
| 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? |
| 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.

## Enum Definitions

Expand Down