From 5d10d0b007fc9c3da6f642e0235837e25c35341b Mon Sep 17 00:00:00 2001 From: Nicholas Reinicke Date: Thu, 25 Jul 2024 16:47:12 -0600 Subject: [PATCH 1/5] Update routee documentation to version 3 --- .../transportation/routee-v1/index.html.md | 8 - source/docs/transportation/routee-v1/spec.yml | 367 ------------------ .../transportation/routee-v3/index.html.md | 8 + source/docs/transportation/routee-v3/spec.yml | 228 +++++++++++ 4 files changed, 236 insertions(+), 375 deletions(-) delete mode 100644 source/docs/transportation/routee-v1/index.html.md delete mode 100644 source/docs/transportation/routee-v1/spec.yml create mode 100644 source/docs/transportation/routee-v3/index.html.md create mode 100644 source/docs/transportation/routee-v3/spec.yml diff --git a/source/docs/transportation/routee-v1/index.html.md b/source/docs/transportation/routee-v1/index.html.md deleted file mode 100644 index 345a6cb9..00000000 --- a/source/docs/transportation/routee-v1/index.html.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: RouteE -summary: The Route Energy Prediction Model (RouteE) predicts the energy consumption of a given vehicle over a proposed route. -layout: swagger -swagger_url: /docs/transportation/routee-v1/spec.yml -swagger_hide_tag_headers: true -swagger_hide_footer_models: true ---- diff --git a/source/docs/transportation/routee-v1/spec.yml b/source/docs/transportation/routee-v1/spec.yml deleted file mode 100644 index 3e61d28a..00000000 --- a/source/docs/transportation/routee-v1/spec.yml +++ /dev/null @@ -1,367 +0,0 @@ -openapi: 3.0.0 -info: - title: RouteE API - version: "2.0" - description: | - The Route Energy Prediction Model (RouteE) predicts the energy consumption of a given vehicle over a link or sequence of links in a road network. For more on RouteE, please visit . Example code can be found at . - - **URL**: `https://developer.nrel.gov/api/routee/v2` - - **Endpoints**: - - `/route`: single vehicle route energy consumption estimate. - - `/network`: energy consumption estimates for a variety of vehicles over all links in a transportation network. - - `/compass`: eco-routing between an origin and destination for a specific vehicle. - -servers: - - url: https://developer.nrel.gov/api/routee/v2 -paths: - /route: - post: - summary: Estimate energy consumption for a single route. - description: Single vehicle route energy consumption estimate. - requestBody: - description: A JSON object with your real or predicted vehicle route data. - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/RouteRequest" - responses: - "200": - description: A JSON object with the returned energy consumption estimates and metadata for the provided route. - content: - application/json: - schema: - $ref: "#/components/schemas/RouteResponse" - /network: - post: - summary: Network energy prediction - description: Energy consumption estimates for a variety of vehicles over all links in a transportation network. - requestBody: - description: A JSON object with your real or predicted transportation network data. - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/NetworkRequest" - responses: - "200": - description: A JSON object with the returned energy consumption estimates and metadata for the provided network. - content: - application/json: - schema: - $ref: "#/components/schemas/NetworkResponse" - /compass/beta: - get: - summary: Shortest energy path - description: Eco-routing between an origin and destination for a specific vehicle. - parameters: - - in: query - name: origin_lat - required: true - schema: - type: number - description: The origin latitude for the route - - in: query - name: origin_lon - required: true - schema: - type: number - description: The origin longitude for the route - - in: query - name: destination_lat - required: true - schema: - type: number - description: The destination latitude for the route - - in: query - name: destination_lon - required: true - schema: - type: number - description: The destination longitude for the route - - in: query - name: number_of_waypoints - schema: - type: integer - description: Upper limit of waypoints to return. Default is 100 - - in: query - name: routee_key - schema: - type: string - description: Which routee model to use for energy prediction. Default is "gasoline" - responses: - "200": - description: A JSON object with the waypoints for the shortest energy route - content: - application/json: - schema: - $ref: "#/components/schemas/CompassResponse" -components: - securitySchemes: - ApiKeyQueryAuth: - type: apiKey - in: query - name: api_key - ApiKeyHeaderAuth: - type: apiKey - in: header - name: X-Api-Key - schemas: - RouteRequest: - type: object - required: [segment_ids, lengths_miles, speeds_mph, grades_percent, model] - properties: - segment_ids: - type: array - items: - type: string - description: Ordered array corresponding to unique identifiers for each road segement of the route. (Such as TMC codes) - example: ["110N04615", "110N04616", "110N04617"] - lengths_miles: - type: array - items: - type: number - description: Ordered array corresponding to distance (in miles) of the road segment. - example: [.12,.2,.13] - speeds_mph: - type: array - items: - type: number - description: Ordered array corresponding to real or predicted speed of the for the road segment. - example: [50.3, 50.0, 47.6] - grades_percent: - type: array - items: - type: number - description: Ordered array corresponding to floating point value representing the gradient of the road segment. - example: [0.01, 0.02, 0.02] - model: - type: string - description: Vehicle fuel type (Conventional gasoline, diesel, battery electric, and hybrid electric). - enum: [gasoline, diesel, hybrid, electric] - NetworkRequest: - type: object - required: [segment_ids, lengths_miles, speeds_mph, grades_percent, volumes] - properties: - segment_ids: - type: array - items: - type: string - description: Ordered array corresponding to unique identifiers for each road segement of the route. (Such as TMC codes) - example: ["110N04615", "110N04616", "110N04617"] - lengths_miles: - type: array - items: - type: number - description: Ordered array corresponding to distance (in miles) of the road segment. - example: [.12,.2,.13] - speeds_mph: - type: array - items: - type: number - description: Ordered array corresponding to real or predicted speed of the for the road segment. - example: [50.3, 50.0, 47.6] - grades_percent: - type: array - items: - type: number - description: Ordered array corresponding to floating point value representing the gradient of the road segment. - example: [0.01, 0.02, 0.02] - volumes: - type: array - items: - type: number - description: Ordered array of integer values of segement-level traffic counts. - example: [12, 12, 11] - gasoline_ratio: - type: number - description: Float value representing percentage of vehicle fleet represented by gasoline vehicles. - example: 0.85 - diesel_ratio: - type: number - description: Float value representing percentage of vehicle fleet represented by diesel vehicles. - example: 0.1 - hybrid_ratio: - type: number - description: Float value representing percentage of vehicle fleet represented by hybrid vehicles. - example: 0.025 - electric_ratio: - type: number - description: Float value representing percentage of vehicle fleet represented by electric vehicles. - example: 0.025 - - RouteResponse: - type: object - properties: - route: - type: object - properties: - segment_ids: - type: array - items: - type: string - description: Ordered array corresponding to unique identifiers for each road segement of the route. (Such as TMC codes) - example: ["110N04615", "110N04616", "110N04617"] - energy_estimate: - type: array - items: - type: number - description: Energy consumption estimates for each road segment. - example: [0.00123, 0.000124, 0.000128] - output_metadata: - type: object - properties: - Total Energy: - type: number - description: Measure of total energy consumed during the trip. - example: 0.00375 - Energy Unit: - type: string - description: Unit of energy measurement - example: "GGE" - RouteE version: - type: string - description: Version of RouteE Powertrain used in the API. - example: "v0.1.0" - Vehicle description: - type: string - description: Vehicle model used in the energy estimation. - example: "built_in_routee_gas_model" - Data Dictionary: - type: object - properties: - output_fields: - type: object - description: Explanation of the output fields in the resulting data. - properties: - energy_estimate: - type: string - description: Indication that this is the resulting segment-level energy estimation data. - example: "Resulting energy estimate array" - NetworkResponse: - type: object - properties: - network: - type: object - properties: - your_input_ids: - type: array - items: - type: string - description: Unique identifiers for each road segement of the route. (Such as TMC codes) - example: ["110N04615", "110N04616", "110N04617"] - gasoline_total_energy: - type: array - items: - type: number - description: Conventional gasoline vehicle energy consumption estimates. - example: [0.00123, 0.000124, 0.000128] - diesel_total_energy: - type: array - items: - type: number - description: Diesel vehicle energy consumption estimates. - example: [0.00123, 0.000124, 0.000128] - hybrid_total_energy: - type: array - items: - type: number - description: Hybrid electric vehicle energy consumption estimates. - example: [0.00123, 0.000124, 0.000128] - electric_total_energy: - type: array - items: - type: number - description: Battery electric vehicle energy consumption estimates. - example: [0.00123, 0.000124, 0.000128] - output_metadata: - type: object - properties: - Energy summary: - type: object - properties: - Total BEV energy: - type: number - description: Total bettery electric vehicle energy consumed. - example: 0.00323 - Total HEV energy: - type: number - description: Total hybrid electric vehicle energy consumed. - example: 0.00654 - Total diesel energy: - type: number - description: Total diesel vehicle energy consumed. - example: 1.418 - Total energy: - type: number - description: Total energy consumed. - example: 13.54132 - Total gasoline energy: - type: number - description: Total gasoline vehicle energy consumed. - example: 10.694 - Energy unit: - type: string - description: Unit of energy measurement - example: "GGE" - Data dictionary: - type: object - properties: - output_fields: - type: object - description: Explanation of the output fields in the resulting data. - properties: - electric_total_energy: - type: string - description: Indication that this is the resulting segment-level BEV energy estimation data. - example: "Total BEV energy" - gasoline_total_energy: - type: string - description: Indication that this is the resulting segment-level gasoline vehicle energy estimation data. - example: "Total gasoline energy" - hybrid_total_energy: - type: string - description: Indication that this is the resulting segment-level HEV energy estimation data. - example: "Total HEV energy" - diesel_total_energy: - type: string - description: Indication that this is the resulting segment-level diesel vehicle energy estimation data. - example: "Total diesel energy" - RouteE version: - type: string - description: Version of RouteE Powertrain used in the API. - example: "v0.1.0" - RouteE Models: - type: object - properties: - BEV: - type: string - description: Description of RouteE BEV model used in the calculation. - example: "built_in_routee_bev_model" - HEV: - type: string - description: Description of RouteE HEV model used in the calculation. - example: "built_in_routee_gev_model" - Diesel: - type: string - description: Description of RouteE diesel vehicle model used in the calculation. - example: "built_in_routee_diesel_model" - Conventional Gasoline: - type: string - description: Description of RouteE gasoline vehicle used in the calculation. - example: "built_in_routee_gas_model" - CompassResponse: - type: object - properties: - route: - type: array - items: - type: array - items: - type: number - description: Individual waypoints for the shortest energy path in [lat, lon] - example: [[39.7540755, -104.9939502], [39.7540757, -104.9939507]] -security: - - ApiKeyQueryAuth: [] - - ApiKeyHeaderAuth: [] \ No newline at end of file diff --git a/source/docs/transportation/routee-v3/index.html.md b/source/docs/transportation/routee-v3/index.html.md new file mode 100644 index 00000000..f45e8a9d --- /dev/null +++ b/source/docs/transportation/routee-v3/index.html.md @@ -0,0 +1,8 @@ +--- +title: RouteE +summary: RouteE Powertrain predicts energy over a pre-determined route. RouteE Compass generates new energy-aware routes. +layout: swagger +swagger_url: /docs/transportation/routee-v3/spec.yml +swagger_hide_tag_headers: true +swagger_hide_footer_models: true +--- diff --git a/source/docs/transportation/routee-v3/spec.yml b/source/docs/transportation/routee-v3/spec.yml new file mode 100644 index 00000000..a60a0905 --- /dev/null +++ b/source/docs/transportation/routee-v3/spec.yml @@ -0,0 +1,228 @@ +openapi: 3.0.0 +info: + title: RouteE API + description: The Route Energy Prediction Model (RouteE) predicts the energy consumption of a given vehicle over a link or sequence of links (route) in a road network. These API endpoints can be used to get single vehicle link or route energy estimates (`/powertrain/route`) and eco-routing between an origin and destination for a specific vehicle (`/compass/route`). For more on RouteE, please visit . + version: "3.0" +servers: + - url: https://developer.nrel.gov/routee/api/v3 +paths: + /powertrain/route: + post: + summary: Estimate energy consumption for a single route. + requestBody: + description: A JSON object with your real or predicted vehicle route data. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/PowertrainRequest" + responses: + "200": + description: A JSON object with the returned energy consumption estimates and metadata for the provided route. + content: + application/json: + schema: + $ref: "#/components/schemas/PowertrainResponse" + /powertrain/models: + get: + summary: Get a list of available powertrain models. + responses: + "200": + description: A JSON object with the available powertrain models. + content: + application/json: + schema: + type: object + properties: + available_models: + type: array + items: + type: string + /compass/route: + post: + summary: Energy aware routing + requestBody: + description: A JSON object with your route request. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CompassRequest" + responses: + "200": + description: A JSON object with the energy aware route + content: + application/json: + schema: + $ref: "#/components/schemas/CompassResponse" + /compass/models: + get: + summary: Get a list of available powertrain models. + responses: + "200": + description: A JSON object with the available powertrain models. + content: + application/json: + schema: + type: object + properties: + available_models: + type: array + items: + type: string +components: + securitySchemes: + ApiKeyQueryAuth: + type: apiKey + in: query + name: api_key + ApiKeyHeaderAuth: + type: apiKey + in: header + name: X-Api-Key + schemas: + PowertrainLink: + type: object + required: [id, miles, speed_mph] + properties: + id: + type: string + description: The unique identifier for the link + miles: + type: number + format: float + description: The length of the link in miles + speed_mph: + type: number + format: float + description: The speed of the link in miles per hour + grade_dec: + type: number + format: float + description: The grade of the link in decimal form (i.e. 0.05 for 5% grade) + nullable: true + entry_angle: + type: number + format: float + description: The entry angle of the link in degrees + nullable: true + exit_angle: + type: number + format: float + description: The exit angle of the link in degrees + nullable: true + RouteRequest: + type: object + required: [powertrain_model, links] + properties: + powertrain_model: + type: string + description: The powertrain model to use for the energy estimate + links: + type: array + description: A list of links that make up the route + items: + $ref: "#/components/schemas/PowertrainLink" + RouteResponse: + type: object + properties: + route: + type: array + items: + type: object + properties: + id: + type: string + energy_estimate: + type: float + description: The energy estimate for the link + output_metadata: + type: object + properties: + total_energy: + type: string + description: The total energy estimate for the route + energy_unit: + type: string + description: The unit of the energy estimate + routee_version: + type: string + description: The version of the RouteE model used for the estimate + vehicle_description: + type: string + description: The description of the vehicle used for the estimate + CompassRequest: + type: object + required: + [origin_lat, origin_lon, destination_lat, destination_lon, model_name] + properties: + origin_lat: + type: number + format: float + description: The latitude of the origin + origin_lon: + type: number + format: float + description: The longitude of the origin + destination_lat: + type: number + format: float + description: The latitude of the destination + destination_lon: + type: number + format: float + description: The longitude of the destination + model_name: + type: string + description: The name of the RouteE Powertrain vehicle model to use for the energy estimate + start_time: + type: string + default: "09:00:00" + description: The start time for the route (in 24-hour format) + start_weekday: + type: string + default: "monday" + description: The start weekday for the route + vehicle_rates: + type: object + description: The vehicle rates for the route + weights: + type: object + description: The weights for the state model + CompassResponse: + type: object + properties: + route: + type: object + description: The route in GeoJSON format + request: + $ref: "#/components/schemas/CompassRequest" + description: The original request that was made + iterations: + type: integer + description: The number of iterations that the algorithm ran + traversal_summary: + type: object + description: A summary of the traversal (e.g. total distance, total energy) + state_model: + type: object + description: The state model used for the routing (e.g. initial conditions, units, etc.) + route_edges: + type: integer + description: The number of edges in the route + search_executed_time: + type: string + description: The time that the search was executed + search_result_size_mib: + type: number + format: float + description: The size of the search result in MiB + search_runtime: + type: string + description: The runtime of the search + tree_size_count: + type: integer + description: The size of the search tree +security: + - ApiKeyQueryAuth: [] + - ApiKeyHeaderAuth: [] From 92be3b80965d683a4d7da1249d0482c9b23cbaf6 Mon Sep 17 00:00:00 2001 From: Nicholas Reinicke Date: Wed, 28 Aug 2024 10:09:55 -0600 Subject: [PATCH 2/5] fix reference name; update description --- source/docs/transportation/routee-v3/spec.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/docs/transportation/routee-v3/spec.yml b/source/docs/transportation/routee-v3/spec.yml index a60a0905..f535bd26 100644 --- a/source/docs/transportation/routee-v3/spec.yml +++ b/source/docs/transportation/routee-v3/spec.yml @@ -1,7 +1,7 @@ openapi: 3.0.0 info: title: RouteE API - description: The Route Energy Prediction Model (RouteE) predicts the energy consumption of a given vehicle over a link or sequence of links (route) in a road network. These API endpoints can be used to get single vehicle link or route energy estimates (`/powertrain/route`) and eco-routing between an origin and destination for a specific vehicle (`/compass/route`). For more on RouteE, please visit . + description: The Route Energy Prediction Model (RouteE) predicts the energy consumption of a given vehicle over a link or sequence of links (route) in a road network. These API endpoints can be used to get single vehicle link or route energy estimates (`/powertrain/route`) and energy aware routes between an origin and destination for a specific vehicle (`/compass/route`). For more on RouteE, please visit . version: "3.0" servers: - url: https://developer.nrel.gov/routee/api/v3 @@ -111,7 +111,7 @@ components: format: float description: The exit angle of the link in degrees nullable: true - RouteRequest: + PowertrainRequest: type: object required: [powertrain_model, links] properties: @@ -123,7 +123,7 @@ components: description: A list of links that make up the route items: $ref: "#/components/schemas/PowertrainLink" - RouteResponse: + PowertrainResponse: type: object properties: route: From fa9da4bb3be82e473c7909a0b6c6d135295ad445 Mon Sep 17 00:00:00 2001 From: Nicholas Reinicke Date: Wed, 28 Aug 2024 10:16:01 -0600 Subject: [PATCH 3/5] update url --- source/docs/transportation/routee-v3/spec.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/docs/transportation/routee-v3/spec.yml b/source/docs/transportation/routee-v3/spec.yml index f535bd26..c22a303c 100644 --- a/source/docs/transportation/routee-v3/spec.yml +++ b/source/docs/transportation/routee-v3/spec.yml @@ -4,7 +4,7 @@ info: description: The Route Energy Prediction Model (RouteE) predicts the energy consumption of a given vehicle over a link or sequence of links (route) in a road network. These API endpoints can be used to get single vehicle link or route energy estimates (`/powertrain/route`) and energy aware routes between an origin and destination for a specific vehicle (`/compass/route`). For more on RouteE, please visit . version: "3.0" servers: - - url: https://developer.nrel.gov/routee/api/v3 + - url: https://developer.nrel.gov/api/routee/v3 paths: /powertrain/route: post: From 97f55edc9966b7b93b5c8d5254f96f19612b0780 Mon Sep 17 00:00:00 2001 From: Nicholas Reinicke Date: Wed, 28 Aug 2024 10:50:27 -0600 Subject: [PATCH 4/5] disclaimer about compass in colorado. --- source/docs/transportation/routee-v3/spec.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/docs/transportation/routee-v3/spec.yml b/source/docs/transportation/routee-v3/spec.yml index c22a303c..e76504b4 100644 --- a/source/docs/transportation/routee-v3/spec.yml +++ b/source/docs/transportation/routee-v3/spec.yml @@ -42,7 +42,7 @@ paths: post: summary: Energy aware routing requestBody: - description: A JSON object with your route request. + description: A JSON object with your route request. Note, this currently only provides routes for the state of Colorado. required: true content: application/json: From c009536cd8c50095708633d0c2940ad0be06062f Mon Sep 17 00:00:00 2001 From: Nicholas Reinicke Date: Wed, 4 Sep 2024 10:36:03 -0600 Subject: [PATCH 5/5] include example values in documentation --- source/docs/transportation/routee-v3/spec.yml | 29 ++++++++++--------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/source/docs/transportation/routee-v3/spec.yml b/source/docs/transportation/routee-v3/spec.yml index e76504b4..51f262ee 100644 --- a/source/docs/transportation/routee-v3/spec.yml +++ b/source/docs/transportation/routee-v3/spec.yml @@ -88,29 +88,23 @@ components: id: type: string description: The unique identifier for the link + example: 1 miles: type: number format: float description: The length of the link in miles + example: 0.1 speed_mph: type: number format: float description: The speed of the link in miles per hour - grade_dec: + example: 30 + grade_percent: type: number format: float - description: The grade of the link in decimal form (i.e. 0.05 for 5% grade) - nullable: true - entry_angle: - type: number - format: float - description: The entry angle of the link in degrees - nullable: true - exit_angle: - type: number - format: float - description: The exit angle of the link in degrees + description: The grade of the link in percent form (i.e. 5% grade) nullable: true + example: 5 PowertrainRequest: type: object required: [powertrain_model, links] @@ -118,6 +112,7 @@ components: powertrain_model: type: string description: The powertrain model to use for the energy estimate + example: 2016_TOYOTA_Corolla_4cyl_2WD links: type: array description: A list of links that make up the route @@ -160,35 +155,41 @@ components: type: number format: float description: The latitude of the origin + example: 39.740434 origin_lon: type: number format: float description: The longitude of the origin + example: -105.167987 destination_lat: type: number format: float description: The latitude of the destination + example: 40.018901 destination_lon: type: number format: float description: The longitude of the destination + example: -105.280362 model_name: type: string description: The name of the RouteE Powertrain vehicle model to use for the energy estimate + example: "2016_TOYOTA_Corolla_4cyl_2WD" start_time: type: string - default: "09:00:00" description: The start time for the route (in 24-hour format) + example: "09:00:00" start_weekday: type: string - default: "monday" description: The start weekday for the route + example: "monday" vehicle_rates: type: object description: The vehicle rates for the route weights: type: object description: The weights for the state model + example: {"distance": 1, "energy_liquid": 1, "energy_electric": 1, "time": 1} CompassResponse: type: object properties: