1. Home
  2. Bliq Park API
  3. Introduction: Bliq Park API v3

Introduction: Bliq Park API v3

Welcome to the Bliq Park API!¬†ūüėä

This article introduces the key concepts and how they are represented in the Bliq Park API. For a formal technical specification, head over to the Swagger/OpenAPI definition.

The API accepts https POST requests with a JSON payload and also returns the results as JSON. We heavily embrace the GeoJSON standard to represent geographical features, such as polygons, lines and points. Beware that in the GeoJSON coordinate tuples, the longitude comes first, so it’s [LNG, LAT] instead of [LAT, LNG].

To get started with the Bliq Park API, please create a free account in Bliq Studio. There, you will obtain your personal API key and can explore the parking map and all data available to date.

Sidenote: Pricing

Good news! The FREE plan gets you covered with 10.000 API requests/month. If you are a commercial user, please refer to our pricing page.

1. On-Street / Off-Street

We strictly differentiate between On-street (curb) parking at the side of public roads and Off-street parking, which can take the form of a designated parking area off the main road, a car park or an underground parking facility. The geographical shape of On-street entities is always represented as a GeoJSON LineString, parallel to the road it belongs to. The geographical extent of Off-Street facilities on the other hand will always be represented by a GeoJSON Polygon/MultiPolygon or a single Point (e.g. for underground facilities), but never a LineString.

The API consists of two separate endpoints to access On-street and Off-street entities.

  • https://api.bliq.ai/park/v3/getOnStreetParkingOptions
  • https://api.bliq.ai/park/v3/getOffStreetParkingOptions

2. Map Layers

Every request to the API needs to specify the map layers that are desired to be included in the output. The entity ID and geographical geometry will always be returned, all other attributes fall in one of the three possible map layers: Rules, Prediction & Live.

Rules

Static parking attributes. This includes the name (streetName for on-street), capacity (number of parking spots), opening hours and price information

Prediction

Predicted availability values. These come in the form of a percentage number that indicates the likelihood of finding a free parking spot for each parking entity

Live

Real-time availability information. This comes in the form of the number of open spots that are currently available on a specific curb stretch, car park etc. For On-street parking entities, the positions of single free spots on the curb are also provided as GeoJSON points.

3. Time

When no time is provided with the API request, the current time is assumed. You can provide a specific request time, but it needs to be between two days in the past and seven days into the future. Live data is only available when requesting for the current time.

4. Request Types

To specify which parking entities should be included in the response, it is possible to request by the geographical area (NextToPointRequest, PolygonRequest, TileRequest) or by the IDs of specific entities (IDRequest). More details on the request types:

NextToPointRequest

This returns entities close to a location you specify.

PolygonRequest

This returns all entities that touch the specified GeoJSON Polygon or MultiPolygon. Beware, that the Polygon is restricted to a size of 1 km² (0.39 mi²).

TileRequest

Use the TileRequest to retrieve entities on an OpenStreetMap slippy map tile – a square that is defined by x, y, and zoom values. More information as well as code snippets to convert from other representations can be found on the OpenStreetMap Wiki. Beware that only zoom levels 15 and higher are allowed. If you want to manually explore map tiles, see this handy tool.

TileRequests are the recommended way of querying from a user device that allows exploring the data on a map. Keep in mind that all entities are returned that touch the tile, so entities that span across to adjacent tiles are returned for both of them.

IDRequest

The IDRequest allows requesting up to 30 specific entity ID and time combinations. This can be used to plot the predictions for a specific entity over the course of the day (e.g. requesting the same entity ID for every hour of the day). Another use case is to update predictions or live information for a set of cached entity IDs.

Keep in mind that it’s not possible to mix On-street and Off-street IDs, as each kind requires a request to the corresponding API endpoint.

5. Authentication

Every request to the API needs to include the x-api-key header field with your personal API key as value. You can find your API key in the Profile tab of Bliq Studio.

6. Tags / Filtering

Every entity in the response comes with a list of tags, by which they can be filtered using the excludeTags and includeTags properties with the request. See the Attributes section for a list of all possible tags. The rules for filtering are as follows:

  • Entities that include any tag from the excludedTags are removed from the results.
  • Entities that do not include all tags from the includeTags are removed from the results.

excludeTags defaults to PRIVATE, but can be overridden by providing an empty array.

7. Localization

All prices are returned in the local currency of the parking entity, not the user’s device. The string representations for opening hours and price information default to English, but can be changed to German by providing a¬†localeDefinition with the request.

8. Attributes

Name Description Example
id An integer representing a unique (among on- and off-street) identifier for this single parking entity
1690133
streetName
(on-street only)
The name of the street this on-street area is situated on, in local language
"Hermannstraße"
name
(off-street only)
The name of this off-street facility
"Tiefgarage Friedrichstadt-Passagen"
capacity The number of parking spots
8
capacityFamilyFriendly The number of parking spots for family-friendly parking (e.g. Frauenparkplatz)
2
capacityHandicapped The number of parking spots for handicapped people.
3
openingHours Information about the opening hours in a format that can be displayed to the user directly. The simpleOpeningStatus indicates the opening status for the requested time and will be translated when a localeDefinition is sent with the request.
{
   stringRepresentation:
      "Sa 8am-3pm
          open
       Mo-Fr 8am-8pm
          open",
   simpleOpeningStatus:
      "open"
}
priceInformation Information about the pricing in a format that can be displayed to the user directly. The simplePriceStatus indicates whether the entity is free or paid for the requested time and will be translated when a localeDefinition is sent with the request.
{
   stringRepresentation:
      "2‚ā¨/h
          up to 30min: 0.80‚ā¨
       30min-1h: 1.20‚ā¨
          max 15‚ā¨/d",
   simplePriceStatus:
      "paid"
}
tags An array of tags for the entity.

Every on-street entity includes the tag ON_STREET.

Every off-street entity includes either one of  CAR_PARK, SURFACE_PARKING UNDERGROUND_PARKING

Every entity includes either FREE or PAID and either OPEN or CLOSED.

["ON_STREET", "FREE", "OPEN"]
entrancePoints
(off-street only)
Entrance points for car parks and underground parking facilities, some including the height.
[
  {
    "entranceHeight": 195,
    "entrancePoint": {
      "type": "Point",
      "coordinates": [
        13.467790,
        52.514935
      ]
    },
    "heightUnit": "cm"
  },
  {
    "entrancePoint": {
      "type": "Point",
      "coordinates": [
        13.467849,
        52.514931
      ]
    }
  }
]

 

Updated on July 31, 2020

Was this article helpful?

Bitnami