openapi: 3.0.1
info:
title: AKINavAPI
version: 1.0.1
termsOfService: https://nav.aki-innovations.net/tnc
description: |
Internal Use Only
contact:
name: AKI innovations IT
url: https://aki-innovations.net
email: support@aki-innovations.net
servers:
- url: https://api.nav.vm.local/
description: "Local Development Environment"
- url: https://api.nav.aki-innovations.net/
description: "Online Staging Environment"
- url: https://api.akinav.net/
description: "Production Environment"
paths:
/location/tileByLocation/:
post:
summary: A request for drawable data in a tiled manner
tags:
- Location
description: |
Returns svg data for a specific region of the map, referred to as a "tile".
The svg data is pre-compiled, therefore, a fix grid is used to tile the map
itself. Each zoom level has its own set of tiles.
The length of a tile's side s determined by the zoom level. On level 0, each
tile has a side length of 1/100th of a degree (latitude/longitude) which calculates
to 1,111.2 m.
Additional tiles may be requested to reduce the number of subsequent calls by using the `power`
property.
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
sid:
type: string
format: uuid
pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
description: |
The session id retrieved from the initial call to `/session/start`
key:
type: string
format: byte
pattern: ^(?:[a-zA-Z0-9\+\/]{4})*(?:[a-zA-Z0-9\+\/]{4}|[a-zA-Z0-9\+\/]{3}=|[a-zA-Z0-9\+\/]{2}==)$
description: |
The session key retrieved from the initial call to `/session/start`
zoom:
type: integer
description: |
The zoom level for the specified region. It is constrained between 0 and 15
location:
type: object
description: |
The desired location to load the tile for. The result will be the tile containing that particular
location.
properties:
lon:
type: number
format: double
description: |
The longitude of the reference point in 1/100th of
a degree
lat:
type: number
format: double
description: |
The latitude of the reference point in 1/100th of
a degree
additionalProperties: false
required:
- lat
- lon
power:
type: number
minimum: 0
maximum: 3
description: |
The number of additional tiles in each direction. The number of tiles is calculated as
(2*`power`+1)2
required:
- sid
- key
- zoom
- location
- power
responses:
'200':
description: |
A set of tiles containg the requested tile
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: false
required:
- tile
- bounds
- areas
- streets
- staticSymbols
- dynamicSymbols
- staticTexts
- dynamicTexts
- nodes
properties:
tile:
type: object
description: |
General information about the tile
additionalProperties: false
required:
- zoom
- ilat
- ilon
- name
properties:
zoom:
type: number
description: |
The zoom level of the tile
ilat:
type: integer
description: |
The latitude tile index
ilon:
type: integer
description: |
The longitude tile index
name:
type: string
description: |
The name of the tile (built from zoom/ilat/ilon)
bounds:
type: object
description: |
The bounding box of the tile in user space units
additionalProperties: false
required:
- x
- y
- w
- h
properties:
x:
type: number
description: |
The virtual left boundary of the viewport
y:
type: number
description: |
The virtual upper boundary of the viewport
w:
type: number
description: |
The virtual width of the viewport
h:
type: number
description: |
The virtual height of the viewport
areas:
description: |
Areas to be drawn on the map
type: array
items:
type: object
description:
A single area combined from several shapes
additionalProperties: false
required:
- id
- cn
- cw
- ccw
properties:
id:
type: integer
description: |
The unique id identifying the area
cn:
type: string
description: |
The class name for the shape. Used for styling purposes
cw:
type: array
description: |
Paths to be drawn in clockwise fashion. This means, the path is additive to the overall shape
items:
type: object
description: |
A closed path to be added to the final area
additionalProperties: false
required:
- pts
properties:
id:
type: integer
description: |
The unique identifier for the path
pts:
type: array
description: |
A list of points making up the path
items:
type: object
description: |
A point in user-space coordinates
additionalProperties: false
required:
- x
- y
properties:
x:
type: number
description: |
The x-coordinate of the point
y:
type: number
description: |
The y-coordinate of the point
ccw:
type: array
description: |
Paths to be drawn in counter-clockwise fashion. Produces a "hole" in the overall shape.
items:
type: object
description: |
A closed path to be added to the final area
additionalProperties: false
required:
- pts
properties:
id:
type: integer
description: |
The unique identifier for the path
pts:
type: array
description: |
A list of points making up the path
items:
type: object
description: |
A point in user-space coordinates
additionalProperties: false
required:
- x
- y
properties:
x:
type: number
description: |
The x-coordinate of the point
y:
type: number
description: |
The y-coordinate of the point
streets:
type: array
description: |
Streets to be drawn on the map.
items:
type: object
description: |
A street containing three paths representing the street sides and the center line.
additionalProperties: false
required:
- id
- closed
- cn
- lines
properties:
id:
type: integer
description: |
The unique identifier for the street
ref:
type: integer
nullable: true
description: |
A relation identifier in case the street was identified by a relation
closed:
type: boolean
description: |
A closed street such as a roundabout or a street ending in itself
label:
type: string
description: |
The street's name, if available. In this case, the name can be drawn on the center
of the street's center line
cn:
type: string
description: |
The class name for the street. Used for styling purposes
lines:
type: object
description: |
The lines describing the street way
additionalProperties: false
required:
- center
properties:
center:
type: array
description: |
A number of points making up the way
items:
type: object
description: |
A point in user-space coordinates
additionalProperties: false
required:
- x
- y
properties:
x:
type: number
description: |
The x-coordinate of the point
y:
type: number
description: |
The y-coordinate of the point
staticSymbols:
type: array
description: |
Symbols to be drawn on the map on the background layer (rotating with the map)
items:
type: object
additionalProperties: false
required:
- id
- cn
- x
- y
properties:
id:
type: integer
description: |
The unique identifier for the symbol
cn:
type: string
description: |
The class name for the symbol, determines its representation
x:
type: number
description: |
The x-coordinate for the symbol
y:
type: number
description: |
The y-coordinate for the symbol
dynamicSymbols:
type: array
description: |
Symbols to be drawn on the map on the foreground layer (not rotating)
items:
type: object
additionalProperties: false
required:
- id
- cn
- x
- y
properties:
id:
type: integer
description: |
The unique identifier for the symbol
cn:
type: string
description: |
The class name for the symbol, determines its representation
x:
type: number
description: |
The x-coordinate for the symbol
y:
type: number
description: |
The y-coordinate for the symbol
staticTexts:
type: array
description: |
Texts to be displayed on the map (except street names and area names, which are drawn implicitly, rotating with the map)
items:
type: object
additionalProperties: false
required:
- id
- cn
- x
- y
- text
properties:
id:
type: integer
description: |
The unique identifier for the text
cn:
type: string
description: |
The class name for the static text
x:
type: number
description: |
The x-coordinate for the text
y:
type: number
description: |
The y-coordinate for the text
text:
type: string
description: |
The text to be displayed
dynamicTexts:
type: array
description: |
Texts to be displayed on the map (except street names and area names, which are drawn implicitly, not rotating with the map)
items:
type: object
additionalProperties: false
required:
- id
- cn
- x
- y
- text
properties:
id:
type: integer
description: |
The unique identifier for the text
cn:
type: string
description: |
The class name for the dynamic text
x:
type: number
description: |
The x-coordinate for the text
y:
type: number
description: |
The y-coordinate for the text
text:
type: string
description: |
The text to be displayed
nodes:
type: array
description: |
Invisible node definitions for various functions
items:
type: object
additionalProperties: false
required:
- id
- cn
- x
- y
properties:
id:
type: integer
description: |
The unique id for the node
cn:
type: array
description: |
Set of classnames applicable to the node. Determine the purposes the node serves
items:
type: string
x:
type: number
description: |
The x-coordinate for the node
y:
type: number
description: |
The y-coordinate for the node
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
/location/tileByID/:
post:
summary: A request for drawable data in a tiled manner
tags:
- Location
description: |
Returns native vector data for a specific region of the map, referred to as a "tile".
The data is generated or pre-compiled, therefore, a fix grid is used to tile the map
itself. Each zoom level has its own set of tiles.
The length of a tile's side s determined by the zoom level. On level 0, each
tile has a side length of 1/100th of a degree (latitude/longitude) which calculates
to 1,111.2 m.
Additional tiles may be requested to reduce the number of subsequent calls by using the `power`
property.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
sid:
type: string
format: uuid
pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
description: |
The session id retrieved from the initial call to `/session/start`
key:
type: string
format: byte
pattern: ^(?:[a-zA-Z0-9\+\/]{4})*(?:[a-zA-Z0-9\+\/]{4}|[a-zA-Z0-9\+\/]{3}=|[a-zA-Z0-9\+\/]{2}==)$
description: |
The session key retrieved from the initial call to `/session/start`
tile:
type: string
pattern: ^0[0-9a-fA-F]\_(?:[0-9a-fA-F]{4})\_(?:[0-9a-fA-F]{4})$
description: |
The tile ID for the requested tile. Tile IDs can be calculated using the openstreetmap slippy map tilenames.
The zoom level is part of the tile name.
power:
type: number
minimum: 0
maximum: 3
description: |
The number of additional tiles in each direction. The number of tiles is calculated as
(2*`power`+1)2
required:
- sid
- key
- tile
- power
additionalProperties: false
responses:
'200':
description: |
A set of tiles containg the requested tile
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: false
required:
- tile
- bounds
- areas
- streets
- staticSymbols
- dynamicSymbols
- staticTexts
- dynamicTexts
- nodes
properties:
tile:
type: object
description: |
General information about the tile
additionalProperties: false
required:
- zoom
- ilat
- ilon
- name
properties:
zoom:
type: number
description: |
The zoom level of the tile
ilat:
type: integer
description: |
The latitude tile index
ilon:
type: integer
description: |
The longitude tile index
name:
type: string
description: |
The name of the tile (built from zoom/ilat/ilon)
bounds:
type: object
description: |
The bounding box of the tile in user space units
additionalProperties: false
required:
- x
- y
- w
- h
properties:
x:
type: number
description: |
The virtual left boundary of the viewport
y:
type: number
description: |
The virtual upper boundary of the viewport
w:
type: number
description: |
The virtual width of the viewport
h:
type: number
description: |
The virtual height of the viewport
areas:
description: |
Areas to be drawn on the map
type: array
items:
type: object
description:
A single area combined from several shapes
additionalProperties: false
required:
- id
- cn
- cw
- ccw
properties:
id:
type: integer
description: |
The unique id identifying the area
cn:
type: string
description: |
The class name for the shape. Used for styling purposes
cw:
type: array
description: |
Paths to be drawn in clockwise fashion. This means, the path is additive to the overall shape
items:
type: object
description: |
A closed path to be added to the final area
additionalProperties: false
required:
- pts
properties:
id:
type: integer
description: |
The unique identifier for the path
pts:
type: array
description: |
A list of points making up the path
items:
type: object
description: |
A point in user-space coordinates
additionalProperties: false
required:
- x
- y
properties:
x:
type: number
description: |
The x-coordinate of the point
y:
type: number
description: |
The y-coordinate of the point
ccw:
type: array
description: |
Paths to be drawn in counter-clockwise fashion. Produces a "hole" in the overall shape.
items:
type: object
description: |
A closed path to be added to the final area
additionalProperties: false
required:
- pts
properties:
id:
type: integer
description: |
The unique identifier for the path
pts:
type: array
description: |
A list of points making up the path
items:
type: object
description: |
A point in user-space coordinates
additionalProperties: false
required:
- x
- y
properties:
x:
type: number
description: |
The x-coordinate of the point
y:
type: number
description: |
The y-coordinate of the point
streets:
type: array
description: |
Streets to be drawn on the map.
items:
type: object
description: |
A street containing three paths representing the street sides and the center line.
additionalProperties: false
required:
- id
- closed
- cn
- lines
properties:
id:
type: integer
description: |
The unique identifier for the street
ref:
type: integer
nullable: true
description: |
A relation identifier in case the street was identified by a relation
closed:
type: boolean
description: |
A closed street such as a roundabout or a street ending in itself
label:
type: string
description: |
The street's name, if available. In this case, the name can be drawn on the center
of the street's center line
cn:
type: string
description: |
The class name for the street. Used for styling purposes
lines:
type: object
description: |
The lines describing the street way
additionalProperties: false
required:
- center
properties:
center:
type: array
description: |
A number of points making up the way
items:
type: object
description: |
A point in user-space coordinates
additionalProperties: false
required:
- x
- y
properties:
x:
type: number
description: |
The x-coordinate of the point
y:
type: number
description: |
The y-coordinate of the point
staticSymbols:
type: array
description: |
Symbols to be drawn on the map on the background layer (rotating with the map)
items:
type: object
additionalProperties: false
required:
- id
- cn
- x
- y
properties:
id:
type: integer
description: |
The unique identifier for the symbol
cn:
type: string
description: |
The class name for the symbol, determines its representation
x:
type: number
description: |
The x-coordinate for the symbol
y:
type: number
description: |
The y-coordinate for the symbol
dynamicSymbols:
type: array
description: |
Symbols to be drawn on the map on the foreground layer (not rotating)
items:
type: object
additionalProperties: false
required:
- id
- cn
- x
- y
properties:
id:
type: integer
description: |
The unique identifier for the symbol
cn:
type: string
description: |
The class name for the symbol, determines its representation
x:
type: number
description: |
The x-coordinate for the symbol
y:
type: number
description: |
The y-coordinate for the symbol
staticTexts:
type: array
description: |
Texts to be displayed on the map (except street names and area names, which are drawn implicitly, rotating with the map)
items:
type: object
additionalProperties: false
required:
- id
- cn
- x
- y
- text
properties:
id:
type: integer
description: |
The unique identifier for the text
cn:
type: string
description: |
The class name for the static text
x:
type: number
description: |
The x-coordinate for the text
y:
type: number
description: |
The y-coordinate for the text
text:
type: string
description: |
The text to be displayed
dynamicTexts:
type: array
description: |
Texts to be displayed on the map (except street names and area names, which are drawn implicitly, not rotating with the map)
items:
type: object
additionalProperties: false
required:
- id
- cn
- x
- y
- text
properties:
id:
type: integer
description: |
The unique identifier for the text
cn:
type: string
description: |
The class name for the dynamic text
x:
type: number
description: |
The x-coordinate for the text
y:
type: number
description: |
The y-coordinate for the text
text:
type: string
description: |
The text to be displayed
nodes:
type: array
description: |
Invisible node definitions for various functions
items:
type: object
additionalProperties: false
required:
- id
- cn
- x
- y
properties:
id:
type: integer
description: |
The unique id for the node
cn:
type: array
description: |
Set of classnames applicable to the node. Determine the purposes the node serves
items:
type: string
x:
type: number
description: |
The x-coordinate for the node
y:
type: number
description: |
The y-coordinate for the node
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
/login/apple/implicit/:
post:
summary: Sign In with Apple ID
tags:
- Accounts
description: |
Implicit OIDC flow:
Takes a signed JWT identity token and verifies it.
- If the account is an existing one, the user is logged in and the session
is tied to the current user.
- If the account does not exist, it is being created on the fly and the user
is again logged in like before.
The call will accept firstname, lastname and middlename parameters as well as
an email parameter. Those values are optional an _MAY_ be provided to be stored
in the user's account. However, this data is just visible to the user himself to
identify him as being the right owner of the account (if he wants to verify it).
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
sid:
type: string
format: uuid
pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
description: |
The session id returned by `/session/start`
key:
type: string
format: byte
pattern: ^(?:[a-zA-Z0-9\+\/]{4})*(?:[a-zA-Z0-9\+\/]{4}|[a-zA-Z0-9\+\/]{3}=|[a-zA-Z0-9\+\/]{2}==)$
description: |
The session key retrieved from the initial call to `/session/start`
jwt:
type: string
format: byte
pattern: ^(?:[a-zA-Z0-9\+\/]{4})*(?:[a-zA-Z0-9\+\/]{4}|[a-zA-Z0-9\+\/]{3}=|[a-zA-Z0-9\+\/]{2}==)$
description: |
The identity token
email:
type: string
description: |
The user's email address
firstName:
type: string
description: |
The user's given name
lastName:
type: string
description: |
The user's family name
middleNames:
type: string
description: |
The user's additional given names
additionalProperties: false
required:
- sid
- jwt
responses:
'200':
description: |
The login succeeded
content:
application/json:
schema:
type: object
properties:
uid:
type: string
format: uuid
description: |
The user id as generated in our systems
aid:
type: string
description: |
The user's friendly unique id. Will be displayed to the user
newUser:
type: boolean
description: |
True, if the user has been seen for the first time
and therefore a new account has just been created
email:
type: string
description: |
The user's email address
firstName:
type: string
description: |
The user's given name
lastName:
type: string
description: |
The user's family name
middleNames:
type: string
description: |
The user's additional given names
additionalProperties: false
required:
- uid
- newUser
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
/session/start/:
post:
summary: Start a new session
tags:
- Session
description: |
Starts a new session. Unless stored session information is available, this
is the first call that should be made against the API because nearly all other
calls require a session id (for an alive session).
If there is stored session information available when starting up, first
call `/session/heartbeat` to revive that session (which might fail, so you
might end up calling `/session/start` eventually anyway).
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
clientType:
type: string
pattern: ^(ios|android|web)$
description: |
The client type for the app making the request
did:
type: string
format: uuid
pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
description: |
The unique device id generated on app installation
dname:
type: string
description: |
The device's name for easier identification in the user's device list
additionalProperties: false
required:
- clientType
- did
- dname
responses:
'200':
description: |
A new session was started
content:
application/Json:
schema:
type: object
properties:
sid:
type: string
format: uuid
description: |
The id of the newly started session
key:
type: string
format: byte
description: |
A private sequence of random bytes used to authenticate the session. This prevents session-
hijacking by guessing valid session ids as their UUID generation might not be as unpredictable
as desired
additionalProperties: false
required:
- sid
- key
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
/session/heartbeat/:
post:
summary: Tries to keep a running session alive
tags:
- Session
description: |
Tries to keep a session alive to prevent it from timing out due to inactivity.
The server may decide to terminate the session anyway in certain situations.
In this case, the request fails with a custom error code
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
sid:
type: string
format: uuid
pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
description: |
The session id retrieved from the initial call to `/session/start`
key:
type: string
format: byte
pattern: ^(?:[a-zA-Z0-9\+\/]{4})*(?:[a-zA-Z0-9\+\/]{4}|[a-zA-Z0-9\+\/]{3}=|[a-zA-Z0-9\+\/]{2}==)$
description: |
The session key retrieved from the initial call to `/session/start`
additionalProperties: false
required:
- sid
- key
responses:
'200':
description: |
The session was refreshed successfully
content:
application/Json:
schema:
type: object
properties:
sid:
type: string
format: uuid
description: |
The id of the session returned
additionalProperties: false
required:
- sid
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
/session/resume/:
post:
summary: Tries to resume a suspended session
tags:
- Session
description: |
Tries to revive a suspended session. A session gets suspended after 30 minutes of inactivity. To prevent a session from getting suspended,
one can call `/session/heartbeat`. A suspended session gets terminated after 7 days of continuous suspension. After that, a new session has
to be requested.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
sid:
type: string
format: uuid
pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
description: |
The session id retrieved from the initial call to `/session/start`
key:
type: string
format: byte
pattern: ^(?:[a-zA-Z0-9\+\/]{4})*(?:[a-zA-Z0-9\+\/]{4}|[a-zA-Z0-9\+\/]{3}=|[a-zA-Z0-9\+\/]{2}==)$
description: |
The session key retrieved from the initial call to `/session/start`
did:
type: string
format: uuid
pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
description: |
The device id from which the session was started. A session can only be resumed from the same device
additionalProperties: false
required:
- sid
- key
- did
responses:
'200':
description: |
The session was refreshed successfully
content:
application/Json:
schema:
type: object
properties:
sid:
type: string
format: uuid
description: |
The id of the session returned
additionalProperties: false
required:
- sid
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
components:
responses:
Error401:
description: |
You are not allowed to perform this action.
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- message
Error403:
description: |
The provided information was not suitable for the call.
content:
application/json:
schema:
type: object
properties:
severity:
type: string
description: |
Contains a single character indicating the severity level of the error:
- `W` is a warning. The action is not required as the current state is already sufficient
- `E` is an error. The action can not succeed given the information provided
- `P` is a problem. The action can not succeed right now because preconditions are not fulfilled (e.g. wrong sequence of API calls) or the state of the session is not suitable for the call
- `C` is a critical error. The action can not proceed due to illegal actions. These usually result in session termination
error:
type: object
properties:
message:
type: string
description: |
A description of what went wrong.
code:
type: integer
description: |
A unique error code further referencing the nature of the error.
This can be used to handle different errors in different ways.
The possible error codes returned are subject to the respective action called.
required:
- message
- code
required:
- error
Error400:
description: |
The content body did not contain valid JSON or did not match the request format.
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- message