diff --git a/tdei-api-gateway-prod.json b/tdei-api-gateway-prod.json index e98323b..2f47b7e 100644 --- a/tdei-api-gateway-prod.json +++ b/tdei-api-gateway-prod.json @@ -143,13 +143,13 @@ "Common APIs" ], "summary": "Lists the TDEI datasets in the system.", - "description": "This API lists all TDEI datasets, allowing users to efficiently search with sorting and filtering features. Each dataset entry is uniquely identified by `tdei_dataset_id` and also provide detailed information including metadata, associated project group, service details, download URL, and status. Users can sort datasets by 'valid_to', 'valid_from', 'uploaded date', 'project group name', and 'status'. Filtering options are provided for enhanced discoverability of the datasets.By default all released datasets are visible to all user. Pre-release datasets are only visible to user affiliated with the project groups.", + "description": "This API returns filtered and sorted lists of TDEI datasets. All text parameters x return datasets with attribute containing x, as opposed to exact match. By default results will include all datasets in released status AND all dataset in pre-release status within the requesting user's project group. This behavior can be controlled by the status parameter. In no situation can a user see pre-release datasets from a project group the user is not part of. Primary use cases include: name search: Given a search string X, return all datasets with a name that contains the search string X) dataset id lookup: Given a tdei_dataset_id, return the dataset with the matching id bounding box: Given xmin, xmax, ymin, ymax, return datasets with dataset_area overlapping the bounding box Sorting: Users can sort datasets by 'valid_to', 'valid_from', 'uploaded date', 'project group name', and 'status'.", "operationId": "listDatasetFiles", "parameters": [ { "name": "data_type", "in": "query", - "description": "Type of the dataset.", + "description": "Type of the dataset. Filters datasets by matching the exact value from the supported enumeration.", "required": false, "schema": { "type": "string", @@ -163,7 +163,7 @@ { "name": "status", "in": "query", - "description": "This filter allows users to request datasets based on their status. When set to 'All', the filter displays all available datasets by default. If specified as 'Pre-Release' or 'Publish', it shows only the datasets that are in the Pre-Release or Publish stages, respectively, for the project groups the user is affiliated with.", + "description": "

Status of the dataset: Filters datasets by status — All (default) returns released datasets and pre-release datasets from the user's project groups; Pre-Release and Publish return only datasets in that status from affiliated project groups.

", "required": false, "schema": { "type": "string", @@ -178,7 +178,7 @@ { "name": "name", "in": "query", - "description": "Dataset name or title", + "description": "

Dataset name or title: Filters datasets where the name or title contains the specified search text.

", "required": false, "schema": { "type": "string" @@ -187,7 +187,7 @@ { "name": "version", "in": "query", - "description": "Dataset version.", + "description": "

Dataset version: Filters datasets using an exact match on the version value.

", "required": false, "schema": { "type": "string" @@ -196,7 +196,7 @@ { "name": "data_source", "in": "query", - "description": "Data source of the dataset.", + "description": "

Data source: Filters datasets by matching the exact value from the supported enumeration.

", "required": false, "schema": { "type": "string", @@ -210,7 +210,7 @@ { "name": "collection_method", "in": "query", - "description": "Method by which the data was collected.", + "description": "

Collection method: Filters datasets by matching the exact value from the supported enumeration.

", "required": false, "schema": { "type": "string", @@ -225,7 +225,7 @@ { "name": "collected_by", "in": "query", - "description": "Collection agency or person.", + "description": "

Collected by: Filters datasets using an exact match on the collection agency or person's name.

", "required": false, "schema": { "type": "string" @@ -234,7 +234,7 @@ { "name": "derived_from_dataset_id", "in": "query", - "description": "Dataset id from which this dataset was derived.", + "description": "derived_from_dataset_id: Filters datasets that are derived from the specified dataset ID. Exact match.", "required": false, "schema": { "type": "string" @@ -243,7 +243,7 @@ { "name": "collection_date", "in": "query", - "description": "Collection date time", + "description": "collection_date: Filters datasets collected after the specified date and time.", "required": false, "schema": { "type": "string" @@ -251,7 +251,7 @@ }, { "name": "confidence_level", - "description": "Minimum confidence level required. Data returned will be at this confidence level or higher. Confidence level range is: 0 (very low confidence) to 100 (very high confidence).", + "description": "Confidence level: Minimum confidence level required. Returns datasets with confidence level greater than the specified value. Range: 0 (very low) to 100 (very high).", "schema": { "type": "integer" }, @@ -260,7 +260,7 @@ { "name": "schema_version", "in": "query", - "description": "Version name of the data type schema version that the application requests. list of versions can be found with /api/v1/{data_type}/versions.", + "description": "Schema version: Filters datasets that match the requested data type schema version. The list of supported versions can be found at /api/v1/{data_type}/versions.", "required": false, "schema": { "type": "string" @@ -269,7 +269,7 @@ { "name": "tdei_project_group_id", "in": "query", - "description": "TDEI project group id of the datasets to be retrieved.", + "description": "TDEI project group ID: Filters datasets that belong to the specified project group. Exact match.", "required": false, "schema": { "type": "string" @@ -278,7 +278,7 @@ { "name": "tdei_service_id", "in": "query", - "description": "TDEI service id of the datasets to be retrieved.", + "description": "TDEI service ID: Filters datasets that belong to the specified TDEI service. Exact match.", "required": false, "schema": { "type": "string" @@ -287,7 +287,7 @@ { "name": "valid_from", "in": "query", - "description": "Valid from date time. Date-time for which datasets to be retrieved.", + "description": "Valid from: Filters datasets with a valid-from date later than the specified date-time.", "required": false, "schema": { "type": "string" @@ -296,7 +296,7 @@ { "name": "valid_to", "in": "query", - "description": "Valid to date time. Date-time for which datasets to be retrieved.", + "description": "Valid to: Filters datasets with a valid-to date earlier than the specified date-time.", "required": false, "schema": { "type": "string" @@ -305,7 +305,7 @@ { "name": "tdei_dataset_id", "in": "query", - "description": "tdei_dataset_id of the dataset to be retrieved.", + "description": "TDEI dataset ID: Filters datasets by the specified TDEI dataset ID.", "required": false, "schema": { "type": "string" @@ -314,7 +314,7 @@ { "name": "bbox", "in": "query", - "description": "A bounding box which specifies the area to be searched. A bounding box is specified by a string providing the lat/lon coordinates of the corners of the bounding box. Coordinate should be specified as west, south, east, north.", + "description": "Bounding box: Specifies the geographic area to search within, using a bounding box defined by four coordinates in the order: west, south, east, north. Accepts an array of four numeric values.", "required": false, "schema": { "maxItems": 4, @@ -335,7 +335,7 @@ { "name": "other_published_locations", "in": "query", - "description": "Other published locations", + "description": "Other published locations: Lists additional places where the dataset has been published. Supports contains match.", "required": false, "schema": { "type": "string" @@ -344,7 +344,7 @@ { "name": "dataset_update_frequency_months", "in": "query", - "description": "Dataset update frequency in months", + "description": "Dataset update frequency in months: Filters datasets based on how frequently they are updated. Uses a greater than or equal to match to include datasets updated at this frequency or more often.", "required": false, "schema": { "type": "integer" @@ -353,7 +353,7 @@ { "name": "schema_validation_run_description", "in": "query", - "description": "Schema validation run description", + "description": "Schema validation run description: Filters datasets based on the description of the schema validation run. Accepts a string value and uses contains match.", "required": false, "schema": { "type": "string" @@ -362,7 +362,7 @@ { "name": "full_dataset_name", "in": "query", - "description": "Full dataset name", + "description": "Full dataset name: Filters datasets based on their full name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -371,7 +371,7 @@ { "name": "collection_name", "in": "query", - "description": "Name of the collection", + "description": "Collection name: Filters datasets based on their collection name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -380,7 +380,7 @@ { "name": "department_name", "in": "query", - "description": "Name of the department", + "description": "Department name: Filters datasets based on their department name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -389,7 +389,7 @@ { "name": "city", "in": "query", - "description": "Name of the city", + "description": "Name of City: Filters datasets based on the city name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -398,7 +398,7 @@ { "name": "region", "in": "query", - "description": "Name of the region", + "description": "Region: Filters datasets based on the region name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -407,7 +407,7 @@ { "name": "county", "in": "query", - "description": "Name of the county", + "description": "County: Filters datasets based on the county name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -416,7 +416,7 @@ { "name": "key_limitations", "in": "query", - "description": "Key limitations of the dataset", + "description": "Key limitations: Filters datasets based on their key limitations. Supports contains match.", "required": false, "schema": { "type": "string" @@ -425,7 +425,7 @@ { "name": "release_notes", "in": "query", - "description": "Release notes", + "description": "Release notes: Filters datasets based on their release notes. Supports contains match.", "required": false, "schema": { "type": "string" @@ -434,7 +434,7 @@ { "name": "challenges", "in": "query", - "description": "Challenges faced in collecting the data", + "description": "Challenges: Filters datasets based on the challenges faced in collecting the data. Supports contains match.", "required": false, "schema": { "type": "string" @@ -443,7 +443,7 @@ { "name": "official_maintainer", "in": "query", - "description": "Official maintainer of the dataset", + "description": "Official maintainer: Filters datasets based on the official maintainer. Supports contains match.", "required": false, "schema": { "type": "array", @@ -455,7 +455,7 @@ { "name": "last_updated", "in": "query", - "description": "Date when the dataset was last updated", + "description": "Last updated: Filters datasets based on the last updated date. Accepts a date-time string match.", "required": false, "schema": { "type": "string" @@ -464,7 +464,7 @@ { "name": "update_frequency", "in": "query", - "description": "Frequency of updates", + "description": "Update frequency: Filters datasets based on their update frequency. Supports contains match.", "required": false, "schema": { "type": "string" @@ -473,7 +473,7 @@ { "name": "authorization_chain", "in": "query", - "description": "Authorization chain", + "description": "Authorization chain: Filters datasets based on their authorization chain. Supports contains match.", "required": false, "schema": { "type": "string" @@ -482,7 +482,7 @@ { "name": "maintenance_funded", "in": "query", - "description": "Is maintenance funded", + "description": "Maintenance funded: Filters datasets based on whether they are funded for maintenance. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -491,7 +491,7 @@ { "name": "funding_details", "in": "query", - "description": "Funding details", + "description": "Funding details: Filters datasets based on their funding details. Supports contains match.", "required": false, "schema": { "type": "string" @@ -500,7 +500,7 @@ { "name": "point_data_collection_device", "in": "query", - "description": "Point data collection device", + "description": "Point data collection device: Filters datasets based on the device used for point data collection. Supports contains match.", "required": false, "schema": { "type": "string" @@ -509,7 +509,7 @@ { "name": "node_locations_and_attributes_editing_software", "in": "query", - "description": "Node locations and attributes editing software", + "description": "Node locations and attributes editing software: Filters datasets based on the software used for editing node locations and attributes. Supports contains match.", "required": false, "schema": { "type": "string" @@ -518,7 +518,7 @@ { "name": "data_collected_by_people", "in": "query", - "description": "Is data collected by people", + "description": "Data collected by people: Filters datasets based on whether the data was collected by people. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -527,7 +527,7 @@ { "name": "data_collectors", "in": "query", - "description": "Data collectors", + "description": "Data collectors: Filters datasets based on the individuals or organizations that collected the data. Supports contains match.", "required": false, "schema": { "type": "string" @@ -536,7 +536,7 @@ { "name": "data_captured_automatically", "in": "query", - "description": "Is data captured automatically", + "description": "Data captured automatically: Filters datasets based on whether the data was captured automatically. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -545,7 +545,7 @@ { "name": "automated_collection", "in": "query", - "description": "Automated collection", + "description": "Automated collection: Filters datasets based on whether the data was collected automatically. Supports contains match.", "required": false, "schema": { "type": "string" @@ -554,7 +554,7 @@ { "name": "data_collectors_organization", "in": "query", - "description": "Data collectors organization", + "description": "Data collectors organization: Filters datasets based on the organization of the data collectors. Supports contains match.", "required": false, "schema": { "type": "string" @@ -563,7 +563,7 @@ { "name": "data_collector_compensation", "in": "query", - "description": "Data collector compensation", + "description": "Data collector compensation: Filters datasets based on whether the data collectors were compensated. Supports contains match.", "required": false, "schema": { "type": "string" @@ -572,7 +572,7 @@ { "name": "preprocessing_location", "in": "query", - "description": "Preprocessing location", + "description": "Preprocessing location: Filters datasets based on their preprocessing location. Supports contains match.", "required": false, "schema": { "type": "string" @@ -581,7 +581,7 @@ { "name": "preprocessing_by", "in": "query", - "description": "Preprocessing by", + "description": "Preprocessing by: Filters datasets based on who performed the preprocessing. Supports contains match.", "required": false, "schema": { "type": "string" @@ -590,7 +590,7 @@ { "name": "preprocessing_steps", "in": "query", - "description": "Preprocessing steps", + "description": "Preprocessing steps: Filters datasets based on their preprocessing steps. Supports contains match.", "required": false, "schema": { "type": "string" @@ -599,7 +599,7 @@ { "name": "data_collection_preprocessing_documentation", "in": "query", - "description": "Is data collection preprocessing documentation available", + "description": "Data collection preprocessing documentation: Filters datasets based on the availability of data collection preprocessing documentation. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -608,7 +608,7 @@ { "name": "documentation_uri", "in": "query", - "description": "Documentation URI", + "description": "Documentation URI: Filters datasets based on their documentation URI. Supports contains match.", "required": false, "schema": { "type": "string" @@ -617,7 +617,7 @@ { "name": "validation_process_exists", "in": "query", - "description": "Is validation process exists", + "description": "Validation process exists: Filters datasets based on whether a validation process exists. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -626,7 +626,7 @@ { "name": "validation_process_description", "in": "query", - "description": "Validation process description", + "description": "Validation process description: Filters datasets based on the description of the validation process. Supports contains match.", "required": false, "schema": { "type": "string" @@ -635,7 +635,7 @@ { "name": "validation_conducted_by", "in": "query", - "description": "Validation conducted by", + "description": "Validation conducted by: Filters datasets based on who conducted the validation. Supports contains match.", "required": false, "schema": { "type": "string" @@ -644,7 +644,7 @@ { "name": "excluded_data", "in": "query", - "description": "Excluded data", + "description": "Excluded data: Filters datasets based on whether they contain excluded data. Supports contains match.", "required": false, "schema": { "type": "string" @@ -653,16 +653,25 @@ { "name": "excluded_data_reason", "in": "query", - "description": "Excluded data reason", + "description": "Excluded data reason: Filters datasets based on the reason for excluding data. Supports contains match.", "required": false, "schema": { "type": "string" } }, + { + "name": "data_viewer_allowed", + "in": "query", + "description": "Data viewer allowed: Filters datasets based on whether data viewer access is allowed. Uses a boolean value.", + "required": false, + "schema": { + "type": "boolean" + } + }, { "name": "page_no", "in": "query", - "description": "Integer, defaults to 1. Retrieves the results in pages.", + "description": "page_no: Integer, defaults to 1. Filters datasets by retrieving results in pages.", "required": false, "schema": { "type": "integer", @@ -673,7 +682,7 @@ { "name": "page_size", "in": "query", - "description": "Page size. integer, between 1 to 50, defaults to 10.Specifies total records per page.", + "description": "Page size: Integer, between 1 to 50, defaults to 10.Specifies total records per page.", "required": false, "schema": { "type": "integer", @@ -684,7 +693,7 @@ { "name": "sort_field", "in": "query", - "description": "Sort field. By default, it is by uploaded timestamp.", + "description": "Sort field: The field by which to sort the results. By default, it is by uploaded timestamp. Matches the exact value from the supported enumeration.", "required": false, "schema": { "type": "string", @@ -701,7 +710,7 @@ { "name": "sort_order", "in": "query", - "description": "Sort order. By default, it is in descending order.", + "description": "Sort order: By default, it is in descending order.", "required": false, "schema": { "type": "string", @@ -2227,107 +2236,67 @@ ] } }, - "/api/v1/gtfs-flex/upload/{tdei_project_group_id}/{tdei_service_id}": { + "/api/v1/osw/dataset-viewer/{tdei_dataset_id}": { "post": { "tags": [ - "GTFS Flex" + "OSW" ], - "summary": "Upload a GTFS Flex dataset.", - "description": "This endpoint enables users to upload a GTFS-Flex dataset. The request must include the required parameters to complete the upload. The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint. By default, the dataset's status will be set to 'pre-release.' The dataset can be published using the /publish endpoint.", - "operationId": "uploadGtfsFlexFile", + "summary": "Updates the visibility preferences for the dataset viewer.", + "description": "Updates the visibility preferences for a specified dataset identified by the tdei_dataset_id. It takes the dataset ID as a parameter and modifies the dataset's visibility settings.", + "operationId": "oswDatasetViewer", "parameters": [ { - "name": "tdei_project_group_id", - "in": "path", - "description": "Project group id to which the dataset would be uploaded", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "tdei_service_id", + "name": "tdei_dataset_id", "in": "path", - "description": "TDEI service id associated with the above project group id.", + "description": "Dataset ID for updating the dataset viewer preferences.", "required": true, "schema": { "type": "string" } - }, - { - "name": "derived_from_dataset_id", - "in": "query", - "description": "Dataset id from which this dataset was derived.", - "required": false, - "schema": { - "type": "string" - } } ], "requestBody": { "content": { - "multipart/form-data": { + "application/json": { "schema": { - "required": [ - "dataset", - "metadata" - ], "type": "object", "properties": { - "dataset": { - "type": "string", - "format": "binary", - "description": "GTFS Flex file which is expected to be a zip file. It typically includes .txt files that define details such as service areas and stops for flexible transit routes." - }, - "metadata": { - "type": "string", - "format": "binary", - "description": "Metadata information for the GTFS-Flex dataset. This is a JSON file that includes details on how and when the data was collected, the file's valid dates, and other relevant information about the dataset. For more details, refer to the [metadata schema](https://raw.githubusercontent.com/TaskarCenterAtUW/TDEI-osw-datasvc-ts/master/schema/metadata.schema.json)." - }, - "changeset": { - "type": "string", - "format": "binary", - "description": "The changeset file records modifications to the sidewalk network included in the GTFS-Flex dataset. It supports file formats with either .zip or .osc extensions." + "allow_viewer_access": { + "type": "boolean", + "default": true, + "description": "Indicates whether the dataset viewer access is allowed." } - } + }, + "required": [ + "allow_viewer_access" + ] } } }, "required": true }, "responses": { - "202": { - "description": "The upload request has been accepted for processing. It returns a `job_id`, a unique identifier for the uploaded request, which can be used to track the status of the upload. The endpoint to check the status is provided in the `location` header of the response.", + "200": { + "description": "Visibility preferences for the dataset viewer updated successfully.", "content": { "application/text": { "schema": { "type": "string" } } - }, - "headers": { - "Location": { - "schema": { - "type": "string" - }, - "description": "Location api to find the status of request processing" - } } }, - "400": { - "description": "The request's input parameters are invalid." - }, "401": { "description": "Unauthenticated request. Check your access token." }, "403": { - "description": "User unauthorized to upload the dataset." + "description": "Forbidden request. Dataset viewer access is not allowed at project group level." }, "404": { - "description": "derived_from_dataset_id, tdei_project_group_id or tdei_service_id doesn't exist in the system" + "description": "tdei_dataset_id doesn't exist in the system." }, "500": { - "description": "An Internal server error occured" + "description": "An server error occurred." } }, "security": [ @@ -2337,19 +2306,19 @@ ] } }, - "/api/v1/gtfs-flex/publish/{tdei_dataset_id}": { - "post": { + "/api/v1/osw/dataset-viewer/pm-tiles/{tdei_dataset_id}": { + "get": { "tags": [ - "GTFS Flex" + "OSW" ], - "summary": "Publishes the GTFS Flex dataset for the tdei_dataset_id", - "description": "Publishes a GTFS Flex dataset that was previously uploaded via the [POST] /gtfs-flex endpoint, marking it as an official release for the mobility service. This official release status ensures visibility to all TDEI data consumers. The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint.", - "operationId": "publishGtfsFlexFile", + "summary": "Retrives the PM tiles SAS url for the dataset.", + "description": "Retrieves the PM tiles SAS url for a specified dataset identified by the tdei_dataset_id.", + "operationId": "oswDatasetViewerPMTiles", "parameters": [ { "name": "tdei_dataset_id", "in": "path", - "description": "Dataset id of the dataset to be published", + "description": "Dataset ID for retrieving the PM tiles SAS url.", "required": true, "schema": { "type": "string" @@ -2357,111 +2326,135 @@ } ], "responses": { - "202": { - "description": "The publish request has been accepted for processing. It returns a `job_id`, a unique identifier for the published request, which can be used to track the status of the request. The endpoint to check the status is provided in the location header of the response.", + "200": { + "description": "PM tiles SAS url retrieved successfully.", "content": { "application/text": { "schema": { "type": "string" } } - }, - "headers": { - "Location": { - "schema": { - "type": "string" - }, - "description": "Location api to find the status of request processing" - } } }, - "400": { - "description": "The request fails to match the publish criteria." - }, "401": { "description": "Unauthenticated request. Check your access token." }, "403": { - "description": "User unauthorized to publish the dataset." + "description": "Forbidden request. Dataset viewer access is not allowed at dataset or project group level." }, "404": { - "description": "Dataset with the specified tdei_dataset_id was not found. Use the [GET] /api/v1/gtfs-flex endpoint to find valid dataset ids.", - "content": { - "text/plain": {} - } + "description": "tdei_dataset_id doesn't exist in the system." }, "500": { - "description": "An Internal server error occured" + "description": "An server error occurred." } }, "security": [ - { - "ApiKey": [] - }, { "AuthorizationToken": [] } ] } }, - "/api/v1/gtfs-flex/validate": { + "/api/v1/osw/dataset-viewer/feedbacks/{project_id}/{tdei_dataset_id}": { "post": { "tags": [ - "GTFS Flex" + "OSW" + ], + "summary": "Accepts the feedback from the dataset viewer.", + "description": "Accepts the feedback from the dataset viewer. The feedback is stored in the system for further analysis and improvement of the dataset.", + "operationId": "oswDatasetViewerFeedback", + "parameters": [ + { + "name": "project_id", + "in": "path", + "required": true, + "description": "ID of the project group.", + "schema": { + "type": "string" + } + }, + { + "name": "tdei_dataset_id", + "in": "path", + "required": true, + "description": "ID of the dataset.", + "schema": { + "type": "string" + } + } ], - "summary": "Validates the GTFS Flex dataset.", - "description": "Allows a user to validate GTFS Flex dataset to check the correctness of data. The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint.", - "operationId": "validateGtfsFlexFile", "requestBody": { "content": { - "multipart/form-data": { + "application/json": { "schema": { - "required": [ - "dataset" - ], "type": "object", "properties": { - "dataset": { + "dataset_element_id": { "type": "string", - "format": "binary", - "description": "GTFS Flex file which is expected to be a zip file. It typically includes .txt files that define details such as service areas and stops for flexible transit routes." + "description": "Dataset ID for which the feedback is provided.", + "example": "14325" + }, + "feedback_text": { + "type": "string", + "description": "Feedback provided by the user regarding the dataset viewer.", + "example": "The dataset viewer is very informative and easy to use." + }, + "customer_email": { + "type": "string", + "format": "email", + "description": "Email address of the user providing feedback. This is optional and can be used for follow-up if needed.", + "example": "user@example.com" + }, + "location_latitude": { + "type": "number", + "format": "double", + "description": "Latitude of the location where the feedback was provided." + }, + "location_longitude": { + "type": "number", + "format": "double", + "description": "Longitude of the location where the feedback was provided." } - } + }, + "required": [ + "feedback_text", + "location", + "customer_email" + ] } } }, "required": true }, "responses": { - "202": { - "description": "The validate request has been accepted for processing. It returns a `job_id`, a unique identifier for the validate request, which can be used to track the status of the validate request. The endpoint to check the status is provided in the location header of the response.", + "200": { + "description": "Feedback submitted successfully.", "content": { - "application/text": { + "application/json": { "schema": { - "type": "string" + "type": "object", + "properties": { + "message": { + "type": "string", + "example": "Feedback submitted successfully." + } + } } } - }, - "headers": { - "Location": { - "schema": { - "type": "string" - }, - "description": "Location api to find the status of request processing" - } } }, "400": { - "description": "Dataset input file not found." - }, - "401": { - "description": "Unauthenticated request. Check your access token." + "description": "Invalid input parameters." }, "403": { - "description": "User unauthorized to validate the dataset." + "description": "CORS error. The request is not allowed from the current origin." + }, + "404": { + "description": "Project group or dataset not found." }, "500": { - "description": "An Internal server error occured" + "description": "An server error occurred." } }, "security": [ @@ -2471,61 +2464,656 @@ ] } }, - "/api/v1/gtfs-flex/{tdei_dataset_id}": { + "/api/v1/osw/dataset-viewer/feedbacks": { "get": { "tags": [ - "GTFS Flex" + "OSW" ], - "summary": "Downloads the GTFS Flex dataset", - "description": "Downloads a specific GTFS Flex dataset as zip containing .txt files that define details such as service areas and stops for flexible transit routes.", - "operationId": "getGtfsFlexFile", + "summary": "Retrieves the dataset viewer feedbacks.", + "description": "Retrieves the dataset viewer feedbacks. Response includes a list of feedbacks provided by users regarding the dataset. Each feedback contains details such as the dataset element ID, feedback text, customer email, and location information.", + "operationId": "oswDatasetViewerFeedbacks", "parameters": [ { - "name": "tdei_dataset_id", - "in": "path", - "description": "Dataset id of the dataset to be downloaded.", - "required": true, + "name": "tdei_project_group_id", + "in": "query", + "required": false, + "description": "ID of the project group.", "schema": { "type": "string" } - } - ], - "responses": { - "200": { - "description": "Streams the dataset zip file.", - "content": { - "application/octet-stream": {} + }, + { + "name": "tdei_dataset_id", + "in": "query", + "required": false, + "description": "ID of the dataset.", + "schema": { + "type": "string" } }, - "400": { - "description": "tdei_dataset_id is not of type GTFS-Flex." + { + "name": "from_date", + "in": "query", + "description": "from_date: Date in ISO 8601 format, filters feedbacks created after this date.", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } }, - "401": { - "description": "Unauthenticated request. Check your access token." + { + "name": "to_date", + "in": "query", + "description": "to_date: Date in ISO 8601 format, filters feedbacks created before this date.", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } }, - "404": { - "description": "A file with the specified tdei_dataset_id was not found. Use the /api/v1/gtfs-flex endpoints to find valid file ids.", - "content": { - "application/json": {} + { + "name": "status", + "in": "query", + "required": false, + "description": "status: Filters feedbacks by their status.", + "schema": { + "type": "string", + "enum": [ + "open", + "resolved" + ] } }, - "500": { - "description": "An Internal server error occured" - } - }, - "security": [ { - "ApiKey": [] + "name": "sort_by", + "in": "query", + "description": "sort_by: String, defaults to 'created_at'. Sorts feedbacks by the specified field.", + "required": false, + "schema": { + "type": "string", + "default": "created_at", + "enum": [ + "created_at", + "due_date" + ] + } }, { - "AuthorizationToken": [] - } - ] - } - }, - "/api/v1/gtfs-flex/versions": { - "get": { - "tags": [ + "name": "sort_order", + "in": "query", + "description": "sort_order: String, defaults to 'desc'. Sorts feedbacks in ascending or descending order.", + "required": false, + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + } + }, + { + "name": "page_no", + "in": "query", + "description": "page_no: Integer, defaults to 1. Specifies the page number to retrieve.", + "required": false, + "schema": { + "type": "integer", + "format": "int32", + "default": 1 + } + }, + { + "name": "page_size", + "in": "query", + "description": "Page size: Integer, between 1 to 50, defaults to 10. Specifies total records per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "responses": { + "200": { + "description": "Feedbacks retrieved successfully.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Feedback" + } + } + } + } + }, + "500": { + "description": "An server error occurred." + } + }, + "security": [ + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/osw/dataset-viewer/feedbacks/download/{tdei_project_group_id}":{ + "get":{ + "tags":[ + "OSW" + ], + "summary":"Downloads dataset viewer feedbacks as a CSV.", + "description":"Streams all feedback for the specified project group in CSV format. Requires poc or osw_data_generator role.", + "operationId":"oswDatasetViewerFeedbacksDownload", + "parameters":[ + { + "name": "tdei_project_group_id", + "in": "path", + "description": "Valid TDEI project group id.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name":"tdei_dataset_id", + "in":"query", + "required":false, + "description":"ID of the dataset.", + "schema":{ + "type":"string" + } + }, + { + "name":"from_date", + "in":"query", + "description":"from_date: Date in ISO 8601 format, filters feedback created after this date.", + "required":false, + "schema":{ + "type":"string", + "format":"date-time" + } + }, + { + "name":"to_date", + "in":"query", + "description":"to_date: Date in ISO 8601 format, filters feedback created before this date.", + "required":false, + "schema":{ + "type":"string", + "format":"date-time" + } + }, + { + "name":"status", + "in":"query", + "required":false, + "description":"status: Filters feedbacks by their status.", + "schema":{ + "type":"string", + "enum":[ + "open", + "resolved" + ] + } + }, + { + "name":"sort_by", + "in":"query", + "description":"sort_by: String, defaults to 'created_at'. Sorts feedbacks by the specified field.", + "required":false, + "schema":{ + "type":"string", + "default":"created_at", + "enum":[ + "created_at", + "due_date" + ] + } + }, + { + "name":"due_date", + "in":"query", + "description":"due_date: Legacy alias for sort_by. Use 'created_at' or 'due_date'.", + "required":false, + "schema":{ + "type":"string", + "enum":[ + "created_at", + "due_date" + ] + } + }, + { + "name":"sort_order", + "in":"query", + "description":"sort_order: String, defaults to 'desc'. Sorts feedbacks in ascending or descending order.", + "required":false, + "schema":{ + "type":"string", + "default":"desc", + "enum":[ + "asc", + "desc" + ] + } + }, + { + "name":"page_no", + "in":"query", + "description":"page_no: Integer, specifies the page number to retrieve. If omitted with page_size, the response is unpaginated.", + "required":false, + "schema":{ + "type":"integer", + "format":"int32" + } + }, + { + "name":"page_size", + "in":"query", + "description":"Page size: Integer, between 1 to 50. If omitted with page_no, the response is unpaginated.", + "required":false, + "schema":{ + "type":"integer", + "format":"int32" + } + }, + { + "name":"format", + "in":"query", + "required":false, + "description":"format: Output format.", + "schema":{ + "type":"string", + "default":"csv", + "enum":[ + "csv", + "geojson" + ] + } + } + ], + "responses":{ + "200": { + "description": "Feedback file streamed successfully.", + "content": { + "text/csv": { + "schema": { "type": "string", "format": "binary" } + }, + "application/geo+json": { + "schema": { + "type": "object", + "required": ["type", "features"], + "properties": { + "type": { "enum": ["FeatureCollection"] }, + "features": { + "type": "array", + "items": { "$ref": "#/components/schemas/Feature" } + } + } + } + } + } + }, + "400":{ + "description":"Invalid request parameters." + }, + "500":{ + "description":"A server error occurred." + } + }, + "security":[ + { + "AuthorizationToken":[ + + ] + } + ] + } + }, + "/api/v1/osw/dataset-viewer/feedbacks/metadata": { + "get": { + "tags": [ + "OSW" + ], + "summary": "Retrieves the feedbacks summary.", + "description": "Retrieves the feedbacks summary. Response includes a summary of feedbacks such as total count, total overdue, and other relevant statistics.", + "operationId": "oswDatasetViewerFeedbacksMetadata", + "parameters": [ + { + "name": "tdei_project_group_id", + "in": "query", + "required": false, + "description": "ID of the project group.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Feedbacks summary retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeedbackMetadata" + } + } + } + }, + "500": { + "description": "An server error occurred." + } + }, + "security": [ + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/gtfs-flex/upload/{tdei_project_group_id}/{tdei_service_id}": { + "post": { + "tags": [ + "GTFS Flex" + ], + "summary": "Upload a GTFS Flex dataset.", + "description": "This endpoint enables users to upload a GTFS-Flex dataset. The request must include the required parameters to complete the upload. The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint. By default, the dataset's status will be set to 'pre-release.' The dataset can be published using the /publish endpoint.", + "operationId": "uploadGtfsFlexFile", + "parameters": [ + { + "name": "tdei_project_group_id", + "in": "path", + "description": "Project group id to which the dataset would be uploaded", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "tdei_service_id", + "in": "path", + "description": "TDEI service id associated with the above project group id.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "derived_from_dataset_id", + "in": "query", + "description": "Dataset id from which this dataset was derived.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "required": [ + "dataset", + "metadata" + ], + "type": "object", + "properties": { + "dataset": { + "type": "string", + "format": "binary", + "description": "GTFS Flex file which is expected to be a zip file. It typically includes .txt files that define details such as service areas and stops for flexible transit routes." + }, + "metadata": { + "type": "string", + "format": "binary", + "description": "Metadata information for the GTFS-Flex dataset. This is a JSON file that includes details on how and when the data was collected, the file's valid dates, and other relevant information about the dataset. For more details, refer to the [metadata schema](https://raw.githubusercontent.com/TaskarCenterAtUW/TDEI-osw-datasvc-ts/master/schema/metadata.schema.json)." + }, + "changeset": { + "type": "string", + "format": "binary", + "description": "The changeset file records modifications to the sidewalk network included in the GTFS-Flex dataset. It supports file formats with either .zip or .osc extensions." + } + } + } + } + }, + "required": true + }, + "responses": { + "202": { + "description": "The upload request has been accepted for processing. It returns a `job_id`, a unique identifier for the uploaded request, which can be used to track the status of the upload. The endpoint to check the status is provided in the `location` header of the response.", + "content": { + "application/text": { + "schema": { + "type": "string" + } + } + }, + "headers": { + "Location": { + "schema": { + "type": "string" + }, + "description": "Location api to find the status of request processing" + } + } + }, + "400": { + "description": "The request's input parameters are invalid." + }, + "401": { + "description": "Unauthenticated request. Check your access token." + }, + "403": { + "description": "User unauthorized to upload the dataset." + }, + "404": { + "description": "derived_from_dataset_id, tdei_project_group_id or tdei_service_id doesn't exist in the system" + }, + "500": { + "description": "An Internal server error occured" + } + }, + "security": [ + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/gtfs-flex/publish/{tdei_dataset_id}": { + "post": { + "tags": [ + "GTFS Flex" + ], + "summary": "Publishes the GTFS Flex dataset for the tdei_dataset_id", + "description": "Publishes a GTFS Flex dataset that was previously uploaded via the [POST] /gtfs-flex endpoint, marking it as an official release for the mobility service. This official release status ensures visibility to all TDEI data consumers. The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint.", + "operationId": "publishGtfsFlexFile", + "parameters": [ + { + "name": "tdei_dataset_id", + "in": "path", + "description": "Dataset id of the dataset to be published", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "202": { + "description": "The publish request has been accepted for processing. It returns a `job_id`, a unique identifier for the published request, which can be used to track the status of the request. The endpoint to check the status is provided in the location header of the response.", + "content": { + "application/text": { + "schema": { + "type": "string" + } + } + }, + "headers": { + "Location": { + "schema": { + "type": "string" + }, + "description": "Location api to find the status of request processing" + } + } + }, + "400": { + "description": "The request fails to match the publish criteria." + }, + "401": { + "description": "Unauthenticated request. Check your access token." + }, + "403": { + "description": "User unauthorized to publish the dataset." + }, + "404": { + "description": "Dataset with the specified tdei_dataset_id was not found. Use the [GET] /api/v1/gtfs-flex endpoint to find valid dataset ids.", + "content": { + "text/plain": {} + } + }, + "500": { + "description": "An Internal server error occured" + } + }, + "security": [ + { + "ApiKey": [] + }, + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/gtfs-flex/validate": { + "post": { + "tags": [ + "GTFS Flex" + ], + "summary": "Validates the GTFS Flex dataset.", + "description": "Allows a user to validate GTFS Flex dataset to check the correctness of data. The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint.", + "operationId": "validateGtfsFlexFile", + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "required": [ + "dataset" + ], + "type": "object", + "properties": { + "dataset": { + "type": "string", + "format": "binary", + "description": "GTFS Flex file which is expected to be a zip file. It typically includes .txt files that define details such as service areas and stops for flexible transit routes." + } + } + } + } + }, + "required": true + }, + "responses": { + "202": { + "description": "The validate request has been accepted for processing. It returns a `job_id`, a unique identifier for the validate request, which can be used to track the status of the validate request. The endpoint to check the status is provided in the location header of the response.", + "content": { + "application/text": { + "schema": { + "type": "string" + } + } + }, + "headers": { + "Location": { + "schema": { + "type": "string" + }, + "description": "Location api to find the status of request processing" + } + } + }, + "400": { + "description": "Dataset input file not found." + }, + "401": { + "description": "Unauthenticated request. Check your access token." + }, + "403": { + "description": "User unauthorized to validate the dataset." + }, + "500": { + "description": "An Internal server error occured" + } + }, + "security": [ + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/gtfs-flex/{tdei_dataset_id}": { + "get": { + "tags": [ + "GTFS Flex" + ], + "summary": "Downloads the GTFS Flex dataset", + "description": "Downloads a specific GTFS Flex dataset as zip containing .txt files that define details such as service areas and stops for flexible transit routes.", + "operationId": "getGtfsFlexFile", + "parameters": [ + { + "name": "tdei_dataset_id", + "in": "path", + "description": "Dataset id of the dataset to be downloaded.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Streams the dataset zip file.", + "content": { + "application/octet-stream": {} + } + }, + "400": { + "description": "tdei_dataset_id is not of type GTFS-Flex." + }, + "401": { + "description": "Unauthenticated request. Check your access token." + }, + "404": { + "description": "A file with the specified tdei_dataset_id was not found. Use the /api/v1/gtfs-flex endpoints to find valid file ids.", + "content": { + "application/json": {} + } + }, + "500": { + "description": "An Internal server error occured" + } + }, + "security": [ + { + "ApiKey": [] + }, + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/gtfs-flex/versions": { + "get": { + "tags": [ "GTFS Flex" ], "summary": "List available GTFS Flex versions", @@ -3678,6 +4266,11 @@ "tdei_project_group_id": { "type": "string", "example": "4e991e7a-5c16-4ebf-ad31-3a3625bcca10" + }, + "dataset_viewer_allowed": { + "type": "boolean", + "default": false, + "description": "Flag to indicate to allow dataset to be viewed on the dataset viewer." } }, "required": [ @@ -3803,16 +4396,171 @@ ], "type": "object", "properties": { - "polygon": { - "$ref": "#/components/schemas/GeoJsonObject" - }, "tdei_project_group_id": { "type": "string", - "description": "Unique id that represents the project group." + "description": "ProjectGroupId uniquely represented in the TDEI system. System generated.", + "default": "0" }, - "project_group_name": { + "name": { "type": "string", "description": "Name of the project group." + }, + "phone": { + "type": "string", + "description": "Phone of the project group for communication." + }, + "url": { + "type": "string", + "description": "Url of the transit project group." + }, + "address": { + "type": "string", + "description": "Address of the transit project group." + }, + "polygon": { + "$ref": "#/components/schemas/Polygon" + }, + "poc": { + "type": "array", + "description": "Project group POC details", + "items": { + "$ref": "#/components/schemas/POC", + "description": "POC details" + } + }, + "data_viewer": { + "type": "object", + "properties": { + "dataset_viewer_allowed": { + "type": "boolean", + "default": false, + "description": "Flag to indicate to allow all datasets within the project group to be viewed on the dataset viewer." + }, + "feedback_turnaround_time": { + "type": "object", + "description": "Feedback turnaround time for the project group.", + "properties": { + "number": { + "type": "integer", + "description": "Number of days for feedback turnaround time." + }, + "unit": { + "type": "string", + "enum": [ + "days", + "months", + "years" + ], + "description": "Unit of time for feedback turnaround time." + } + } + } + }, + "description": "Describes an Project group." + } + } + }, + "POC": { + "type": "object", + "properties": { + "first_name": { + "type": "string" + }, + "last_name": { + "type": "string" + }, + "username": { + "type": "string" + }, + "email": { + "type": "string" + } + }, + "required": [ + "first_name", + "last_name", + "username", + "email" + ] + }, + "Polygon": { + "title": "GeoJSON FeatureCollection", + "type": "object", + "required": [ + "type", + "features" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "FeatureCollection" + ] + }, + "features": { + "type": "array", + "items": { + "title": "GeoJSON Feature", + "type": "object", + "required": [ + "type", + "properties", + "geometry" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "Feature" + ] + }, + "id": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ] + }, + "properties": { + "type": "object" + }, + "geometry": { + "title": "GeoJSON Polygon", + "type": "object", + "required": [ + "type", + "coordinates" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "Polygon" + ] + }, + "coordinates": { + "type": "array", + "items": { + "type": "array", + "minItems": 4, + "items": { + "type": "array", + "minItems": 2, + "maxItems": 2, + "items": { + "type": "number", + "format": "double" + } + } + } + } + } + } + } + } } } }, @@ -4201,6 +4949,115 @@ "dataMetrics", "datasetMetrics" ] + }, + "Feedback": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the feedback.", + "example": "10432" + }, + "project_group": { + "type": "object", + "properties": { + "tdei_project_group_id": { + "type": "string", + "description": "ID of the project group.", + "example": "4e991e7a-5c16-4ebf-ad31-3a3625bcca10" + }, + "name": { + "type": "string", + "description": "Name of the project group." + } + }, + "required": [ + "tdei_project_group_id", + "name" + ] + }, + "dataset": { + "type": "object", + "properties": { + "tdei_dataset_id": { + "type": "string", + "description": "ID of the dataset.", + "example": "4e991e7a-5c16-4ebf-ad31-3a3625bcca10" + }, + "name": { + "type": "string", + "description": "Name of the dataset." + } + }, + "required": [ + "tdei_dataset_id", + "name" + ] + }, + "feedback_text": { + "type": "string", + "description": "Feedback text provided by the user." + }, + "dataset_element_id": { + "type": "string", + "description": "ID of the specific dataset element related to the feedback.", + "example": "10432" + }, + "status": { + "type": "string", + "description": "Status of the feedback.", + "enum": [ + "open", + "resolved" + ] + }, + "location_latitude": { + "type": "number", + "description": "Latitude of the location related to the feedback.", + "example": 37.7749 + }, + "location_longitude": { + "type": "number", + "description": "Longitude of the location related to the feedback.", + "example": -122.4194 + }, + "due_date": { + "type": "string", + "format": "date-time", + "description": "Due date for the feedback response." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the feedback was created." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the feedback was last updated." + } + } + }, + "FeedbackMetadata": { + "type": "object", + "description": "Additional metadata related to the feedback.", + "properties": { + "total_count": { + "type": "number", + "description": "Count of feedback entries.", + "example": 5 + }, + "total_overdues": { + "type": "number", + "description": "Indicates number of overdue feedbacks.", + "example": 0 + }, + "total_open": { + "type": "number", + "description": "Indicates number of open feedbacks.", + "example": 3 + } + } } }, "securitySchemes": { diff --git a/tdei-api-gateway-stage.json b/tdei-api-gateway-stage.json index 9b66480..fca32b1 100644 --- a/tdei-api-gateway-stage.json +++ b/tdei-api-gateway-stage.json @@ -143,13 +143,13 @@ "Common APIs" ], "summary": "Lists the TDEI datasets in the system.", - "description": "This API lists all TDEI datasets, allowing users to efficiently search with sorting and filtering features. Each dataset entry is uniquely identified by `tdei_dataset_id` and also provide detailed information including metadata, associated project group, service details, download URL, and status. Users can sort datasets by 'valid_to', 'valid_from', 'uploaded date', 'project group name', and 'status'. Filtering options are provided for enhanced discoverability of the datasets.By default all released datasets are visible to all user. Pre-release datasets are only visible to user affiliated with the project groups.", + "description": "This API returns filtered and sorted lists of TDEI datasets. All text parameters x return datasets with attribute containing x, as opposed to exact match. By default results will include all datasets in released status AND all dataset in pre-release status within the requesting user's project group. This behavior can be controlled by the status parameter. In no situation can a user see pre-release datasets from a project group the user is not part of. Primary use cases include: name search: Given a search string X, return all datasets with a name that contains the search string X) dataset id lookup: Given a tdei_dataset_id, return the dataset with the matching id bounding box: Given xmin, xmax, ymin, ymax, return datasets with dataset_area overlapping the bounding box Sorting: Users can sort datasets by 'valid_to', 'valid_from', 'uploaded date', 'project group name', and 'status'.", "operationId": "listDatasetFiles", "parameters": [ { "name": "data_type", "in": "query", - "description": "Type of the dataset.", + "description": "Type of the dataset. Filters datasets by matching the exact value from the supported enumeration.", "required": false, "schema": { "type": "string", @@ -163,7 +163,7 @@ { "name": "status", "in": "query", - "description": "This filter allows users to request datasets based on their status. When set to 'All', the filter displays all available datasets by default. If specified as 'Pre-Release' or 'Publish', it shows only the datasets that are in the Pre-Release or Publish stages, respectively, for the project groups the user is affiliated with.", + "description": "

Status of the dataset: Filters datasets by status — All (default) returns released datasets and pre-release datasets from the user's project groups; Pre-Release and Publish return only datasets in that status from affiliated project groups.

", "required": false, "schema": { "type": "string", @@ -178,7 +178,7 @@ { "name": "name", "in": "query", - "description": "Dataset name or title", + "description": "

Dataset name or title: Filters datasets where the name or title contains the specified search text.

", "required": false, "schema": { "type": "string" @@ -187,7 +187,7 @@ { "name": "version", "in": "query", - "description": "Dataset version.", + "description": "

Dataset version: Filters datasets using an exact match on the version value.

", "required": false, "schema": { "type": "string" @@ -196,7 +196,7 @@ { "name": "data_source", "in": "query", - "description": "Data source of the dataset.", + "description": "

Data source: Filters datasets by matching the exact value from the supported enumeration.

", "required": false, "schema": { "type": "string", @@ -210,7 +210,7 @@ { "name": "collection_method", "in": "query", - "description": "Method by which the data was collected.", + "description": "

Collection method: Filters datasets by matching the exact value from the supported enumeration.

", "required": false, "schema": { "type": "string", @@ -225,7 +225,7 @@ { "name": "collected_by", "in": "query", - "description": "Collection agency or person.", + "description": "

Collected by: Filters datasets using an exact match on the collection agency or person's name.

", "required": false, "schema": { "type": "string" @@ -234,7 +234,7 @@ { "name": "derived_from_dataset_id", "in": "query", - "description": "Dataset id from which this dataset was derived.", + "description": "derived_from_dataset_id: Filters datasets that are derived from the specified dataset ID. Exact match.", "required": false, "schema": { "type": "string" @@ -243,7 +243,7 @@ { "name": "collection_date", "in": "query", - "description": "Collection date time", + "description": "collection_date: Filters datasets collected after the specified date and time.", "required": false, "schema": { "type": "string" @@ -251,7 +251,7 @@ }, { "name": "confidence_level", - "description": "Minimum confidence level required. Data returned will be at this confidence level or higher. Confidence level range is: 0 (very low confidence) to 100 (very high confidence).", + "description": "Confidence level: Minimum confidence level required. Returns datasets with confidence level greater than the specified value. Range: 0 (very low) to 100 (very high).", "schema": { "type": "integer" }, @@ -260,7 +260,7 @@ { "name": "schema_version", "in": "query", - "description": "Version name of the data type schema version that the application requests. list of versions can be found with /api/v1/{data_type}/versions.", + "description": "Schema version: Filters datasets that match the requested data type schema version. The list of supported versions can be found at /api/v1/{data_type}/versions.", "required": false, "schema": { "type": "string" @@ -269,7 +269,7 @@ { "name": "tdei_project_group_id", "in": "query", - "description": "TDEI project group id of the datasets to be retrieved.", + "description": "TDEI project group ID: Filters datasets that belong to the specified project group. Exact match.", "required": false, "schema": { "type": "string" @@ -278,7 +278,7 @@ { "name": "tdei_service_id", "in": "query", - "description": "TDEI service id of the datasets to be retrieved.", + "description": "TDEI service ID: Filters datasets that belong to the specified TDEI service. Exact match.", "required": false, "schema": { "type": "string" @@ -287,7 +287,7 @@ { "name": "valid_from", "in": "query", - "description": "Valid from date time. Date-time for which datasets to be retrieved.", + "description": "Valid from: Filters datasets with a valid-from date later than the specified date-time.", "required": false, "schema": { "type": "string" @@ -296,7 +296,7 @@ { "name": "valid_to", "in": "query", - "description": "Valid to date time. Date-time for which datasets to be retrieved.", + "description": "Valid to: Filters datasets with a valid-to date earlier than the specified date-time.", "required": false, "schema": { "type": "string" @@ -305,7 +305,7 @@ { "name": "tdei_dataset_id", "in": "query", - "description": "tdei_dataset_id of the dataset to be retrieved.", + "description": "TDEI dataset ID: Filters datasets by the specified TDEI dataset ID.", "required": false, "schema": { "type": "string" @@ -314,7 +314,7 @@ { "name": "bbox", "in": "query", - "description": "A bounding box which specifies the area to be searched. A bounding box is specified by a string providing the lat/lon coordinates of the corners of the bounding box. Coordinate should be specified as west, south, east, north.", + "description": "Bounding box: Specifies the geographic area to search within, using a bounding box defined by four coordinates in the order: west, south, east, north. Accepts an array of four numeric values.", "required": false, "schema": { "maxItems": 4, @@ -335,7 +335,7 @@ { "name": "other_published_locations", "in": "query", - "description": "Other published locations", + "description": "Other published locations: Lists additional places where the dataset has been published. Supports contains match.", "required": false, "schema": { "type": "string" @@ -344,7 +344,7 @@ { "name": "dataset_update_frequency_months", "in": "query", - "description": "Dataset update frequency in months", + "description": "Dataset update frequency in months: Filters datasets based on how frequently they are updated. Uses a greater than or equal to match to include datasets updated at this frequency or more often.", "required": false, "schema": { "type": "integer" @@ -353,7 +353,7 @@ { "name": "schema_validation_run_description", "in": "query", - "description": "Schema validation run description", + "description": "Schema validation run description: Filters datasets based on the description of the schema validation run. Accepts a string value and uses contains match.", "required": false, "schema": { "type": "string" @@ -362,7 +362,7 @@ { "name": "full_dataset_name", "in": "query", - "description": "Full dataset name", + "description": "Full dataset name: Filters datasets based on their full name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -371,7 +371,7 @@ { "name": "collection_name", "in": "query", - "description": "Name of the collection", + "description": "Collection name: Filters datasets based on their collection name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -380,7 +380,7 @@ { "name": "department_name", "in": "query", - "description": "Name of the department", + "description": "Department name: Filters datasets based on their department name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -389,7 +389,7 @@ { "name": "city", "in": "query", - "description": "Name of the city", + "description": "Name of City: Filters datasets based on the city name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -398,7 +398,7 @@ { "name": "region", "in": "query", - "description": "Name of the region", + "description": "Region: Filters datasets based on the region name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -407,7 +407,7 @@ { "name": "county", "in": "query", - "description": "Name of the county", + "description": "County: Filters datasets based on the county name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -416,7 +416,7 @@ { "name": "key_limitations", "in": "query", - "description": "Key limitations of the dataset", + "description": "Key limitations: Filters datasets based on their key limitations. Supports contains match.", "required": false, "schema": { "type": "string" @@ -425,7 +425,7 @@ { "name": "release_notes", "in": "query", - "description": "Release notes", + "description": "Release notes: Filters datasets based on their release notes. Supports contains match.", "required": false, "schema": { "type": "string" @@ -434,7 +434,7 @@ { "name": "challenges", "in": "query", - "description": "Challenges faced in collecting the data", + "description": "Challenges: Filters datasets based on the challenges faced in collecting the data. Supports contains match.", "required": false, "schema": { "type": "string" @@ -443,7 +443,7 @@ { "name": "official_maintainer", "in": "query", - "description": "Official maintainer of the dataset", + "description": "Official maintainer: Filters datasets based on the official maintainer. Supports contains match.", "required": false, "schema": { "type": "array", @@ -455,7 +455,7 @@ { "name": "last_updated", "in": "query", - "description": "Date when the dataset was last updated", + "description": "Last updated: Filters datasets based on the last updated date. Accepts a date-time string match.", "required": false, "schema": { "type": "string" @@ -464,7 +464,7 @@ { "name": "update_frequency", "in": "query", - "description": "Frequency of updates", + "description": "Update frequency: Filters datasets based on their update frequency. Supports contains match.", "required": false, "schema": { "type": "string" @@ -473,7 +473,7 @@ { "name": "authorization_chain", "in": "query", - "description": "Authorization chain", + "description": "Authorization chain: Filters datasets based on their authorization chain. Supports contains match.", "required": false, "schema": { "type": "string" @@ -482,7 +482,7 @@ { "name": "maintenance_funded", "in": "query", - "description": "Is maintenance funded", + "description": "Maintenance funded: Filters datasets based on whether they are funded for maintenance. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -491,7 +491,7 @@ { "name": "funding_details", "in": "query", - "description": "Funding details", + "description": "Funding details: Filters datasets based on their funding details. Supports contains match.", "required": false, "schema": { "type": "string" @@ -500,7 +500,7 @@ { "name": "point_data_collection_device", "in": "query", - "description": "Point data collection device", + "description": "Point data collection device: Filters datasets based on the device used for point data collection. Supports contains match.", "required": false, "schema": { "type": "string" @@ -509,7 +509,7 @@ { "name": "node_locations_and_attributes_editing_software", "in": "query", - "description": "Node locations and attributes editing software", + "description": "Node locations and attributes editing software: Filters datasets based on the software used for editing node locations and attributes. Supports contains match.", "required": false, "schema": { "type": "string" @@ -518,7 +518,7 @@ { "name": "data_collected_by_people", "in": "query", - "description": "Is data collected by people", + "description": "Data collected by people: Filters datasets based on whether the data was collected by people. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -527,7 +527,7 @@ { "name": "data_collectors", "in": "query", - "description": "Data collectors", + "description": "Data collectors: Filters datasets based on the individuals or organizations that collected the data. Supports contains match.", "required": false, "schema": { "type": "string" @@ -536,7 +536,7 @@ { "name": "data_captured_automatically", "in": "query", - "description": "Is data captured automatically", + "description": "Data captured automatically: Filters datasets based on whether the data was captured automatically. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -545,7 +545,7 @@ { "name": "automated_collection", "in": "query", - "description": "Automated collection", + "description": "Automated collection: Filters datasets based on whether the data was collected automatically. Supports contains match.", "required": false, "schema": { "type": "string" @@ -554,7 +554,7 @@ { "name": "data_collectors_organization", "in": "query", - "description": "Data collectors organization", + "description": "Data collectors organization: Filters datasets based on the organization of the data collectors. Supports contains match.", "required": false, "schema": { "type": "string" @@ -563,7 +563,7 @@ { "name": "data_collector_compensation", "in": "query", - "description": "Data collector compensation", + "description": "Data collector compensation: Filters datasets based on whether the data collectors were compensated. Supports contains match.", "required": false, "schema": { "type": "string" @@ -572,7 +572,7 @@ { "name": "preprocessing_location", "in": "query", - "description": "Preprocessing location", + "description": "Preprocessing location: Filters datasets based on their preprocessing location. Supports contains match.", "required": false, "schema": { "type": "string" @@ -581,7 +581,7 @@ { "name": "preprocessing_by", "in": "query", - "description": "Preprocessing by", + "description": "Preprocessing by: Filters datasets based on who performed the preprocessing. Supports contains match.", "required": false, "schema": { "type": "string" @@ -590,7 +590,7 @@ { "name": "preprocessing_steps", "in": "query", - "description": "Preprocessing steps", + "description": "Preprocessing steps: Filters datasets based on their preprocessing steps. Supports contains match.", "required": false, "schema": { "type": "string" @@ -599,7 +599,7 @@ { "name": "data_collection_preprocessing_documentation", "in": "query", - "description": "Is data collection preprocessing documentation available", + "description": "Data collection preprocessing documentation: Filters datasets based on the availability of data collection preprocessing documentation. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -608,7 +608,7 @@ { "name": "documentation_uri", "in": "query", - "description": "Documentation URI", + "description": "Documentation URI: Filters datasets based on their documentation URI. Supports contains match.", "required": false, "schema": { "type": "string" @@ -617,7 +617,7 @@ { "name": "validation_process_exists", "in": "query", - "description": "Is validation process exists", + "description": "Validation process exists: Filters datasets based on whether a validation process exists. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -626,7 +626,7 @@ { "name": "validation_process_description", "in": "query", - "description": "Validation process description", + "description": "Validation process description: Filters datasets based on the description of the validation process. Supports contains match.", "required": false, "schema": { "type": "string" @@ -635,7 +635,7 @@ { "name": "validation_conducted_by", "in": "query", - "description": "Validation conducted by", + "description": "Validation conducted by: Filters datasets based on who conducted the validation. Supports contains match.", "required": false, "schema": { "type": "string" @@ -644,7 +644,7 @@ { "name": "excluded_data", "in": "query", - "description": "Excluded data", + "description": "Excluded data: Filters datasets based on whether they contain excluded data. Supports contains match.", "required": false, "schema": { "type": "string" @@ -653,16 +653,25 @@ { "name": "excluded_data_reason", "in": "query", - "description": "Excluded data reason", + "description": "Excluded data reason: Filters datasets based on the reason for excluding data. Supports contains match.", "required": false, "schema": { "type": "string" } }, + { + "name": "data_viewer_allowed", + "in": "query", + "description": "Data viewer allowed: Filters datasets based on whether data viewer access is allowed. Uses a boolean value.", + "required": false, + "schema": { + "type": "boolean" + } + }, { "name": "page_no", "in": "query", - "description": "Integer, defaults to 1. Retrieves the results in pages.", + "description": "page_no: Integer, defaults to 1. Filters datasets by retrieving results in pages.", "required": false, "schema": { "type": "integer", @@ -673,7 +682,7 @@ { "name": "page_size", "in": "query", - "description": "Page size. integer, between 1 to 50, defaults to 10.Specifies total records per page.", + "description": "Page size: Integer, between 1 to 50, defaults to 10.Specifies total records per page.", "required": false, "schema": { "type": "integer", @@ -684,7 +693,7 @@ { "name": "sort_field", "in": "query", - "description": "Sort field. By default, it is by uploaded timestamp.", + "description": "Sort field: The field by which to sort the results. By default, it is by uploaded timestamp. Matches the exact value from the supported enumeration.", "required": false, "schema": { "type": "string", @@ -701,7 +710,7 @@ { "name": "sort_order", "in": "query", - "description": "Sort order. By default, it is in descending order.", + "description": "Sort order: By default, it is in descending order.", "required": false, "schema": { "type": "string", @@ -2227,107 +2236,67 @@ ] } }, - "/api/v1/gtfs-flex/upload/{tdei_project_group_id}/{tdei_service_id}": { + "/api/v1/osw/dataset-viewer/{tdei_dataset_id}": { "post": { "tags": [ - "GTFS Flex" + "OSW" ], - "summary": "Upload a GTFS Flex dataset.", - "description": "This endpoint enables users to upload a GTFS-Flex dataset. The request must include the required parameters to complete the upload. The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint. By default, the dataset's status will be set to 'pre-release.' The dataset can be published using the /publish endpoint.", - "operationId": "uploadGtfsFlexFile", + "summary": "Updates the visibility preferences for the dataset viewer.", + "description": "Updates the visibility preferences for a specified dataset identified by the tdei_dataset_id. It takes the dataset ID as a parameter and modifies the dataset's visibility settings.", + "operationId": "oswDatasetViewer", "parameters": [ { - "name": "tdei_project_group_id", - "in": "path", - "description": "Project group id to which the dataset would be uploaded", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "tdei_service_id", + "name": "tdei_dataset_id", "in": "path", - "description": "TDEI service id associated with the above project group id.", + "description": "Dataset ID for updating the dataset viewer preferences.", "required": true, "schema": { "type": "string" } - }, - { - "name": "derived_from_dataset_id", - "in": "query", - "description": "Dataset id from which this dataset was derived.", - "required": false, - "schema": { - "type": "string" - } } ], "requestBody": { "content": { - "multipart/form-data": { + "application/json": { "schema": { - "required": [ - "dataset", - "metadata" - ], "type": "object", "properties": { - "dataset": { - "type": "string", - "format": "binary", - "description": "GTFS Flex file which is expected to be a zip file. It typically includes .txt files that define details such as service areas and stops for flexible transit routes." - }, - "metadata": { - "type": "string", - "format": "binary", - "description": "Metadata information for the GTFS-Flex dataset. This is a JSON file that includes details on how and when the data was collected, the file's valid dates, and other relevant information about the dataset. For more details, refer to the [metadata schema](https://raw.githubusercontent.com/TaskarCenterAtUW/TDEI-osw-datasvc-ts/stage/schema/metadata.schema.json)." - }, - "changeset": { - "type": "string", - "format": "binary", - "description": "The changeset file records modifications to the sidewalk network included in the GTFS-Flex dataset. It supports file formats with either .zip or .osc extensions." + "allow_viewer_access": { + "type": "boolean", + "default": true, + "description": "Indicates whether the dataset viewer access is allowed." } - } + }, + "required": [ + "allow_viewer_access" + ] } } }, "required": true }, "responses": { - "202": { - "description": "The upload request has been accepted for processing. It returns a `job_id`, a unique identifier for the uploaded request, which can be used to track the status of the upload. The endpoint to check the status is provided in the `location` header of the response.", + "200": { + "description": "Visibility preferences for the dataset viewer updated successfully.", "content": { "application/text": { "schema": { "type": "string" } } - }, - "headers": { - "Location": { - "schema": { - "type": "string" - }, - "description": "Location api to find the status of request processing" - } } }, - "400": { - "description": "The request's input parameters are invalid." - }, "401": { "description": "Unauthenticated request. Check your access token." }, "403": { - "description": "User unauthorized to upload the dataset." + "description": "Forbidden request. Dataset viewer access is not allowed at project group level." }, "404": { - "description": "derived_from_dataset_id, tdei_project_group_id or tdei_service_id doesn't exist in the system" + "description": "tdei_dataset_id doesn't exist in the system." }, "500": { - "description": "An Internal server error occured" + "description": "An server error occurred." } }, "security": [ @@ -2337,19 +2306,19 @@ ] } }, - "/api/v1/gtfs-flex/publish/{tdei_dataset_id}": { - "post": { + "/api/v1/osw/dataset-viewer/pm-tiles/{tdei_dataset_id}": { + "get": { "tags": [ - "GTFS Flex" + "OSW" ], - "summary": "Publishes the GTFS Flex dataset for the tdei_dataset_id", - "description": "Publishes a GTFS Flex dataset that was previously uploaded via the [POST] /gtfs-flex endpoint, marking it as an official release for the mobility service. This official release status ensures visibility to all TDEI data consumers. The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint.", - "operationId": "publishGtfsFlexFile", + "summary": "Retrives the PM tiles SAS url for the dataset.", + "description": "Retrieves the PM tiles SAS url for a specified dataset identified by the tdei_dataset_id.", + "operationId": "oswDatasetViewerPMTiles", "parameters": [ { "name": "tdei_dataset_id", "in": "path", - "description": "Dataset id of the dataset to be published", + "description": "Dataset ID for retrieving the PM tiles SAS url.", "required": true, "schema": { "type": "string" @@ -2357,111 +2326,135 @@ } ], "responses": { - "202": { - "description": "The publish request has been accepted for processing. It returns a `job_id`, a unique identifier for the published request, which can be used to track the status of the request. The endpoint to check the status is provided in the location header of the response.", + "200": { + "description": "PM tiles SAS url retrieved successfully.", "content": { "application/text": { "schema": { "type": "string" } } - }, - "headers": { - "Location": { - "schema": { - "type": "string" - }, - "description": "Location api to find the status of request processing" - } } }, - "400": { - "description": "The request fails to match the publish criteria." - }, "401": { "description": "Unauthenticated request. Check your access token." }, "403": { - "description": "User unauthorized to publish the dataset." + "description": "Forbidden request. Dataset viewer access is not allowed at dataset or project group level." }, "404": { - "description": "Dataset with the specified tdei_dataset_id was not found. Use the [GET] /api/v1/gtfs-flex endpoint to find valid dataset ids.", - "content": { - "text/plain": {} - } + "description": "tdei_dataset_id doesn't exist in the system." }, "500": { - "description": "An Internal server error occured" + "description": "An server error occurred." } }, "security": [ - { - "ApiKey": [] - }, { "AuthorizationToken": [] } ] } }, - "/api/v1/gtfs-flex/validate": { + "/api/v1/osw/dataset-viewer/feedbacks/{project_id}/{tdei_dataset_id}": { "post": { "tags": [ - "GTFS Flex" + "OSW" + ], + "summary": "Accepts the feedback from the dataset viewer.", + "description": "Accepts the feedback from the dataset viewer. The feedback is stored in the system for further analysis and improvement of the dataset.", + "operationId": "oswDatasetViewerFeedback", + "parameters": [ + { + "name": "project_id", + "in": "path", + "required": true, + "description": "ID of the project group.", + "schema": { + "type": "string" + } + }, + { + "name": "tdei_dataset_id", + "in": "path", + "required": true, + "description": "ID of the dataset.", + "schema": { + "type": "string" + } + } ], - "summary": "Validates the GTFS Flex dataset.", - "description": "Allows a user to validate GTFS Flex dataset to check the correctness of data. The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint.", - "operationId": "validateGtfsFlexFile", "requestBody": { "content": { - "multipart/form-data": { + "application/json": { "schema": { - "required": [ - "dataset" - ], "type": "object", "properties": { - "dataset": { + "dataset_element_id": { "type": "string", - "format": "binary", - "description": "GTFS Flex file which is expected to be a zip file. It typically includes .txt files that define details such as service areas and stops for flexible transit routes." + "description": "Dataset ID for which the feedback is provided.", + "example": "14325" + }, + "feedback_text": { + "type": "string", + "description": "Feedback provided by the user regarding the dataset viewer.", + "example": "The dataset viewer is very informative and easy to use." + }, + "customer_email": { + "type": "string", + "format": "email", + "description": "Email address of the user providing feedback. This is optional and can be used for follow-up if needed.", + "example": "user@example.com" + }, + "location_latitude": { + "type": "number", + "format": "double", + "description": "Latitude of the location where the feedback was provided." + }, + "location_longitude": { + "type": "number", + "format": "double", + "description": "Longitude of the location where the feedback was provided." } - } + }, + "required": [ + "feedback_text", + "location", + "customer_email" + ] } } }, "required": true }, "responses": { - "202": { - "description": "The validate request has been accepted for processing. It returns a `job_id`, a unique identifier for the validate request, which can be used to track the status of the validate request. The endpoint to check the status is provided in the location header of the response.", + "200": { + "description": "Feedback submitted successfully.", "content": { - "application/text": { + "application/json": { "schema": { - "type": "string" + "type": "object", + "properties": { + "message": { + "type": "string", + "example": "Feedback submitted successfully." + } + } } } - }, - "headers": { - "Location": { - "schema": { - "type": "string" - }, - "description": "Location api to find the status of request processing" - } } }, "400": { - "description": "Dataset input file not found." - }, - "401": { - "description": "Unauthenticated request. Check your access token." + "description": "Invalid input parameters." }, "403": { - "description": "User unauthorized to validate the dataset." + "description": "CORS error. The request is not allowed from the current origin." + }, + "404": { + "description": "Project group or dataset not found." }, "500": { - "description": "An Internal server error occured" + "description": "An server error occurred." } }, "security": [ @@ -2471,61 +2464,656 @@ ] } }, - "/api/v1/gtfs-flex/{tdei_dataset_id}": { + "/api/v1/osw/dataset-viewer/feedbacks": { "get": { "tags": [ - "GTFS Flex" + "OSW" ], - "summary": "Downloads the GTFS Flex dataset", - "description": "Downloads a specific GTFS Flex dataset as zip containing .txt files that define details such as service areas and stops for flexible transit routes.", - "operationId": "getGtfsFlexFile", + "summary": "Retrieves the dataset viewer feedbacks.", + "description": "Retrieves the dataset viewer feedbacks. Response includes a list of feedbacks provided by users regarding the dataset. Each feedback contains details such as the dataset element ID, feedback text, customer email, and location information.", + "operationId": "oswDatasetViewerFeedbacks", "parameters": [ { - "name": "tdei_dataset_id", - "in": "path", - "description": "Dataset id of the dataset to be downloaded.", - "required": true, + "name": "tdei_project_group_id", + "in": "query", + "required": false, + "description": "ID of the project group.", "schema": { "type": "string" } - } - ], - "responses": { - "200": { - "description": "Streams the dataset zip file.", - "content": { - "application/octet-stream": {} + }, + { + "name": "tdei_dataset_id", + "in": "query", + "required": false, + "description": "ID of the dataset.", + "schema": { + "type": "string" } }, - "400": { - "description": "tdei_dataset_id is not of type GTFS-Flex." + { + "name": "from_date", + "in": "query", + "description": "from_date: Date in ISO 8601 format, filters feedbacks created after this date.", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } }, - "401": { - "description": "Unauthenticated request. Check your access token." + { + "name": "to_date", + "in": "query", + "description": "to_date: Date in ISO 8601 format, filters feedbacks created before this date.", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } }, - "404": { - "description": "A file with the specified tdei_dataset_id was not found. Use the /api/v1/gtfs-flex endpoints to find valid file ids.", - "content": { - "application/json": {} + { + "name": "status", + "in": "query", + "required": false, + "description": "status: Filters feedbacks by their status.", + "schema": { + "type": "string", + "enum": [ + "open", + "resolved" + ] } }, - "500": { - "description": "An Internal server error occured" - } - }, - "security": [ { - "ApiKey": [] + "name": "sort_by", + "in": "query", + "description": "sort_by: String, defaults to 'created_at'. Sorts feedbacks by the specified field.", + "required": false, + "schema": { + "type": "string", + "default": "created_at", + "enum": [ + "created_at", + "due_date" + ] + } }, { - "AuthorizationToken": [] - } - ] - } - }, - "/api/v1/gtfs-flex/versions": { - "get": { - "tags": [ + "name": "sort_order", + "in": "query", + "description": "sort_order: String, defaults to 'desc'. Sorts feedbacks in ascending or descending order.", + "required": false, + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + } + }, + { + "name": "page_no", + "in": "query", + "description": "page_no: Integer, defaults to 1. Specifies the page number to retrieve.", + "required": false, + "schema": { + "type": "integer", + "format": "int32", + "default": 1 + } + }, + { + "name": "page_size", + "in": "query", + "description": "Page size: Integer, between 1 to 50, defaults to 10. Specifies total records per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "responses": { + "200": { + "description": "Feedbacks retrieved successfully.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Feedback" + } + } + } + } + }, + "500": { + "description": "An server error occurred." + } + }, + "security": [ + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/osw/dataset-viewer/feedbacks/download/{tdei_project_group_id}":{ + "get":{ + "tags":[ + "OSW" + ], + "summary":"Downloads dataset viewer feedbacks as a CSV.", + "description":"Streams all feedback for the specified project group in CSV format. Requires poc or osw_data_generator role.", + "operationId":"oswDatasetViewerFeedbacksDownload", + "parameters":[ + { + "name": "tdei_project_group_id", + "in": "path", + "description": "Valid TDEI project group id.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name":"tdei_dataset_id", + "in":"query", + "required":false, + "description":"ID of the dataset.", + "schema":{ + "type":"string" + } + }, + { + "name":"from_date", + "in":"query", + "description":"from_date: Date in ISO 8601 format, filters feedback created after this date.", + "required":false, + "schema":{ + "type":"string", + "format":"date-time" + } + }, + { + "name":"to_date", + "in":"query", + "description":"to_date: Date in ISO 8601 format, filters feedback created before this date.", + "required":false, + "schema":{ + "type":"string", + "format":"date-time" + } + }, + { + "name":"status", + "in":"query", + "required":false, + "description":"status: Filters feedbacks by their status.", + "schema":{ + "type":"string", + "enum":[ + "open", + "resolved" + ] + } + }, + { + "name":"sort_by", + "in":"query", + "description":"sort_by: String, defaults to 'created_at'. Sorts feedbacks by the specified field.", + "required":false, + "schema":{ + "type":"string", + "default":"created_at", + "enum":[ + "created_at", + "due_date" + ] + } + }, + { + "name":"due_date", + "in":"query", + "description":"due_date: Legacy alias for sort_by. Use 'created_at' or 'due_date'.", + "required":false, + "schema":{ + "type":"string", + "enum":[ + "created_at", + "due_date" + ] + } + }, + { + "name":"sort_order", + "in":"query", + "description":"sort_order: String, defaults to 'desc'. Sorts feedbacks in ascending or descending order.", + "required":false, + "schema":{ + "type":"string", + "default":"desc", + "enum":[ + "asc", + "desc" + ] + } + }, + { + "name":"page_no", + "in":"query", + "description":"page_no: Integer, specifies the page number to retrieve. If omitted with page_size, the response is unpaginated.", + "required":false, + "schema":{ + "type":"integer", + "format":"int32" + } + }, + { + "name":"page_size", + "in":"query", + "description":"Page size: Integer, between 1 to 50. If omitted with page_no, the response is unpaginated.", + "required":false, + "schema":{ + "type":"integer", + "format":"int32" + } + }, + { + "name":"format", + "in":"query", + "required":false, + "description":"format: Output format.", + "schema":{ + "type":"string", + "default":"csv", + "enum":[ + "csv", + "geojson" + ] + } + } + ], + "responses":{ + "200": { + "description": "Feedback file streamed successfully.", + "content": { + "text/csv": { + "schema": { "type": "string", "format": "binary" } + }, + "application/geo+json": { + "schema": { + "type": "object", + "required": ["type", "features"], + "properties": { + "type": { "enum": ["FeatureCollection"] }, + "features": { + "type": "array", + "items": { "$ref": "#/components/schemas/Feature" } + } + } + } + } + } + }, + "400":{ + "description":"Invalid request parameters." + }, + "500":{ + "description":"A server error occurred." + } + }, + "security":[ + { + "AuthorizationToken":[ + + ] + } + ] + } + }, + "/api/v1/osw/dataset-viewer/feedbacks/metadata": { + "get": { + "tags": [ + "OSW" + ], + "summary": "Retrieves the feedbacks summary.", + "description": "Retrieves the feedbacks summary. Response includes a summary of feedbacks such as total count, total overdue, and other relevant statistics.", + "operationId": "oswDatasetViewerFeedbacksMetadata", + "parameters": [ + { + "name": "tdei_project_group_id", + "in": "query", + "required": false, + "description": "ID of the project group.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Feedbacks summary retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeedbackMetadata" + } + } + } + }, + "500": { + "description": "An server error occurred." + } + }, + "security": [ + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/gtfs-flex/upload/{tdei_project_group_id}/{tdei_service_id}": { + "post": { + "tags": [ + "GTFS Flex" + ], + "summary": "Upload a GTFS Flex dataset.", + "description": "This endpoint enables users to upload a GTFS-Flex dataset. The request must include the required parameters to complete the upload. The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint. By default, the dataset's status will be set to 'pre-release.' The dataset can be published using the /publish endpoint.", + "operationId": "uploadGtfsFlexFile", + "parameters": [ + { + "name": "tdei_project_group_id", + "in": "path", + "description": "Project group id to which the dataset would be uploaded", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "tdei_service_id", + "in": "path", + "description": "TDEI service id associated with the above project group id.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "derived_from_dataset_id", + "in": "query", + "description": "Dataset id from which this dataset was derived.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "required": [ + "dataset", + "metadata" + ], + "type": "object", + "properties": { + "dataset": { + "type": "string", + "format": "binary", + "description": "GTFS Flex file which is expected to be a zip file. It typically includes .txt files that define details such as service areas and stops for flexible transit routes." + }, + "metadata": { + "type": "string", + "format": "binary", + "description": "Metadata information for the GTFS-Flex dataset. This is a JSON file that includes details on how and when the data was collected, the file's valid dates, and other relevant information about the dataset. For more details, refer to the [metadata schema](https://raw.githubusercontent.com/TaskarCenterAtUW/TDEI-osw-datasvc-ts/stage/schema/metadata.schema.json)." + }, + "changeset": { + "type": "string", + "format": "binary", + "description": "The changeset file records modifications to the sidewalk network included in the GTFS-Flex dataset. It supports file formats with either .zip or .osc extensions." + } + } + } + } + }, + "required": true + }, + "responses": { + "202": { + "description": "The upload request has been accepted for processing. It returns a `job_id`, a unique identifier for the uploaded request, which can be used to track the status of the upload. The endpoint to check the status is provided in the `location` header of the response.", + "content": { + "application/text": { + "schema": { + "type": "string" + } + } + }, + "headers": { + "Location": { + "schema": { + "type": "string" + }, + "description": "Location api to find the status of request processing" + } + } + }, + "400": { + "description": "The request's input parameters are invalid." + }, + "401": { + "description": "Unauthenticated request. Check your access token." + }, + "403": { + "description": "User unauthorized to upload the dataset." + }, + "404": { + "description": "derived_from_dataset_id, tdei_project_group_id or tdei_service_id doesn't exist in the system" + }, + "500": { + "description": "An Internal server error occured" + } + }, + "security": [ + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/gtfs-flex/publish/{tdei_dataset_id}": { + "post": { + "tags": [ + "GTFS Flex" + ], + "summary": "Publishes the GTFS Flex dataset for the tdei_dataset_id", + "description": "Publishes a GTFS Flex dataset that was previously uploaded via the [POST] /gtfs-flex endpoint, marking it as an official release for the mobility service. This official release status ensures visibility to all TDEI data consumers. The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint.", + "operationId": "publishGtfsFlexFile", + "parameters": [ + { + "name": "tdei_dataset_id", + "in": "path", + "description": "Dataset id of the dataset to be published", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "202": { + "description": "The publish request has been accepted for processing. It returns a `job_id`, a unique identifier for the published request, which can be used to track the status of the request. The endpoint to check the status is provided in the location header of the response.", + "content": { + "application/text": { + "schema": { + "type": "string" + } + } + }, + "headers": { + "Location": { + "schema": { + "type": "string" + }, + "description": "Location api to find the status of request processing" + } + } + }, + "400": { + "description": "The request fails to match the publish criteria." + }, + "401": { + "description": "Unauthenticated request. Check your access token." + }, + "403": { + "description": "User unauthorized to publish the dataset." + }, + "404": { + "description": "Dataset with the specified tdei_dataset_id was not found. Use the [GET] /api/v1/gtfs-flex endpoint to find valid dataset ids.", + "content": { + "text/plain": {} + } + }, + "500": { + "description": "An Internal server error occured" + } + }, + "security": [ + { + "ApiKey": [] + }, + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/gtfs-flex/validate": { + "post": { + "tags": [ + "GTFS Flex" + ], + "summary": "Validates the GTFS Flex dataset.", + "description": "Allows a user to validate GTFS Flex dataset to check the correctness of data. The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint.", + "operationId": "validateGtfsFlexFile", + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "required": [ + "dataset" + ], + "type": "object", + "properties": { + "dataset": { + "type": "string", + "format": "binary", + "description": "GTFS Flex file which is expected to be a zip file. It typically includes .txt files that define details such as service areas and stops for flexible transit routes." + } + } + } + } + }, + "required": true + }, + "responses": { + "202": { + "description": "The validate request has been accepted for processing. It returns a `job_id`, a unique identifier for the validate request, which can be used to track the status of the validate request. The endpoint to check the status is provided in the location header of the response.", + "content": { + "application/text": { + "schema": { + "type": "string" + } + } + }, + "headers": { + "Location": { + "schema": { + "type": "string" + }, + "description": "Location api to find the status of request processing" + } + } + }, + "400": { + "description": "Dataset input file not found." + }, + "401": { + "description": "Unauthenticated request. Check your access token." + }, + "403": { + "description": "User unauthorized to validate the dataset." + }, + "500": { + "description": "An Internal server error occured" + } + }, + "security": [ + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/gtfs-flex/{tdei_dataset_id}": { + "get": { + "tags": [ + "GTFS Flex" + ], + "summary": "Downloads the GTFS Flex dataset", + "description": "Downloads a specific GTFS Flex dataset as zip containing .txt files that define details such as service areas and stops for flexible transit routes.", + "operationId": "getGtfsFlexFile", + "parameters": [ + { + "name": "tdei_dataset_id", + "in": "path", + "description": "Dataset id of the dataset to be downloaded.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Streams the dataset zip file.", + "content": { + "application/octet-stream": {} + } + }, + "400": { + "description": "tdei_dataset_id is not of type GTFS-Flex." + }, + "401": { + "description": "Unauthenticated request. Check your access token." + }, + "404": { + "description": "A file with the specified tdei_dataset_id was not found. Use the /api/v1/gtfs-flex endpoints to find valid file ids.", + "content": { + "application/json": {} + } + }, + "500": { + "description": "An Internal server error occured" + } + }, + "security": [ + { + "ApiKey": [] + }, + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/gtfs-flex/versions": { + "get": { + "tags": [ "GTFS Flex" ], "summary": "List available GTFS Flex versions", @@ -3678,6 +4266,11 @@ "tdei_project_group_id": { "type": "string", "example": "4e991e7a-5c16-4ebf-ad31-3a3625bcca10" + }, + "dataset_viewer_allowed": { + "type": "boolean", + "default": false, + "description": "Flag to indicate to allow dataset to be viewed on the dataset viewer." } }, "required": [ @@ -3803,16 +4396,171 @@ ], "type": "object", "properties": { - "polygon": { - "$ref": "#/components/schemas/GeoJsonObject" - }, "tdei_project_group_id": { "type": "string", - "description": "Unique id that represents the project group." + "description": "ProjectGroupId uniquely represented in the TDEI system. System generated.", + "default": "0" }, - "project_group_name": { + "name": { "type": "string", "description": "Name of the project group." + }, + "phone": { + "type": "string", + "description": "Phone of the project group for communication." + }, + "url": { + "type": "string", + "description": "Url of the transit project group." + }, + "address": { + "type": "string", + "description": "Address of the transit project group." + }, + "polygon": { + "$ref": "#/components/schemas/Polygon" + }, + "poc": { + "type": "array", + "description": "Project group POC details", + "items": { + "$ref": "#/components/schemas/POC", + "description": "POC details" + } + }, + "data_viewer": { + "type": "object", + "properties": { + "dataset_viewer_allowed": { + "type": "boolean", + "default": false, + "description": "Flag to indicate to allow all datasets within the project group to be viewed on the dataset viewer." + }, + "feedback_turnaround_time": { + "type": "object", + "description": "Feedback turnaround time for the project group.", + "properties": { + "number": { + "type": "integer", + "description": "Number of days for feedback turnaround time." + }, + "unit": { + "type": "string", + "enum": [ + "days", + "months", + "years" + ], + "description": "Unit of time for feedback turnaround time." + } + } + } + }, + "description": "Describes an Project group." + } + } + }, + "POC": { + "type": "object", + "properties": { + "first_name": { + "type": "string" + }, + "last_name": { + "type": "string" + }, + "username": { + "type": "string" + }, + "email": { + "type": "string" + } + }, + "required": [ + "first_name", + "last_name", + "username", + "email" + ] + }, + "Polygon": { + "title": "GeoJSON FeatureCollection", + "type": "object", + "required": [ + "type", + "features" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "FeatureCollection" + ] + }, + "features": { + "type": "array", + "items": { + "title": "GeoJSON Feature", + "type": "object", + "required": [ + "type", + "properties", + "geometry" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "Feature" + ] + }, + "id": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ] + }, + "properties": { + "type": "object" + }, + "geometry": { + "title": "GeoJSON Polygon", + "type": "object", + "required": [ + "type", + "coordinates" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "Polygon" + ] + }, + "coordinates": { + "type": "array", + "items": { + "type": "array", + "minItems": 4, + "items": { + "type": "array", + "minItems": 2, + "maxItems": 2, + "items": { + "type": "number", + "format": "double" + } + } + } + } + } + } + } + } } } }, @@ -4201,6 +4949,115 @@ "dataMetrics", "datasetMetrics" ] + }, + "Feedback": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the feedback.", + "example": "10432" + }, + "project_group": { + "type": "object", + "properties": { + "tdei_project_group_id": { + "type": "string", + "description": "ID of the project group.", + "example": "4e991e7a-5c16-4ebf-ad31-3a3625bcca10" + }, + "name": { + "type": "string", + "description": "Name of the project group." + } + }, + "required": [ + "tdei_project_group_id", + "name" + ] + }, + "dataset": { + "type": "object", + "properties": { + "tdei_dataset_id": { + "type": "string", + "description": "ID of the dataset.", + "example": "4e991e7a-5c16-4ebf-ad31-3a3625bcca10" + }, + "name": { + "type": "string", + "description": "Name of the dataset." + } + }, + "required": [ + "tdei_dataset_id", + "name" + ] + }, + "feedback_text": { + "type": "string", + "description": "Feedback text provided by the user." + }, + "dataset_element_id": { + "type": "string", + "description": "ID of the specific dataset element related to the feedback.", + "example": "10432" + }, + "status": { + "type": "string", + "description": "Status of the feedback.", + "enum": [ + "open", + "resolved" + ] + }, + "location_latitude": { + "type": "number", + "description": "Latitude of the location related to the feedback.", + "example": 37.7749 + }, + "location_longitude": { + "type": "number", + "description": "Longitude of the location related to the feedback.", + "example": -122.4194 + }, + "due_date": { + "type": "string", + "format": "date-time", + "description": "Due date for the feedback response." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the feedback was created." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the feedback was last updated." + } + } + }, + "FeedbackMetadata": { + "type": "object", + "description": "Additional metadata related to the feedback.", + "properties": { + "total_count": { + "type": "number", + "description": "Count of feedback entries.", + "example": 5 + }, + "total_overdues": { + "type": "number", + "description": "Indicates number of overdue feedbacks.", + "example": 0 + }, + "total_open": { + "type": "number", + "description": "Indicates number of open feedbacks.", + "example": 3 + } + } } }, "securitySchemes": { diff --git a/tdei-api-gateway.json b/tdei-api-gateway.json index d7a5f2b..d55f118 100644 --- a/tdei-api-gateway.json +++ b/tdei-api-gateway.json @@ -143,13 +143,13 @@ "Common APIs" ], "summary": "Lists the TDEI datasets in the system.", - "description": "This API lists all TDEI datasets, allowing users to efficiently search with sorting and filtering features. Each dataset entry is uniquely identified by `tdei_dataset_id` and also provide detailed information including metadata, associated project group, service details, download URL, and status. Users can sort datasets by 'valid_to', 'valid_from', 'uploaded date', 'project group name', and 'status'. Filtering options are provided for enhanced discoverability of the datasets.By default all released datasets are visible to all user. Pre-release datasets are only visible to user affiliated with the project groups.", + "description": "

This API returns filtered and sorted lists of TDEI datasets. The matching behavior of filter parameters may vary depending on the attribute type.

By default results will include all datasets in released status AND all dataset in pre-release status within the requesting user's project group. This behavior can be controlled by the status parameter. In no situation can a user see pre-release datasets from a project group the user is not part of.

\n\n Primary use cases include: \n\n Sorting:

Users can sort datasets by 'valid_to', 'valid_from', 'uploaded date', 'project group name', and 'status'.

", "operationId": "listDatasetFiles", "parameters": [ { "name": "data_type", "in": "query", - "description": "Type of the dataset.", + "description": "Type of the dataset. Filters datasets by matching the exact value from the supported enumeration.", "required": false, "schema": { "type": "string", @@ -163,7 +163,7 @@ { "name": "status", "in": "query", - "description": "This filter allows users to request datasets based on their status. When set to 'All', the filter displays all available datasets by default. If specified as 'Pre-Release' or 'Publish', it shows only the datasets that are in the Pre-Release or Publish stages, respectively, for the project groups the user is affiliated with.", + "description": "

Status of the dataset: Filters datasets by status — All (default) returns released datasets and pre-release datasets from the user's project groups; Pre-Release and Publish return only datasets in that status from affiliated project groups.

", "required": false, "schema": { "type": "string", @@ -178,7 +178,7 @@ { "name": "name", "in": "query", - "description": "Dataset name or title", + "description": "

Dataset name or title: Filters datasets where the name or title contains the specified search text.

", "required": false, "schema": { "type": "string" @@ -187,7 +187,7 @@ { "name": "version", "in": "query", - "description": "Dataset version.", + "description": "

Dataset version: Filters datasets using an exact match on the version value.

", "required": false, "schema": { "type": "string" @@ -196,7 +196,7 @@ { "name": "data_source", "in": "query", - "description": "Data source of the dataset.", + "description": "

Data source: Filters datasets by matching the exact value from the supported enumeration.

", "required": false, "schema": { "type": "string", @@ -210,7 +210,7 @@ { "name": "collection_method", "in": "query", - "description": "Method by which the data was collected.", + "description": "

Collection method: Filters datasets by matching the exact value from the supported enumeration.

", "required": false, "schema": { "type": "string", @@ -225,7 +225,7 @@ { "name": "collected_by", "in": "query", - "description": "Collection agency or person.", + "description": "

Collected by: Filters datasets using an exact match on the collection agency or person's name.

", "required": false, "schema": { "type": "string" @@ -234,7 +234,7 @@ { "name": "derived_from_dataset_id", "in": "query", - "description": "Dataset id from which this dataset was derived.", + "description": "derived_from_dataset_id: Filters datasets that are derived from the specified dataset ID. Exact match.", "required": false, "schema": { "type": "string" @@ -243,7 +243,7 @@ { "name": "collection_date", "in": "query", - "description": "Collection date time", + "description": "collection_date: Filters datasets collected after the specified date and time.", "required": false, "schema": { "type": "string" @@ -251,7 +251,7 @@ }, { "name": "confidence_level", - "description": "Minimum confidence level required. Data returned will be at this confidence level or higher. Confidence level range is: 0 (very low confidence) to 100 (very high confidence).", + "description": "Confidence level: Minimum confidence level required. Returns datasets with confidence level greater than the specified value. Range: 0 (very low) to 100 (very high).", "schema": { "type": "integer" }, @@ -260,7 +260,7 @@ { "name": "schema_version", "in": "query", - "description": "Version name of the data type schema version that the application requests. list of versions can be found with /api/v1/{data_type}/versions.", + "description": "Schema version: Filters datasets that match the requested data type schema version. The list of supported versions can be found at /api/v1/{data_type}/versions.", "required": false, "schema": { "type": "string" @@ -269,7 +269,7 @@ { "name": "tdei_project_group_id", "in": "query", - "description": "TDEI project group id of the datasets to be retrieved.", + "description": "TDEI project group ID: Filters datasets that belong to the specified project group. Exact match.", "required": false, "schema": { "type": "string" @@ -278,7 +278,7 @@ { "name": "tdei_service_id", "in": "query", - "description": "TDEI service id of the datasets to be retrieved.", + "description": "TDEI service ID: Filters datasets that belong to the specified TDEI service. Exact match.", "required": false, "schema": { "type": "string" @@ -287,7 +287,7 @@ { "name": "valid_from", "in": "query", - "description": "Valid from date time. Date-time for which datasets to be retrieved.", + "description": "Valid from: Filters datasets with a valid-from date later than the specified date-time.", "required": false, "schema": { "type": "string" @@ -296,7 +296,7 @@ { "name": "valid_to", "in": "query", - "description": "Valid to date time. Date-time for which datasets to be retrieved.", + "description": "Valid to: Filters datasets with a valid-to date earlier than the specified date-time.", "required": false, "schema": { "type": "string" @@ -305,7 +305,7 @@ { "name": "tdei_dataset_id", "in": "query", - "description": "tdei_dataset_id of the dataset to be retrieved.", + "description": "TDEI dataset ID: Filters datasets by the specified TDEI dataset ID.", "required": false, "schema": { "type": "string" @@ -314,7 +314,7 @@ { "name": "bbox", "in": "query", - "description": "A bounding box which specifies the area to be searched. A bounding box is specified by a string providing the lat/lon coordinates of the corners of the bounding box. Coordinate should be specified as west, south, east, north.", + "description": "Bounding box: Specifies the geographic area to search within, using a bounding box defined by four coordinates in the order: west, south, east, north. Accepts an array of four numeric values.", "required": false, "schema": { "maxItems": 4, @@ -335,7 +335,7 @@ { "name": "other_published_locations", "in": "query", - "description": "Other published locations", + "description": "Other published locations: Lists additional places where the dataset has been published. Supports contains match.", "required": false, "schema": { "type": "string" @@ -344,7 +344,7 @@ { "name": "dataset_update_frequency_months", "in": "query", - "description": "Dataset update frequency in months", + "description": "Dataset update frequency in months: Filters datasets based on how frequently they are updated. Uses a greater than or equal to match to include datasets updated at this frequency or more often.", "required": false, "schema": { "type": "integer" @@ -353,7 +353,7 @@ { "name": "schema_validation_run_description", "in": "query", - "description": "Schema validation run description", + "description": "Schema validation run description: Filters datasets based on the description of the schema validation run. Accepts a string value and uses contains match.", "required": false, "schema": { "type": "string" @@ -362,7 +362,7 @@ { "name": "full_dataset_name", "in": "query", - "description": "Full dataset name", + "description": "Full dataset name: Filters datasets based on their full name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -371,7 +371,7 @@ { "name": "collection_name", "in": "query", - "description": "Name of the collection", + "description": "Collection name: Filters datasets based on their collection name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -380,7 +380,7 @@ { "name": "department_name", "in": "query", - "description": "Name of the department", + "description": "Department name: Filters datasets based on their department name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -389,7 +389,7 @@ { "name": "city", "in": "query", - "description": "Name of the city", + "description": "Name of City: Filters datasets based on the city name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -398,7 +398,7 @@ { "name": "region", "in": "query", - "description": "Name of the region", + "description": "Region: Filters datasets based on the region name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -407,7 +407,7 @@ { "name": "county", "in": "query", - "description": "Name of the county", + "description": "County: Filters datasets based on the county name. Supports contains match.", "required": false, "schema": { "type": "string" @@ -416,7 +416,7 @@ { "name": "key_limitations", "in": "query", - "description": "Key limitations of the dataset", + "description": "Key limitations: Filters datasets based on their key limitations. Supports contains match.", "required": false, "schema": { "type": "string" @@ -425,7 +425,7 @@ { "name": "release_notes", "in": "query", - "description": "Release notes", + "description": "Release notes: Filters datasets based on their release notes. Supports contains match.", "required": false, "schema": { "type": "string" @@ -434,7 +434,7 @@ { "name": "challenges", "in": "query", - "description": "Challenges faced in collecting the data", + "description": "Challenges: Filters datasets based on the challenges faced in collecting the data. Supports contains match.", "required": false, "schema": { "type": "string" @@ -443,7 +443,7 @@ { "name": "official_maintainer", "in": "query", - "description": "Official maintainer of the dataset", + "description": "Official maintainer: Filters datasets based on the official maintainer. Supports contains match.", "required": false, "schema": { "type": "array", @@ -455,7 +455,7 @@ { "name": "last_updated", "in": "query", - "description": "Date when the dataset was last updated", + "description": "Last updated: Filters datasets based on the last updated date. Accepts a date-time string match.", "required": false, "schema": { "type": "string" @@ -464,7 +464,7 @@ { "name": "update_frequency", "in": "query", - "description": "Frequency of updates", + "description": "Update frequency: Filters datasets based on their update frequency. Supports contains match.", "required": false, "schema": { "type": "string" @@ -473,7 +473,7 @@ { "name": "authorization_chain", "in": "query", - "description": "Authorization chain", + "description": "Authorization chain: Filters datasets based on their authorization chain. Supports contains match.", "required": false, "schema": { "type": "string" @@ -482,7 +482,7 @@ { "name": "maintenance_funded", "in": "query", - "description": "Is maintenance funded", + "description": "Maintenance funded: Filters datasets based on whether they are funded for maintenance. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -491,7 +491,7 @@ { "name": "funding_details", "in": "query", - "description": "Funding details", + "description": "Funding details: Filters datasets based on their funding details. Supports contains match.", "required": false, "schema": { "type": "string" @@ -500,7 +500,7 @@ { "name": "point_data_collection_device", "in": "query", - "description": "Point data collection device", + "description": "Point data collection device: Filters datasets based on the device used for point data collection. Supports contains match.", "required": false, "schema": { "type": "string" @@ -509,7 +509,7 @@ { "name": "node_locations_and_attributes_editing_software", "in": "query", - "description": "Node locations and attributes editing software", + "description": "Node locations and attributes editing software: Filters datasets based on the software used for editing node locations and attributes. Supports contains match.", "required": false, "schema": { "type": "string" @@ -518,7 +518,7 @@ { "name": "data_collected_by_people", "in": "query", - "description": "Is data collected by people", + "description": "Data collected by people: Filters datasets based on whether the data was collected by people. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -527,7 +527,7 @@ { "name": "data_collectors", "in": "query", - "description": "Data collectors", + "description": "Data collectors: Filters datasets based on the individuals or organizations that collected the data. Supports contains match.", "required": false, "schema": { "type": "string" @@ -536,7 +536,7 @@ { "name": "data_captured_automatically", "in": "query", - "description": "Is data captured automatically", + "description": "Data captured automatically: Filters datasets based on whether the data was captured automatically. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -545,7 +545,7 @@ { "name": "automated_collection", "in": "query", - "description": "Automated collection", + "description": "Automated collection: Filters datasets based on whether the data was collected automatically. Supports contains match.", "required": false, "schema": { "type": "string" @@ -554,7 +554,7 @@ { "name": "data_collectors_organization", "in": "query", - "description": "Data collectors organization", + "description": "Data collectors organization: Filters datasets based on the organization of the data collectors. Supports contains match.", "required": false, "schema": { "type": "string" @@ -563,7 +563,7 @@ { "name": "data_collector_compensation", "in": "query", - "description": "Data collector compensation", + "description": "Data collector compensation: Filters datasets based on whether the data collectors were compensated. Supports contains match.", "required": false, "schema": { "type": "string" @@ -572,7 +572,7 @@ { "name": "preprocessing_location", "in": "query", - "description": "Preprocessing location", + "description": "Preprocessing location: Filters datasets based on their preprocessing location. Supports contains match.", "required": false, "schema": { "type": "string" @@ -581,7 +581,7 @@ { "name": "preprocessing_by", "in": "query", - "description": "Preprocessing by", + "description": "Preprocessing by: Filters datasets based on who performed the preprocessing. Supports contains match.", "required": false, "schema": { "type": "string" @@ -590,7 +590,7 @@ { "name": "preprocessing_steps", "in": "query", - "description": "Preprocessing steps", + "description": "Preprocessing steps: Filters datasets based on their preprocessing steps. Supports contains match.", "required": false, "schema": { "type": "string" @@ -599,7 +599,7 @@ { "name": "data_collection_preprocessing_documentation", "in": "query", - "description": "Is data collection preprocessing documentation available", + "description": "Data collection preprocessing documentation: Filters datasets based on the availability of data collection preprocessing documentation. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -608,7 +608,7 @@ { "name": "documentation_uri", "in": "query", - "description": "Documentation URI", + "description": "Documentation URI: Filters datasets based on their documentation URI. Supports contains match.", "required": false, "schema": { "type": "string" @@ -617,7 +617,7 @@ { "name": "validation_process_exists", "in": "query", - "description": "Is validation process exists", + "description": "Validation process exists: Filters datasets based on whether a validation process exists. Uses a boolean value.", "required": false, "schema": { "type": "boolean" @@ -626,7 +626,7 @@ { "name": "validation_process_description", "in": "query", - "description": "Validation process description", + "description": "Validation process description: Filters datasets based on the description of the validation process. Supports contains match.", "required": false, "schema": { "type": "string" @@ -635,7 +635,7 @@ { "name": "validation_conducted_by", "in": "query", - "description": "Validation conducted by", + "description": "Validation conducted by: Filters datasets based on who conducted the validation. Supports contains match.", "required": false, "schema": { "type": "string" @@ -644,7 +644,7 @@ { "name": "excluded_data", "in": "query", - "description": "Excluded data", + "description": "Excluded data: Filters datasets based on whether they contain excluded data. Supports contains match.", "required": false, "schema": { "type": "string" @@ -653,16 +653,25 @@ { "name": "excluded_data_reason", "in": "query", - "description": "Excluded data reason", + "description": "Excluded data reason: Filters datasets based on the reason for excluding data. Supports contains match.", "required": false, "schema": { "type": "string" } }, + { + "name": "data_viewer_allowed", + "in": "query", + "description": "Data viewer allowed: Filters datasets based on whether data viewer access is allowed. Uses a boolean value.", + "required": false, + "schema": { + "type": "boolean" + } + }, { "name": "page_no", "in": "query", - "description": "Integer, defaults to 1. Retrieves the results in pages.", + "description": "page_no: Integer, defaults to 1. Filters datasets by retrieving results in pages.", "required": false, "schema": { "type": "integer", @@ -673,7 +682,7 @@ { "name": "page_size", "in": "query", - "description": "Page size. integer, between 1 to 50, defaults to 10.Specifies total records per page.", + "description": "Page size: Integer, between 1 to 50, defaults to 10.Specifies total records per page.", "required": false, "schema": { "type": "integer", @@ -684,7 +693,7 @@ { "name": "sort_field", "in": "query", - "description": "Sort field. By default, it is by uploaded timestamp.", + "description": "Sort field: The field by which to sort the results. By default, it is by uploaded timestamp. Matches the exact value from the supported enumeration.", "required": false, "schema": { "type": "string", @@ -701,7 +710,7 @@ { "name": "sort_order", "in": "query", - "description": "Sort order. By default, it is in descending order.", + "description": "Sort order: By default, it is in descending order.", "required": false, "schema": { "type": "string", @@ -2006,7 +2015,7 @@ "join_condition": { "type": "string", "example": "ST_Intersects(ST_Buffer(geometry_target, 5), geometry_source)", - "description": "Condition on which target and source geometry will join. geometry_target & geometry_source are constant variable representing the element geometry.\n" + "description": "Condition on which target and source geometry will join. geometry_target & geometry_source are constant variable representing the element geometry. " }, "join_filter_target": { "type": "string", @@ -2110,117 +2119,696 @@ } } ], - "responses": { - "202": { - "description": "The request has been accepted for processing. It returns a `job_id`, a unique identifier for the request, which can be used to track the status of the request. The endpoint to check the status is provided in the location header of the response.", + "responses": { + "202": { + "description": "The request has been accepted for processing. It returns a `job_id`, a unique identifier for the request, which can be used to track the status of the request. The endpoint to check the status is provided in the location header of the response.", + "content": { + "application/text": { + "schema": { + "type": "string" + } + } + }, + "headers": { + "Location": { + "schema": { + "type": "string" + }, + "description": "Location api to find the status of request processing" + } + } + }, + "401": { + "description": "Unauthenticated request. Check your access token." + }, + "404": { + "description": "tdei_dataset_id doesn't exist in the system." + }, + "500": { + "description": "An server error occurred." + } + }, + "security": [ + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/osw/union": { + "post": { + "tags": [ + "OSW" + ], + "summary": "Performs a union of the two input OSW datasets.", + "description": "This function merges spatial data from two datasets by unifying overlapping nodes, edges, and polygons into consolidated geometries. It identifies equivalent nodes based on proximity, aligns and merges overlapping edges, and combines adjacent polygons. The function outputs a single cohesive dataset.The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint.", + "operationId": "osw-union", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "tdei_dataset_id_one": { + "type": "string", + "example": "fa8e12ea-6b0c-4d3e-8b38-5b87b268e76b", + "description": "Dataset id defined to be unioned" + }, + "tdei_dataset_id_two": { + "type": "string", + "example": "0d661b69495d47fb838862edf699fe09", + "description": "Dataset id defined to be unioned" + }, + "proximity": { + "type": "number", + "example": "0.5", + "description": "Proximity value to identify equivalent nodes in meters. Default value is 0.5 meters." + } + }, + "required": [ + "tdei_dataset_id_one", + "tdei_dataset_id_two" + ] + } + } + }, + "required": true + }, + "responses": { + "202": { + "description": "The request has been accepted for processing. It returns a `job_id`, a unique identifier for the request, which can be used to track the status of the request. The endpoint to check the status is provided in the location header of the response.", + "content": { + "application/text": { + "schema": { + "type": "string" + } + } + }, + "headers": { + "Location": { + "schema": { + "type": "string" + }, + "description": "Location api to find the status of request processing" + } + } + }, + "400": { + "description": "The request body is empty." + }, + "401": { + "description": "Unauthenticated request. Check your access token." + }, + "404": { + "description": "Dataset not found for either tdei_dataset_id_one or tdei_dataset_id_two." + }, + "500": { + "description": "An Internal server error occured." + } + }, + "security": [ + { + "ApiKey": [] + }, + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/osw/dataset-viewer/{tdei_dataset_id}": { + "post": { + "tags": [ + "OSW" + ], + "summary": "Updates the visibility preferences for the dataset viewer.", + "description": "Updates the visibility preferences for a specified dataset identified by the tdei_dataset_id. It takes the dataset ID as a parameter and modifies the dataset's visibility settings.", + "operationId": "oswDatasetViewer", + "parameters": [ + { + "name": "tdei_dataset_id", + "in": "path", + "description": "Dataset ID for updating the dataset viewer preferences.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "allow_viewer_access": { + "type": "boolean", + "default": true, + "description": "Indicates whether the dataset viewer access is allowed." + } + }, + "required": [ + "allow_viewer_access" + ] + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Visibility preferences for the dataset viewer updated successfully.", + "content": { + "application/text": { + "schema": { + "type": "string" + } + } + } + }, + "401": { + "description": "Unauthenticated request. Check your access token." + }, + "403": { + "description": "Forbidden request. Dataset viewer access is not allowed at project group level." + }, + "404": { + "description": "tdei_dataset_id doesn't exist in the system." + }, + "500": { + "description": "An server error occurred." + } + }, + "security": [ + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/osw/dataset-viewer/pm-tiles/{tdei_dataset_id}": { + "get": { + "tags": [ + "OSW" + ], + "summary": "Retrives the PM tiles SAS url for the dataset.", + "description": "Retrieves the PM tiles SAS url for a specified dataset identified by the tdei_dataset_id.", + "operationId": "oswDatasetViewerPMTiles", + "parameters": [ + { + "name": "tdei_dataset_id", + "in": "path", + "description": "Dataset ID for retrieving the PM tiles SAS url.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "PM tiles SAS url retrieved successfully.", + "content": { + "application/text": { + "schema": { + "type": "string" + } + } + } + }, + "401": { + "description": "Unauthenticated request. Check your access token." + }, + "403": { + "description": "Forbidden request. Dataset viewer access is not allowed at dataset or project group level." + }, + "404": { + "description": "tdei_dataset_id doesn't exist in the system." + }, + "500": { + "description": "An server error occurred." + } + }, + "security": [ + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/osw/dataset-viewer/feedbacks/{project_id}/{tdei_dataset_id}": { + "post": { + "tags": [ + "OSW" + ], + "summary": "Accepts the feedback from the dataset viewer.", + "description": "Accepts the feedback from the dataset viewer. The feedback is stored in the system for further analysis and improvement of the dataset.", + "operationId": "oswDatasetViewerFeedback", + "parameters": [ + { + "name": "project_id", + "in": "path", + "required": true, + "description": "ID of the project group.", + "schema": { + "type": "string" + } + }, + { + "name": "tdei_dataset_id", + "in": "path", + "required": true, + "description": "ID of the dataset.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "dataset_element_id": { + "type": "string", + "description": "Dataset ID for which the feedback is provided.", + "example": "14325" + }, + "feedback_text": { + "type": "string", + "description": "Feedback provided by the user regarding the dataset viewer.", + "example": "The dataset viewer is very informative and easy to use." + }, + "customer_email": { + "type": "string", + "format": "email", + "description": "Email address of the user providing feedback. This is optional and can be used for follow-up if needed.", + "example": "user@example.com" + }, + "location_latitude": { + "type": "number", + "format": "double", + "description": "Latitude of the location where the feedback was provided." + }, + "location_longitude": { + "type": "number", + "format": "double", + "description": "Longitude of the location where the feedback was provided." + } + }, + "required": [ + "feedback_text", + "location", + "customer_email" + ] + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Feedback submitted successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "example": "Feedback submitted successfully." + } + } + } + } + } + }, + "400": { + "description": "Invalid input parameters." + }, + "403": { + "description": "CORS error. The request is not allowed from the current origin." + }, + "404": { + "description": "Project group or dataset not found." + }, + "500": { + "description": "An server error occurred." + } + }, + "security": [ + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/osw/dataset-viewer/feedbacks": { + "get": { + "tags": [ + "OSW" + ], + "summary": "Retrieves the dataset viewer feedbacks.", + "description": "Retrieves the dataset viewer feedbacks. Response includes a list of feedbacks provided by users regarding the dataset. Each feedback contains details such as the dataset element ID, feedback text, customer email, and location information.", + "operationId": "oswDatasetViewerFeedbacks", + "parameters": [ + { + "name": "tdei_project_group_id", + "in": "query", + "required": false, + "description": "ID of the project group.", + "schema": { + "type": "string" + } + }, + { + "name": "tdei_dataset_id", + "in": "query", + "required": false, + "description": "ID of the dataset.", + "schema": { + "type": "string" + } + }, + { + "name": "from_date", + "in": "query", + "description": "from_date: Date in ISO 8601 format, filters feedbacks created after this date.", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "to_date", + "in": "query", + "description": "to_date: Date in ISO 8601 format, filters feedbacks created before this date.", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "status", + "in": "query", + "required": false, + "description": "status: Filters feedbacks by their status.", + "schema": { + "type": "string", + "enum": [ + "open", + "resolved" + ] + } + }, + { + "name": "sort_by", + "in": "query", + "description": "sort_by: String, defaults to 'created_at'. Sorts feedbacks by the specified field.", + "required": false, + "schema": { + "type": "string", + "default": "created_at", + "enum": [ + "created_at", + "due_date" + ] + } + }, + { + "name": "sort_order", + "in": "query", + "description": "sort_order: String, defaults to 'desc'. Sorts feedbacks in ascending or descending order.", + "required": false, + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + } + }, + { + "name": "page_no", + "in": "query", + "description": "page_no: Integer, defaults to 1. Specifies the page number to retrieve.", + "required": false, + "schema": { + "type": "integer", + "format": "int32", + "default": 1 + } + }, + { + "name": "page_size", + "in": "query", + "description": "Page size: Integer, between 1 to 50, defaults to 10. Specifies total records per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "responses": { + "200": { + "description": "Feedbacks retrieved successfully.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Feedback" + } + } + } + } + }, + "500": { + "description": "An server error occurred." + } + }, + "security": [ + { + "AuthorizationToken": [] + } + ] + } + }, + "/api/v1/osw/dataset-viewer/feedbacks/download/{tdei_project_group_id}":{ + "get":{ + "tags":[ + "OSW" + ], + "summary":"Downloads dataset viewer feedbacks as a CSV.", + "description":"Streams all feedback for the specified project group in CSV format. Requires poc or osw_data_generator role.", + "operationId":"oswDatasetViewerFeedbacksDownload", + "parameters":[ + { + "name": "tdei_project_group_id", + "in": "path", + "description": "Valid TDEI project group id.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name":"tdei_dataset_id", + "in":"query", + "required":false, + "description":"ID of the dataset.", + "schema":{ + "type":"string" + } + }, + { + "name":"from_date", + "in":"query", + "description":"from_date: Date in ISO 8601 format, filters feedback created after this date.", + "required":false, + "schema":{ + "type":"string", + "format":"date-time" + } + }, + { + "name":"to_date", + "in":"query", + "description":"to_date: Date in ISO 8601 format, filters feedback created before this date.", + "required":false, + "schema":{ + "type":"string", + "format":"date-time" + } + }, + { + "name":"status", + "in":"query", + "required":false, + "description":"status: Filters feedbacks by their status.", + "schema":{ + "type":"string", + "enum":[ + "open", + "resolved" + ] + } + }, + { + "name":"sort_by", + "in":"query", + "description":"sort_by: String, defaults to 'created_at'. Sorts feedbacks by the specified field.", + "required":false, + "schema":{ + "type":"string", + "default":"created_at", + "enum":[ + "created_at", + "due_date" + ] + } + }, + { + "name":"due_date", + "in":"query", + "description":"due_date: Legacy alias for sort_by. Use 'created_at' or 'due_date'.", + "required":false, + "schema":{ + "type":"string", + "enum":[ + "created_at", + "due_date" + ] + } + }, + { + "name":"sort_order", + "in":"query", + "description":"sort_order: String, defaults to 'desc'. Sorts feedbacks in ascending or descending order.", + "required":false, + "schema":{ + "type":"string", + "default":"desc", + "enum":[ + "asc", + "desc" + ] + } + }, + { + "name":"page_no", + "in":"query", + "description":"page_no: Integer, specifies the page number to retrieve. If omitted with page_size, the response is unpaginated.", + "required":false, + "schema":{ + "type":"integer", + "format":"int32" + } + }, + { + "name":"page_size", + "in":"query", + "description":"Page size: Integer, between 1 to 50. If omitted with page_no, the response is unpaginated.", + "required":false, + "schema":{ + "type":"integer", + "format":"int32" + } + }, + { + "name":"format", + "in":"query", + "required":false, + "description":"format: Output format.", + "schema":{ + "type":"string", + "default":"csv", + "enum":[ + "csv", + "geojson" + ] + } + } + ], + "responses":{ + "200": { + "description": "Feedback file streamed successfully.", "content": { - "application/text": { + "text/csv": { + "schema": { "type": "string", "format": "binary" } + }, + "application/geo+json": { "schema": { - "type": "string" + "type": "object", + "required": ["type", "features"], + "properties": { + "type": { "enum": ["FeatureCollection"] }, + "features": { + "type": "array", + "items": { "$ref": "#/components/schemas/Feature" } + } + } } } - }, - "headers": { - "Location": { - "schema": { - "type": "string" - }, - "description": "Location api to find the status of request processing" - } } }, - "401": { - "description": "Unauthenticated request. Check your access token." - }, - "404": { - "description": "tdei_dataset_id doesn't exist in the system." + "400":{ + "description":"Invalid request parameters." }, - "500": { - "description": "An server error occurred." + "500":{ + "description":"A server error occurred." } }, - "security": [ + "security":[ { - "AuthorizationToken": [] + "AuthorizationToken":[ + + ] } ] } }, - "/api/v1/osw/union": { - "post": { + "/api/v1/osw/dataset-viewer/feedbacks/metadata": { + "get": { "tags": [ "OSW" ], - "summary": "Performs a union of the two input OSW datasets.", - "description": "This function merges spatial data from two datasets by unifying overlapping nodes, edges, and polygons into consolidated geometries. It identifies equivalent nodes based on proximity, aligns and merges overlapping edges, and combines adjacent polygons. The function outputs a single cohesive dataset.The response includes a `job_id` for tracking the request.To check the request status, refer to the location header in the response, which provides the URL for the status API endpoint.", - "operationId": "osw-union", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "tdei_dataset_id_one": { - "type": "string", - "example": "fa8e12ea-6b0c-4d3e-8b38-5b87b268e76b", - "description": "Dataset id defined to be unioned" - }, - "tdei_dataset_id_two": { - "type": "string", - "example": "0d661b69495d47fb838862edf699fe09", - "description": "Dataset id defined to be unioned" - }, - "proximity": { - "type": "number", - "example": "0.5", - "description": "Proximity value to identify equivalent nodes in meters. Default value is 0.5 meters." - } - }, - "required": [ - "tdei_dataset_id_one", - "tdei_dataset_id_two" - ] - } + "summary": "Retrieves the feedbacks summary.", + "description": "Retrieves the feedbacks summary. Response includes a summary of feedbacks such as total count, total overdue, and other relevant statistics.", + "operationId": "oswDatasetViewerFeedbacksMetadata", + "parameters": [ + { + "name": "tdei_project_group_id", + "in": "query", + "required": false, + "description": "ID of the project group.", + "schema": { + "type": "string" } - }, - "required": true - }, + } + ], "responses": { - "202": { - "description": "The request has been accepted for processing. It returns a `job_id`, a unique identifier for the request, which can be used to track the status of the request. The endpoint to check the status is provided in the location header of the response.", + "200": { + "description": "Feedbacks summary retrieved successfully.", "content": { - "application/text": { + "application/json": { "schema": { - "type": "string" + "$ref": "#/components/schemas/FeedbackMetadata" } } - }, - "headers": { - "Location": { - "schema": { - "type": "string" - }, - "description": "Location api to find the status of request processing" - } } }, - "400": { - "description": "The request body is empty." - }, - "401": { - "description": "Unauthenticated request. Check your access token." - }, - "404": { - "description": "Dataset not found for either tdei_dataset_id_one or tdei_dataset_id_two." - }, "500": { - "description": "An Internal server error occured." + "description": "An server error occurred." } }, "security": [ - { - "ApiKey": [] - }, { "AuthorizationToken": [] } @@ -3734,6 +4322,11 @@ "tdei_project_group_id": { "type": "string", "example": "4e991e7a-5c16-4ebf-ad31-3a3625bcca10" + }, + "dataset_viewer_allowed": { + "type": "boolean", + "default": false, + "description": "Flag to indicate to allow dataset to be viewed on the dataset viewer." } }, "required": [ @@ -3859,16 +4452,171 @@ ], "type": "object", "properties": { - "polygon": { - "$ref": "#/components/schemas/GeoJsonObject" - }, "tdei_project_group_id": { "type": "string", - "description": "Unique id that represents the project group." + "description": "ProjectGroupId uniquely represented in the TDEI system. System generated.", + "default": "0" }, - "project_group_name": { + "name": { "type": "string", "description": "Name of the project group." + }, + "phone": { + "type": "string", + "description": "Phone of the project group for communication." + }, + "url": { + "type": "string", + "description": "Url of the transit project group." + }, + "address": { + "type": "string", + "description": "Address of the transit project group." + }, + "polygon": { + "$ref": "#/components/schemas/Polygon" + }, + "poc": { + "type": "array", + "description": "Project group POC details", + "items": { + "$ref": "#/components/schemas/POC", + "description": "POC details" + } + }, + "data_viewer": { + "type": "object", + "properties": { + "dataset_viewer_allowed": { + "type": "boolean", + "default": false, + "description": "Flag to indicate to allow all datasets within the project group to be viewed on the dataset viewer." + }, + "feedback_turnaround_time": { + "type": "object", + "description": "Feedback turnaround time for the project group.", + "properties": { + "number": { + "type": "integer", + "description": "Number of days for feedback turnaround time." + }, + "unit": { + "type": "string", + "enum": [ + "days", + "months", + "years" + ], + "description": "Unit of time for feedback turnaround time." + } + } + } + }, + "description": "Describes an Project group." + } + } + }, + "POC": { + "type": "object", + "properties": { + "first_name": { + "type": "string" + }, + "last_name": { + "type": "string" + }, + "username": { + "type": "string" + }, + "email": { + "type": "string" + } + }, + "required": [ + "first_name", + "last_name", + "username", + "email" + ] + }, + "Polygon": { + "title": "GeoJSON FeatureCollection", + "type": "object", + "required": [ + "type", + "features" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "FeatureCollection" + ] + }, + "features": { + "type": "array", + "items": { + "title": "GeoJSON Feature", + "type": "object", + "required": [ + "type", + "properties", + "geometry" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "Feature" + ] + }, + "id": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ] + }, + "properties": { + "type": "object" + }, + "geometry": { + "title": "GeoJSON Polygon", + "type": "object", + "required": [ + "type", + "coordinates" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "Polygon" + ] + }, + "coordinates": { + "type": "array", + "items": { + "type": "array", + "minItems": 4, + "items": { + "type": "array", + "minItems": 2, + "maxItems": 2, + "items": { + "type": "number", + "format": "double" + } + } + } + } + } + } + } + } } } }, @@ -4343,6 +5091,115 @@ "project_group", "services" ] + }, + "Feedback": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the feedback.", + "example": "10432" + }, + "project_group": { + "type": "object", + "properties": { + "tdei_project_group_id": { + "type": "string", + "description": "ID of the project group.", + "example": "4e991e7a-5c16-4ebf-ad31-3a3625bcca10" + }, + "name": { + "type": "string", + "description": "Name of the project group." + } + }, + "required": [ + "tdei_project_group_id", + "name" + ] + }, + "dataset": { + "type": "object", + "properties": { + "tdei_dataset_id": { + "type": "string", + "description": "ID of the dataset.", + "example": "4e991e7a-5c16-4ebf-ad31-3a3625bcca10" + }, + "name": { + "type": "string", + "description": "Name of the dataset." + } + }, + "required": [ + "tdei_dataset_id", + "name" + ] + }, + "feedback_text": { + "type": "string", + "description": "Feedback text provided by the user." + }, + "dataset_element_id": { + "type": "string", + "description": "ID of the specific dataset element related to the feedback.", + "example": "10432" + }, + "status": { + "type": "string", + "description": "Status of the feedback.", + "enum": [ + "open", + "resolved" + ] + }, + "location_latitude": { + "type": "number", + "description": "Latitude of the location related to the feedback.", + "example": 37.7749 + }, + "location_longitude": { + "type": "number", + "description": "Longitude of the location related to the feedback.", + "example": -122.4194 + }, + "due_date": { + "type": "string", + "format": "date-time", + "description": "Due date for the feedback response." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the feedback was created." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the feedback was last updated." + } + } + }, + "FeedbackMetadata": { + "type": "object", + "description": "Additional metadata related to the feedback.", + "properties": { + "total_count": { + "type": "string", + "description": "Count of feedback entries.", + "example": "5" + }, + "total_overdues": { + "type": "number", + "description": "Count of feedback entries.", + "example": 5 + }, + "total_open": { + "type": "number", + "description": "Indicates number of open feedbacks.", + "example": 3 + } + } } }, "securitySchemes": {