Corporate Mobility API

API backend for visualising corporate mobility data

More information: https://helloreverb.com

Contact Info: dev@triply.at

Version: 0.0.1

BasePath:/triply/corporate-mobility-planner/0.0.1

http://apache.org/licenses/LICENSE-2.0.html

Access

Methods

[ Jump to Models ]

Default

get /companies/{companyId}/catchment
get /companies/{companyId}/employees
post /companies/{companyId}/employees
get /companies/{companyId}/mobilityScore
get /companies/{companyId}/mobilityStats
put /companies/{companyId}/mobilityStats
get /companies/{companyId}/packages
get /companies
post /companies

Default

get /companies/{companyId}/catchment

calculate catchment area for mode (companiesCompanyIdCatchmentGet)

In V1 the catchment area for a specific mode is calculated whenever this REST service is called. One request can only calculate the catchment area for one transport mode and a given set of time steps. The response is a geojson <a href="https://tools.ietf.org/html/rfc7946#section-3.3">FeatureCollection</a> that consists of one <a href="https://tools.ietf.org/html/rfc7946#section-3.1.6">Polygon</a> or <a href="https://tools.ietf.org/html/rfc7946#section-3.1.7">MultiPolygon</a> per time step. The properties object of each polygon should contain a <code>time</code> field with the travel time of that catchment area. An example response can be found <a href="http://data.triply.ai/data/example_iso.json">here</a>. In future versions, calculating catchment areas for multiple catchment areas could be supported by changing the <code>mode</code> parameter into an array.

Path parameters

companyId (required)

Path Parameter —

Query parameters

mode (required)

Query Parameter — mode of transport for calculating the catchment area

times (required)

Query Parameter — travel time steps for calculating catchment area in minutes format: int32

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

Example data

Content-Type: exampleIsochrone

get /companies/{companyId}/employees

get employee addresses (companiesCompanyIdEmployeesGet)

List all saved employee address data for the company. A successful response also contains the geocoded centroid of each district identified by the zipcode uploaded.

Path parameters

companyId (required)

Path Parameter —

Return type

array[EmployeeInfo]

Example data

Content-Type: application/json

[ {
  "zipcode" : "A-4020",
  "count" : 34,
  "latitude" : 48.2890788,
  "longitude" : 14.2532453
}, {
  "zipcode" : "A-4030",
  "count" : 27,
  "latitude" : 48.2485449,
  "longitude" : 14.3007944
}, {
  "zipcode" : "A-4040",
  "count" : 89,
  "latitude" : 48.344745,
  "longitude" : 14.2548773
} ]

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

post /companies/{companyId}/employees

upload employee address data (companiesCompanyIdEmployeesPost)

The address data that comes from the company-internal HR department. This data is usually exported as a CSV or excel file. For the sake of simplicity, V1 of the API will only work with CSV file in the form of <code>zipcode,count</code> in each line. In later versions, it will be possible to furhter narrow down employee locations by providing street and city names alongside the zipcode. The CSV file is then parsed on the server and geocoded to the centroid of the zip code for easier display on the client later.

Path parameters

companyId (required)

Path Parameter —

Consumes

This API call consumes the following media types via the request header:

application/json
text/csv

Request body

body EmployeeInfo (optional)

Body Parameter —

Responses

201

Added employee data to service

get /companies/{companyId}/mobilityScore

calculate mobilityScore for current situation at company (companiesCompanyIdMobilityScoreGet)

Path parameters

companyId (required)

Path Parameter —

Return type

MobilityScore

Example data

Content-Type: application/json

{
  "mobilityScore" : 72.3,
  "stats" : {
    "car" : 0.5,
    "transit" : 0.25,
    "carUtilization" : 1.4,
    "walk" : 0.1,
    "bike" : 0.15
  },
  "totalDistance" : 92342.2,
  "totalEmissions" : 927394.25
}

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

OK MobilityScore

get /companies/{companyId}/mobilityStats

get mobility statistics about company (companiesCompanyIdMobilityStatsGet)

Mobility statistics (modal split + car utilization) should be set to sensible defaults whenever a new company is created. This defaults can either be set through a per-country pre-defined dataset or on a more granular level in the future

Path parameters

companyId (required)

Path Parameter —

Return type

MobilityStats

Example data

Content-Type: application/json

{
  "car" : 0.5,
  "transit" : 0.25,
  "carUtilization" : 1.4,
  "walk" : 0.1,
  "bike" : 0.15
}

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

OK MobilityStats

put /companies/{companyId}/mobilityStats

update company mobility statistics (companiesCompanyIdMobilityStatsPut)

Allows manually overwriting the default modal spliat and car utilisation for a given company when more detailed data already exists (e.g. from a previously done employee survey).

Path parameters

companyId (required)

Path Parameter —

Consumes

This API call consumes the following media types via the request header:

application/json

Request body

body MobilityStats (optional)

Body Parameter —

Responses

201

Created

get /companies/{companyId}/packages

See improvements for mobility packages (companiesCompanyIdPackagesGet)

Calculate the improvements to the by a (or a combination of) mobility package mobility score and mobility stats. TODO: how should we visualize these improvements?

Path parameters

companyId (required)

Path Parameter —

Query parameters

active (optional)

Query Parameter —

Return type

array[inline_response_200]

Example data

Content-Type: application/json

[ {
  "score" : {
    "mobilityScore" : 72.3,
    "stats" : {
      "car" : 0.5,
      "transit" : 0.25,
      "carUtilization" : 1.4,
      "walk" : 0.1,
      "bike" : 0.15
    },
    "totalDistance" : 92342.2,
    "totalEmissions" : 927394.25
  },
  "package" : "walk"
}, {
  "score" : {
    "mobilityScore" : 72.3,
    "stats" : {
      "car" : 0.5,
      "transit" : 0.25,
      "carUtilization" : 1.4,
      "walk" : 0.1,
      "bike" : 0.15
    },
    "totalDistance" : 92342.2,
    "totalEmissions" : 927394.25
  },
  "package" : "walk"
} ]

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

get /companies

list all Companies (companiesGet)

Return type

array[Company]

Example data

Content-Type: application/json

[ {
  "shiftWork" : true,
  "name" : "voestalpine AG",
  "industry" : [ "Steel-based technology", "Capital goods" ],
  "location" : {
    "zipcode" : "A-4020",
    "country" : "Austria",
    "city" : "Linz",
    "street" : "Industriezeile 28",
    "latitude" : 48.313394,
    "description" : "voestalpine Linz",
    "longitude" : 14.311394
  },
  "employeeCount" : 2500,
  "perceivedTransportQuality" : 6
}, {
  "shiftWork" : true,
  "name" : "voestalpine AG",
  "industry" : [ "Steel-based technology", "Capital goods" ],
  "location" : {
    "zipcode" : "A-4020",
    "country" : "Austria",
    "city" : "Linz",
    "street" : "Industriezeile 28",
    "latitude" : 48.313394,
    "description" : "voestalpine Linz",
    "longitude" : 14.311394
  },
  "employeeCount" : 2500,
  "perceivedTransportQuality" : 6
} ]