v1.md

API v1

This document contains details and endpoints of API version 1.

All payloads are sent with POST request to URL in form of <API_URL>/<ENDPOINT>.

Capabilities

This endpoint, <API_URL>/capabilities, is used to query the server of its capabilities, i.e. which endpoints it supports. This is queried when program starts or if user changes settings.

Expected HTTP response code 200. Program will not send anything to the API until the capabilities has been successfully queried. Query can fail because of server did not return HTTP code 200 or the received JSON was invalid.

Configurable endpoints and example of JSON which server is expected to return:

{
    "truck": true                 // Supports Truck -endpoint (default: false)
    "fine": true                  // Supports Fine -endpoint (default: false)
}

JSON can be minified and keys with default values can be omitted if you want to use the default value.

Job

Jobs will be sent to <API_URL>/job when user takes a job or cancels or delivers it.

Expected HTTP response code 200. Otherwise, payload sending will be retried in 30 seconds intervals until API responds with HTTP code 200.

Below is an example of JSON format for a job.

Notes:

• If isSpecial is true then company object in source and destination will not exist.
• Truck can be wrong when status is Delivered or Cancelled
  • e.g. when user owns a truck but decides to do a quick job; truck is correct when OnJob but when Delivered/Cancelled the truck is reported as the truck the user owns instead of the one used in the job.

{
    "game": "ets2",               // Game type (ets2, ats)
    "status": 1,                  // See "Status" below
    "type": 1,                    // See "Types" below
    "isSpecial": false,           // Is this special transport job
    "income": 6878,               // In game specific units (ETS2: €, ATS: $)
    "revenue": 6878,              // In game specific units (ETS2: €, ATS: $)
    "xp": 120,                    // XP received
    "time": 234,                  // Time spend on the job in game minutes
    "maxSpeed": 0.0,              // Maximum  speed during the delivery (can be negative)
    "fuelConsumed": 0.0,          // Liters
    "autoPark": false,            // Was auto parking used
    "autoLoad": false,            // Was auto loading used (always true for non cargo market jobs)
    "distance": {
        "driven": 0.0,            // Kilometers
        "planned": 248            // Planned trip distance kilometers
    },
    "trailer": {
        "id": "scs_box.moving_floor.chassis_stwx2esii",
        "accessoryId": ""
    },
    "truck": {
        "id": "vehicle.scania.streamline",
        "name": "Streamline",
        "wheels": 6,
        "brand": {
            "id": "scania",
            "name": "Scania"
        }
    },
    "cargo": {
        "id": "paper",
        "name": "Office Paper",
        "mass": 18000.0,          // Kilograms
        "damage": 0.0             // Percentage (e.g. 0.01 = 1%)
    },
    "source": {
        "city": {
            "id": "tampere",
            "name": "Tampere"
        },
        "company": {
            "id": "viljo_paper",
            "name": "Viljo Paperitehdas Oy"
        }
    },
    "destination": {
        "city": {
            "id": "helsinki",
            "name": "Helsinki"
        },
        "company": {
            "id": "cont_port",
            "name": "Container Port"
        }
    }
}

Status

Description of job status:

0 = FreeAsWind
1 = OnJob
2 = Cancelled
3 = Delivered

Note: Job with a status 0 should not ever be sent to the API, if that happens it's a bug.

Types

Description of job types:

0 = Unknown
1 = CargoMarket
2 = QuickJob
3 = FreightMarket
4 = ExternalContract
5 = ExternalMarket

Note: If job has status of 0 it's most likely bug and an Issue should be opened if there is no open issue of it already.

Truck

Trucks positional data will be sent to <API_URL>/truck once in a second only if game is not paused.

Response code is ignored; payload is only sent once.

Below is an example of JSON format for a truck positional data.

{
    "speed": 0.0,                 // Meters per second
    "heading": 0.723,
    "x": 34496.559,
    "y": 11.938,
    "z": -61094.948
}

Fine

When player receives a fine it will be sent to <API_URL>/fine. Fines will be sent to the API even when player does not have an active job.

Expected response code 200.

Below is an example of JSON format for fine:

{
    "type": 1,                    // Explanation below
    "amount": 370                 // Fine offence amount in native game currency
}

Valid Types are:

0  = Unknown
1  = Crash
2  = AvoidSleeping
3  = WrongWay
4  = SpeedingCamera
5  = NoLights
6  = RedSignal
7  = Speeding
8  = AvoidWeighing
9  = IllegalTrailer
10 = AvoidInspection
11 = IllegalBorderCrossing
12 = HardShoulderViolation
13 = DamagedVehicleUsage
14 = Generic

If API receives fine with type Unknown then create an issue (if it does not exist yet) as it could indicate game has a new fine type.