Transport Operator MaaS Provider (TOMP) API

TOMP is an integration API between the MaaS providers and the transport operators for booking trips and corresponding assets.

This document describes version 1.2 of the felyx TOMP API.

More detailed information can be found at TOMP-WG page.

• API Specification
• Wiki

Summary

The felyx TOMP API is the primary way for MaaS providers to interact with felyx programmatically.

Read methods

All read methods are HTTP GET requests. Some require authentication. Responses are given in JSON format.

Write methods

All write methods are either POST or PUT requests and require authentication.

Core concepts

The felyx TOMP API is a resource-based (RESTful) HTTP interface that supports retrieving, creating, updating and deleting the resources that make up the TOMP API.

A resource is an individual data entity that is identified by its URL. As an example, it can contain information about a booking, or a pricing type, or the geographical location of a scooter. You indicate the action you want to complete on a resource via standard HTTP verbs (POST, GET, PUT, ..).

API endpoints

The felyx TOMP API is accessed from, tomp.felyx.com.

All API endpoints are relative to the base URL and must contain the version and the global region identifiers, e.g. tomp.felyx.com/v1/eu.

https://tomp.felyx.com/v1/eu/operator/operating-hours?regionId=42
\________________________/\_/\_______________________/\__________/
   server URL            region       endpoint path         query
                      namespace                        parameters

Authentication

Authentication is required if the requested resource is private, or if the request modifies data on felyx. Authenticated requests also have increased rate limits.

We ask developers to officially register their applications with us and have an API key associated with them. This would allow the felyx team to better respond to your inquiries and information requests.

Please contact [email protected] to request your unique API key and for more information.

API key usage

Your API key uniquely identifies you and gives your application access to all of the TOMP API resources.

To use it, simply pass it as a URL query parameter when making requests.

https://tomp.felyx.com/eu/operator/regions?key=YOUR_API_KEY

You can also include it in the request header as the X-API-Key header.

curl \
  -H "X-Api-Key: YOUR_API_KEY" \
  https://tomp.felyx.com/eu/booking/ID

Errors

The felyx TOMP API responds with the appropriate HTTP status codes and the error information in the response body.

Errors responses have two properties:

• errcode is an integer value for identify the error type.

• detail a human readable string describing the error.

Rate limits

Some requests to the felyx TOMP API are rate limited. The maximum number of allowed requests is based on a time interval.

Review the returned HTTP headers in order to find out your current quota.

• x-ratelimit-limit is the maximum number of allowed requests in the current time frame.

• x-ratelimit-remaining is the number of remaining requests in the current time frame.

Requests and data formats

All methods are either HTTP GET, POST or PUT requests.

Request bodies can only contain application/json data.

Response types

API responses are available in JSON format. Dates are in RFC 3339 format in UTC.

Operator Information

Operator Information provides information about the regions that felyx operates at, operating hours, pricing and vehicle availability.

Get available assets

GET /operator/available-assets

Retrieve scooters.

Parameters

Response

200 OK

Returns a list of asset types.

[
  {
    "id": "NIU-25km-2b",
    "assets": [
      {
        "id": "tomp_b49df22e-1642-4259-ab95-abd54ed9b26c",
        "overriddenProperties": {
          "location": {
            "name": "The Hague",
            "coordinates": {
              "lng": 3.99858192,
              "lat": 52.28753867
            },
            "physicalAddress": {
              "country": "NL"
            },
            "extraInfo": {
              "locationId": "6edcc227-172a-126b-998d-4308d0eb9ccf"
            }
          },
          "stateOfCharge": 27,
          "meta": {
            "licensePlate": "FLX42",
            "range": "0"
          }
        }
      },
      ...
    ],
    ...
  }
]

Get information

GET /operator/information

Retrieve information about the system.

Parameters

None

Response

200 OK

Returns a system information object.

{
  "language": ["nl-NL", "en-GB", "fr-FR", "de-DE"],
  "email": "[email protected]",
  "name": "felyx",
  "operator": "felyx",
  "phoneNumber": "+31 85 2080 470",
  "url": "https://felyx.com",
  "systemID": "FELYX0001",
  "timezone": "Europe/Amsterdam",
  "productType": "SHARING",
  "typeOfSystem": "FREE_FLOATING",
  "assetClasses": ["MOPED"]
}

Get meta information

GET /operator/meta

Retrieve information about the felyx TOMP implementation.

Parameters

None

Response

200 OK

Returns an endpoint implementation object.

[
  {
    "version": "1.1.0",
    "baseUrl": "https://felyx.com",
    "endpoints": [
      {
        "method": "GET",
        "path": "/operator/information",
        "status": "IMPLEMENTED"
      },
      {
        "method": "GET",
        "path": "/bookings/{id}",
        "status": "NOT_IMPLEMENTED"
      },
      ...
    ],
    "scenarios": [
      "NORMAL"
    ],
    "processIdentifiers": {
      "operatorInformation": [
        "DEFAULT"
      ],
      "planning": [
        "ASSET_BASED",
        "EXACT_ID"
      ],
      "booking": [
        "ACCESS_CODE_DEEPLINK",
        "ACCESS_CODE_BY_TO"
      ],
      "tripExecution": [
        "LOCK_UNLOCK_APP",
        "LOCK_UNLOCK_OWN_SDK"
      ],
      "support": null,
      "payment": [
        "CORRECTION_BY_EXTRA_COSTS"
      ],
      "general": null
    }
  }
]

Get operating calendar

GET /operator/operating-calendar

Retrieve the operating calendar.

Parameters

Response

200 OK

Returns a list of system calendar objects.

[
  {
    "regionId": "5298ba96-8707-4f0a-accd-8835b1f0b6a2",
    "startMonth": 2,
    "startDay": 14,
    "startYear": 2021,
    "endMonth": 6,
    "endDay": 30,
    "endYear": 2021
  },
  ...
]

Get operating hours

GET /operator/operating-hours

Retrieve the hours of operation.

Parameters

Response

200 OK

Returns a list of system hours objects.

[
  {
    "userType": "MEMBER",
    "regionId": "3b5ee3fd-ec5b-4633-88df-40124fdf9ac2",
    "startTime": "00:00",
    "endTime": "00:00",
    "days": [
      "MON",
      "WED",
      "THU",
      "FRI",
      "SAT"
    ]
  },
  ...
]

Get pricing plans

GET /operator/pricing-plans

Retrieve pricing information.

Parameters

Response

200 OK

Returns a list of system pricing plans.

[
  {
    "planId": "489a43e3-4cbb-4d51-b6c1-2b8638196241",
    "url": "https://felyx.com",
    "name": "felyx",
    "regionId": "b4779ec2-c4e8-44a1-8498-8073a2b07813",
    "fare": {
      "estimated": true,
      "description": "Full fare",
      "parts": [
        {
          "amount": 33.98344,
          "amountExVat": 28.261978,
          "currencyCode": "eur",
          "vatRate": 32.204132,
          "vatCountryCode": "nl",
          "type": "FIXED"
        },
        ...
      ]
    },
    "isTaxable": true,
    "description": "Your awesome ride"
  },
  ...
]

Get regions

GET /operator/regions

Retrieve information about the regions felyx operates at.

Parameters

Response

200 OK

Returns a list of system regions.

[
  {
    "regionId": "cfdde442-7412-43e6-48df-c75061ba0e84",
    "name": "Delft",
    "serviceArea": [
      [
        [
          4.35966,
          51.96154
        ],
        [
          4.30001,
          51.97155
        ],
        ...
      ]
    ]
  },
  ...
]