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..51f262ee --- /dev/null +++ b/source/docs/transportation/routee-v3/spec.yml @@ -0,0 +1,229 @@ +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 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/api/routee/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. Note, this currently only provides routes for the state of Colorado. + 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 + 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 + example: 30 + grade_percent: + type: number + format: float + description: The grade of the link in percent form (i.e. 5% grade) + nullable: true + example: 5 + PowertrainRequest: + type: object + required: [powertrain_model, links] + properties: + 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 + items: + $ref: "#/components/schemas/PowertrainLink" + PowertrainResponse: + 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 + 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 + description: The start time for the route (in 24-hour format) + example: "09:00:00" + start_weekday: + type: string + 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: + 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: []