AMCS Group ApiGpsDataExternal API

openapi: 3.0.1
info:
  title: Core AccessGroup ApiGpsDataExternal API
  version: core
tags:
- name: ApiGpsDataExternal
paths:
  /integrator/gpsdata/changes:
    get:
      tags:
      - ApiGpsDataExternal
      summary: 'Response: API GPS Data External'
      description: "# API GPS Data Changes\n\nProvides a structured response for changes in GPS Data Points.\n\n## How to Use This API\n\nThis API retrieves GPS data point changes using either a timestamp (`Since`) or a pagination cursor (`Cursor`).\n\n### **Usage Guidelines**\n- If `Since` is provided, the API returns data changes from that timestamp onwards.\n- If `Cursor` is provided, the API retrieves the next set of results from the given position.\n- If both `Since` and `Cursor` are omitted, the result is the same as using `Cursor`, meaning it will retrieve the most recent set of changes.\n- `Links.Next` contains both a URL and a `Cursor`. This will have data only if the response contains a `Cursor` value.\n- **A maximum of 2000 items can be retrieved per request.** If more data is required, use pagination via the `Cursor` parameter.\n\n## **Request Parameters**\n\n| Parameter   | Type        | Required | Description |\n|------------|------------|----------|-------------|\n| **Since**  | `DateTime?` | No       | The timestamp from which to retrieve changes. |\n| **Cursor** | `string`    | No       | A pagination cursor to fetch the next set of data. |\n\n---\n\n## **Response Structure**\n\n### **Main Response Object**\n| Property   | Type                                   | Description                                                   |\n|------------|---------------------------------------|---------------------------------------------------------------|\n| **Resource**   | `List<GpsDataPointChangeResourceDto>` | List of GPS data point changes.                               |\n| **Links**      | `GpsDataPointChangesLink`         | Links object containing navigation links.                     |\n| **Links.Next** | `string`                          | Contains the next page URL and cursor if there are more results. Will be present only if `Cursor` is included in the response. |\n| **Extra**      | `GpsDataPointChangesExtra`        | Extra information for pagination, including cursors and until. |\n\n---\n\n### **Links Object**\n| Property   | Type   | Description                     |\n|------------|--------|---------------------------------|\n| **Next**   | `string` | Link to the next page of data. Will only be present if `Cursor` is included in the response. |\n\n---\n\n### **Extra Object**\n| Property   | Type   | Description                                                                 |\n|------------|--------|---------------------------------------------------------------------------|\n| **Cursor** | `string` | Bookmark for navigating through pages.                                   |\n| **Until**  | `string` | Timestamp indicating the end of the range. If the `Cursor` is lost or unavailable, this `Until` timestamp can be used as the `Since` value in a new request to continue retrieving data from the last known point. |\n\n---\n\n### **GpsDataPointChangeResourceDto Object**\n| Property     | Type                        | Description                                  |\n|--------------|----------------------------|----------------------------------------------|\n| **Resource** | `GpsDataPointChangeDto`    | The GPS data point change details.          |\n\n---\n\n### **GpsDataPointChangeDto Object**\n| Property     | Type       | Description                                  |\n|--------------|-----------|----------------------------------------------|\n| **Id**       | `string`     | Unique identifier for the GPS data point.  |\n| **PlateNo**  | `string`     | Vehicle plate number associated with the data point. |\n| **Timestamp** | `DateTime`   | Date and time of the GPS data point.       |\n| **Latitude**  | `double`     | Latitude of the GPS data point.            |\n| **Longitude** | `double`     | Longitude of the GPS data point.           |\n| **SpeedKmh**  | `int`        | Speed in kilometers per hour.              |\n| **TenantId**  | `Guid`       | Identifier for the associated tenant.      |\n\n---\n\n### **Example Request**\n```json\n{\n  \"Since\": \"2024-02-21T12:00:00Z\",\n  \"Cursor\": \"abcdef\"\n}\n```\n\n---\n\n### **Example Response**\n```json\n{\n  \"Resource\": [\n    {\n      \"Resource\": {\n        \"Id\": \"12345\",\n        \"PlateNo\": \"ABC123\",\n        \"Timestamp\": \"2024-02-21T14:30:00Z\",\n        \"Latitude\": 14.5995,\n        \"Longitude\": 120.9842,\n        \"SpeedKmh\": 60,\n        \"TenantId\": \"550e8400-e29b-41d4-a716-446655440000\"\n      }\n    }\n  ],\n  \"Links\": {\n    \"Next\": \"/integrator/gpsdata/changes?cursor=abcdef\"\n  },\n  \"Extra\": {\n    \"Cursor\": \"abcdef\",\n    \"Until\": \"2024-02-21T15:00:00Z\"\n  }\n}\n```\n\n---\n\n### **Pagination Instructions**\n- If the response includes a `Next` link, call the API again using the `Cursor` parameter from the `Extra` object to fetch the next batch of data.\n- If the `Cursor` is lost or unavailable, use the `Until` timestamp as the `Since` value in a new request to continue retrieving data.\n- **Each request can return a maximum of 2000 items.** To retrieve more data, continue calling the API with the `Next` link until no `Next` link is provided.\n\n---\n\n### **HTTP Status Codes**\n- **`200 OK`** – Successful response with GPS data point changes.\n- **`400 Bad Request`** – Invalid request parameters.\n- **`500 Internal Server Error`** – Unexpected server error."
      parameters:
      - name: Since
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: The timestamp to retrieve changes from.
      - name: Cursor
        in: query
        required: false
        schema:
          type: string
        description: A cursor for paginated results.
      responses:
        '200':
          description: Successful response with GPS data point changes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GpsDataPointChangesResponse'
        '400':
          description: Invalid request parameters.
        '500':
          description: Internal server error.
components:
  schemas:
    GpsDataPointChangesExtra:
      type: object
      properties:
        Cursor:
          type: string
        Until:
          type: string
    GpsDataPointChangeResourceDto:
      type: object
      properties:
        Resource:
          $ref: '#/components/schemas/GpsDataPointChangeDto'
    GpsDataPointChangeDto:
      type: object
      properties:
        Id:
          type: string
        PlateNo:
          type: string
        Timestamp:
          type: string
          format: date-time
        Latitude:
          type: number
          format: double
        Longitude:
          type: number
          format: double
        SpeedKmh:
          type: integer
          format: int32
        TenantId:
          type: string
          format: uuid
    GpsDataPointChangesLink:
      type: object
      properties:
        Next:
          type: string
    GpsDataPointChangesResponse:
      type: object
      properties:
        Resource:
          type: array
          items:
            $ref: '#/components/schemas/GpsDataPointChangeResourceDto'
        Extra:
          $ref: '#/components/schemas/GpsDataPointChangesExtra'
        Links:
          $ref: '#/components/schemas/GpsDataPointChangesLink'