Merge branch 'dev' into master

README.md

@@ -20,6 +20,8 @@ The specification will be versioned using Git tags and [semantic versioning](htt
 
 The City of Los Angeles is currently looking for feedback and comments on the draft versions. Comments can be made by making an Github Issue, while suggested changes can be made using a pull request. The rules and guidelines for the Los Angeles Dockless Bikeshare Systems / Pilot Program can be found on [Council Clerk Connect](https://cityclerk.lacity.org/lacityclerkconnect/index.cfm?fa=ccfi.viewrecord&cfnumber=17-1125).
 
+*12/27/2018 Update*: Applications for the One-Year Dockless On-Demand Personal Mobility Permit are now available on the [LADOT Website](https://ladot.lacity.org/ladot-begins-one-year-dockless-demand-personal-mobility-program)
+
 *10/28/2018 Update*: [LADOT Guidelines for Handling of Data from Mobility Service Providers](http://www.urbanmobilityla.com/s/LADOT-Guidelines-for-Handling-of-Data-from-MSPs-2018-10-25.pdf)
 
 *10/1/2018 Update*: Applications for the Conditional Permit are now open for submission on the [LADOT Website](http://ladot.lacity.org/ladot-begins-conditional-permit-program-dockless-mobility)
@@ -38,10 +40,18 @@ The City of Los Angeles is currently looking for feedback and comments on the dr
 * [`mds-provider`](https://github.com/cityofsantamonica/mds-provider) - Python package implementing the provider API, validation using JSONSchema, data loading to multiple targets, and fake provider data generation.
 * [`mds-provider-services`](https://github.com/cityofsantamonica/mds-provider-services) - Python scripts wrapped in Docker containers implementing a MDS provider data ingestion flow, using `mds-provider` and handling the various dependencies.
 
+### City of Austin
+* [`transportation-dockless-dataviz`](https://github.com/cityofaustin/transportation-dockless-dataviz) - A hexbin origin/destintation web map of dockless trips using jQuery & Mapbox GL JS. See [http://dockless.austintexas.io/](http://dockless.austintexas.io/).
+* [`transportation-dockless-api`](https://github.com/cityofaustin/transportation-dockless-api) - Python Sanic-based API that provides an interface for retrieving anonymized and aggregated trip data. This API supplies data to our interactive [Dockless Mobility Explorer](https://dockless.austintexas.io). The source database for the API is our [Dockless Vehicle Trips](https://data.austintexas.gov/Transportation-and-Mobility/Dockless-Vehicle-Trips/7d8e-dm7r) dataset.
+* [`transportation-dockless-processing`](https://github.com/cityofaustin/transportation-dockless-processing) - Python scripts for dockless mobility data ETL.
+* [`mds-provider-client`](https://github.com/cityofaustin/mds-provider-client) - A forked Python client from [`CityofSantaMonica/mds-provider`](https://github.com/cityofsantamonica/mds-provider).
+
 ### Others
 
 Please open a pull request if you create open source or private MDS tooling. 
 
+* [`midas`](https://github.com/polyconseil/midas) - Python/Django open source server for the [`agency`][agency] API, developped by BlueSystems.
+
 ## Contact
 
 Questions can be directed to [email protected]. 

generate_schema/Pipfile

@@ -6,7 +6,7 @@ name = "pypi"
 [packages]
 
 [dev-packages]
-jsonschema = ">=3.0.0a2"
+jsonschema = "==3.0.0a3"
 requests = "*"
 
 [requires]

generate_schema/common.json

@@ -108,9 +108,10 @@
     },
     "timestamp": {
       "$id": "#/definitions/timestamp",
-      "title": "Floating-point seconds since Unix epoch",
+      "title": "Integer milliseconds since Unix epoch",
       "type": "number",
-      "minimum": 0.0
+      "multipleOf": 1.0, 
+      "minimum": 0 
     }
   }
 }

generate_schema/generate_provider_schema.py

@@ -13,7 +13,7 @@
 MDS_FEATURECOLLECTION_ROUTE = "MDS_FeatureCollection_Route"
 
 def get_definition(id):
-    return "#/definitions/{}".format(id)
+    return f"#/definitions/{id}"
 
 def get_point_schema():
     """

generate_schema/provider/status_changes.json

@@ -163,12 +163,8 @@
               },
               "event_time": {
                 "$id": "#/properties/data/properties/status_changes/items/properties/event_time",
-                "type": "number",
                 "description": "The time the event occurred, expressed as a Unix Timestamp",
-                "default": 0.0,
-                "examples": [
-                  1529968782.421409
-                ]
+                "$ref": "#/definitions/timestamp"
               },
               "event_location": {
                 "$id": "#/properties/data/properties/status_changes/items/properties/event_location",
@@ -206,4 +202,4 @@
     }
   },
   "additionalProperties": false
-}
+}

generate_schema/provider/trips.json

@@ -123,21 +123,13 @@
               },
               "start_time": {
                 "$id": "#/properties/data/properties/trips/items/properties/start_time",
-                "type": "number",
                 "description": "The time the trip began, expressed as a Unix Timestamp",
-                "default": 0.0,
-                "examples": [
-                  1529968782.421409
-                ]
+                "$ref": "#/definitions/timestamp"
               },
               "end_time": {
                 "$id": "#/properties/data/properties/trips/items/properties/end_time",
-                "type": "number",
                 "description": "The time the trip ended, expressed as a Unix Timestamp",
-                "default": 0.0,
-                "examples": [
-                  1531007628.3774529
-                ]
+                "$ref": "#/definitions/timestamp"
               },
               "parking_verification_url": {
                 "$id": "#/properties/data/properties/trips/items/properties/parking_verification_url",
@@ -175,4 +167,4 @@
     }
   },
   "additionalProperties": false
-}
+}

provider/README.md

@@ -15,6 +15,8 @@ The following information applies to all `provider` API endpoints. Details on pr
 
 ### Response Format
 
+The response to a client request must include a status code defined in the [IANA HTTP Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
+
 Responses must be `UTF-8` encoded `application/json` and must minimally include the MDS `version` and a `data` payload:
 
 ```json
@@ -85,7 +87,7 @@ represented as a GeoJSON [`Feature`](https://tools.ietf.org/html/rfc7946#section
 {
     "type": "Feature",
     "properties": {
-        "timestamp": 1529968782.421409
+        "timestamp": 1529968782421
     },
     "geometry": {
         "type": "Point",
@@ -101,8 +103,7 @@ represented as a GeoJSON [`Feature`](https://tools.ietf.org/html/rfc7946#section
 
 ### Timestamps
 
-References to `timestamp` imply floating-point seconds since [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), such as
-the format returned by Python's [`time.time()`](https://docs.python.org/3/library/time.html#time.time) function.
+References to `timestamp` imply integer milliseconds since [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). You can find the implementation of unix timestamp in milliseconds for your programming language [here](https://currentmillis.com/).
 
 [Top][toc]
 
@@ -143,19 +144,8 @@ The trips API should allow querying trips with a combination of query parameters
 
 * `device_id`
 * `vehicle_id`
-* `start_time`: filters for trips where `start_time` occurs at or after the given time
-* `end_time`: filters for trips where `end_time` occurs at or before the given time
-* `bbox`
-
-All of these query params will use the *Type* listed above with the exception of `bbox`, which is the bounding-box.
-
-For example:
-
-```
-bbox=-122.4183,37.7758,-122.4120,37.7858
-```
-
-Gets all trips within that bounding-box where any point inside the `route` is inside said box. The order is defined as: southwest longitude, southwest latitude, northeast longitude, northeast latitude (separated by commas).
+* `min_end_time`: filters for trips where `end_time` occurs at or after the given time
+* `max_end_time`: filters for trips where `end_time` occurs before the given time
 
 ### Vehicle Types
 
@@ -187,7 +177,7 @@ Routes must include at least 2 points: the start point and end point. Additional
     "features": [{
         "type": "Feature",
         "properties": {
-            "timestamp": 1529968782.421409
+            "timestamp": 1529968782421
         },
         "geometry": {
             "type": "Point",
@@ -200,7 +190,7 @@ Routes must include at least 2 points: the start point and end point. Additional
     {
         "type": "Feature",
         "properties": {
-            "timestamp": 1531007628.3774529
+            "timestamp": 1531007628377
         },
         "geometry": {
             "type": "Point",
@@ -246,14 +236,7 @@ Schema: [`status_changes` schema][sc-schema]
 The status_changes API should allow querying status changes with a combination of query parameters.
 
 * `start_time`: filters for status changes where `event_time` occurs at or after the given time
-* `end_time`: filters for status changes where `event_time` occurs at or before the given time
-* `bbox`: filters for status changes where `event_location` is within defined bounding-box. The order is definied as: southwest longitude, southwest latitude, northeast longitude, northeast latitude (separated by commas). 
-
-Example:
-
-```
-bbox=-122.4183,37.7758,-122.4120,37.7858
-```
+* `end_time`: filters for status changes where `event_time` occurs before the given time
 
 ### Event Types
 
@@ -270,16 +253,53 @@ bbox=-122.4183,37.7758,-122.4120,37.7858
 | | | `rebalance_pick_up` | Device removed from street and will be placed at another location to rebalance service |
 | | | `maintenance_pick_up` | Device removed from street so it can be worked on |
 
+## Service Areas
+
+Gets the list of service areas available to the provider.
+
+Endpoint: `/service_areas`
+Method: `GET`
+Query Parameters:
+
+| Parameter | Type | Required/Optional | Description |
+| ----- | ---- | ----------------- | ----- |
+| `service_area_id` | UUID  | Optional | If provided, retrieve a specific service area (e.g. a retired or old service area). If omitted, will return all active service areas. |
+
+Response:
+
+| Field | Types  | Required/Optional | Other |
+| ----- | ---- | ----------------- | ----- |
+| `service_area_id` | UUID | Required |  |
+| `service_start_date` | Unix Timestamp | Required | Date at which this service area became effective |
+| `service_end_date` | Unix Timestamp | Required | Date at which this service area was replaced. If currently effective, place NaN |
+| `service_area` | MultiPolygon | Required | |
+| `prior_service_area` | UUID | Optional | If exists, the UUID of the prior service area. |
+| `replacement_service_area` | UUID | Optional | If exists, the UUID of the service area that replaced this one |
+| `type` | Enum | Required |  See [area types](#area-types) table |
+
+### Area types
+
+| `type` | Description |
+|------------| ----------- |
+| unrestricted | Areas where devices may be picked up/dropped off. A provider's unrestricted area shall be contained completely inside the agency's unrestricted area for the provider in question, but it need not cover the entire agency unrestricted area. See the agency version of the service areas endpoint |
+| agency_restricted | Areas where the agency does not allow device pick-up/drop-off |
+| agency_preferred_pick_up | Areas where users are encouraged by the agency to pick up devices |
+| agency_preferred_drop_off | Areas where users are encouraged by the agency to drop off devices |
+| provider_restricted | Areas where the provider does not allow device pick-up/drop-off |
+| provider_preferred_pick_up | Areas where users are encouraged by the provider to pick up devices |
+| provider_preferred_drop_off | Areas where users are encouraged by the provider to drop off devices |
+
+[Top][toc]
+
 ## Realtime Data
 
 All MDS compatible `provider` APIs must expose a public [GBFS](https://github.com/NABSA/gbfs) feed as well. Given that GBFS hasn't fully [evolved to support dockless mobility](https://github.com/NABSA/gbfs/pull/92) yet, we follow the current guidelines in making bike information avaliable to the public. 
 
+  - `gbfs.json` is always required and must contain a `feeds` property that lists all published feeds
   - `system_information.json` is always required
   - `free_bike_status.json` is required for MDS
   - `station_information.json` and `station_status.json` don't apply for MDS
 
-
-
 [Top][toc]
 
 [geo]: #geographic-data

provider/status_changes.json

@@ -52,7 +52,6 @@
           ]
         },
         "properties": {
-          "type": "object",
           "required": [
             "timestamp"
           ],
@@ -150,9 +149,10 @@
     },
     "timestamp": {
       "$id": "#/definitions/timestamp",
-      "title": "Floating-point seconds since Unix epoch",
+      "title": "Integer milliseconds since Unix epoch",
       "type": "number",
-      "minimum": 0.0
+      "multipleOf": 1.0,
+      "minimum": 0
     },
     "vehicle_type": {
       "$id": "#/definitions/vehicle_type",
@@ -342,12 +342,8 @@
               },
               "event_time": {
                 "$id": "#/properties/data/properties/status_changes/items/properties/event_time",
-                "type": "number",
                 "description": "The time the event occurred, expressed as a Unix Timestamp",
-                "default": 0.0,
-                "examples": [
-                  1529968782.421409
-                ]
+                "$ref": "#/definitions/timestamp"
               },
               "event_location": {
                 "$id": "#/properties/data/properties/status_changes/items/properties/event_location",
@@ -391,4 +387,4 @@
     }
   },
   "additionalProperties": false
-}
+}