> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fleeticc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# History

> Past GPS points for a vehicle, or the nearest point at a given time

```
GET https://api.fleeticc.com/api/partner/v1/history
```

Identify the vehicle with **either** `vehicleId` or `imei`.

## Headers

**X-Api-Key** `string` *required*

Your Partner API key

**X-Timestamp** `string` *required*

Unix seconds

**X-Signature** `string` *required*

HMAC signature of the full path **including** the query string

## Trip history (time range)

**vehicleId** `string`

Fleeticc vehicle UUID (or use `imei`)

**imei** `string`

Device IMEI (or use `vehicleId`)

**from** `integer` *required*

Start time (Unix seconds)

**to** `integer` *required*

End time (Unix seconds)

Maximum range is **7 days** per request.

### Request example

```bash theme={null}
export PATH="/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin:$PATH"
KEY="$FLEETICC_API_KEY"
SECRET="$FLEETICC_API_SECRET"
IMEI="359633100000001"
FROM=$(($(date +%s) - 86400))
TO=$(date +%s)
REQ_PATH="/api/partner/v1/history?imei=${IMEI}&from=${FROM}&to=${TO}"
TS=$(date +%s)
BODY_HASH=$(printf '' | openssl dgst -sha256 -hex | awk '{print $NF}')
SIG=$(printf 'GET\n%s\n%s\n%s' "$REQ_PATH" "$TS" "$BODY_HASH" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')

curl -sS -X GET "https://api.fleeticc.com$REQ_PATH" \
  -H "X-Api-Key: $KEY" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"
```

### Example response

```json theme={null}
{
  "code": "200",
  "message": "Partner GPS history retrieved successfully.",
  "data": {
    "mode": "range",
    "vehicleId": "8f3c2a1b-4d5e-6f70-8192-a3b4c5d6e7f8",
    "imei": "359633100000001",
    "from": 1761190000,
    "to": 1761200000,
    "record": [
      {
        "timestamp": 1761190100,
        "latitude": 7.29,
        "longitude": 80.63,
        "speed": 12,
        "heading": 90,
        "accstatus": 1
      }
    ]
  }
}
```

## Location at a specific time

Useful when you already have a timestamp (for example a stop or job event) and want the GPS point closest to that moment.

**vehicleId** `string`

Fleeticc vehicle UUID (or use `imei`)

**imei** `string`

Device IMEI (or use `vehicleId`)

**at** `integer` *required*

Time you care about (Unix seconds)

**windowSeconds** `integer`

Search ± this many seconds (default `300`, max `3600`)

If GPS was offline at that moment, `point` may be `null`. Save `at` and try again later.

### Example response

```json theme={null}
{
  "code": "200",
  "message": "Partner GPS history retrieved successfully.",
  "data": {
    "mode": "nearest",
    "at": 1761200000,
    "windowSeconds": 300,
    "point": {
      "timestamp": 1761199988,
      "latitude": 7.2911,
      "longitude": 80.635,
      "speed": 0,
      "heading": 10,
      "accstatus": 0
    }
  }
}
```

## Limits

Up to **60** requests per minute per API key. Max range **7 days** per `from`/`to` request.


## OpenAPI

````yaml GET /api/partner/v1/history
openapi: 3.1.0
info:
  title: Fleeticc Partner API
  description: >-
    Live and historical GPS for partner backends. HMAC-SHA256 auth. Base:
    https://api.fleeticc.com
  version: 1.0.0
  contact:
    email: info@fleeticc.com
    url: https://fleeticc.com/contact
servers:
  - url: https://api.fleeticc.com
    description: Production
security:
  - PartnerHmac: []
paths:
  /api/partner/v1/history:
    get:
      summary: GPS history or nearest point
      description: Trip range (from+to, max 7 days) or nearest point (at).
      operationId: partnerHistory
      parameters:
        - $ref: '#/components/parameters/XApiKey'
        - $ref: '#/components/parameters/XTimestamp'
        - $ref: '#/components/parameters/XSignature'
        - name: vehicleId
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Fleeticc vehicle id (or use imei)
        - name: imei
          in: query
          required: false
          schema:
            type: string
            example: '359633100000001'
          description: Device IMEI (or use vehicleId)
        - name: from
          in: query
          required: false
          schema:
            type: integer
            example: 1761190000
          description: Range start (Unix seconds). Required with to.
        - name: to
          in: query
          required: false
          schema:
            type: integer
            example: 1761200000
          description: Range end (Unix seconds). Required with from. Max span 7 days.
        - name: at
          in: query
          required: false
          schema:
            type: integer
          description: Unix seconds — nearest GPS point mode
        - name: windowSeconds
          in: query
          required: false
          schema:
            type: integer
            default: 300
          description: Search ± seconds around at (default 300, max 3600)
      responses:
        '200':
          description: History range or nearest point
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccess'
components:
  parameters:
    XApiKey:
      name: X-Api-Key
      in: header
      required: true
      schema:
        type: string
        example: pk_078dd6a8b290dbce3543d18f9c6cf72d
      description: Your Partner API key
    XTimestamp:
      name: X-Timestamp
      in: header
      required: true
      schema:
        type: string
        example: '1761200000'
      description: Current Unix time in seconds (±5 minutes)
    XSignature:
      name: X-Signature
      in: header
      required: true
      schema:
        type: string
      description: HMAC-SHA256 hex of METHOD\nPATH\nTIMESTAMP\nBODY_SHA256
  schemas:
    ApiSuccess:
      type: object
      properties:
        code:
          type: string
          example: '200'
        message:
          type: string
        data:
          type: object
  securitySchemes:
    PartnerHmac:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        Also send X-Timestamp (Unix seconds) and X-Signature (HMAC-SHA256 hex).
        See Authentication.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.