Restrictions API | On-Premise | 2GIS Documentation
On-Premisebeta

Restrictions API

Restrictions API service allows you to manage information about road closures: get a list of currently active road closures, add new road closures, and remove the ones that are no longer relevant. All road closures added via Restrictions API will be taken into account when building routes using On-Premise Navigation services.

Restrictions API service publishes a RESTful API for use by a client application.

Restrictions API service integrates with On-Premise Navigation services (Navi-Castle and Navi-Back) to obtain geographic data. In addition, the service uses a cron job to periodically (once per hour) retrieve current road closure information from public 2GIS Update servers.

On-Premise Restrictions API service architecture

Shared infrastructure:

  • PostgreSQL data storage for storing road closure data. It is required to deploy PostgreSQL 12 with PL/pgSQL enabled.

Services:

  1. Create the values-restrictions.yaml configuration file:

    values-restrictions.yaml

    dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise
    
    db:
        host: <hostname or IP address of PostgreSQL>
        port: <PostgreSQL port>
        path: <database name>
        username: <user name>
        password: <password>
    
    api:
        attractor_url: <Navi-Back URL (ex. "https://example.com:80")>
    

    Where:

    1. dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside.

    2. db: access settings for the PostgreSQL server.

      1. host: hostname or IP address of the PostgreSQL server.
      2. port: listening port of the PostgreSQL server. For example, 5432.
      3. path: database name.
      4. username and password: credentials for accessing the database specified in the path setting. The user must be the owner of this database or a superuser.
    3. attractor_url: URL of Navi-Back service. This URL should be accessible from all the pods within your Kubernetes cluster.

  2. Deploy the service with Helm using the created values-restrictions.yaml configuration file:

helm upgrade --install --version=1.0.3 --atomic --wait-for-jobs --values ./values-restrictions.yaml navi-restrictions 2gis-on-premise/navi-restrictions

To update the service after changing the settings or after updating the Docker image, call helm upgrade command:

helm upgrade --version=1.0.3 --atomic --wait-for-jobs --values ./values-restrictions.yaml navi-restrictions 2gis-on-premise/navi-restrictions

To add a road closure, send a POST request to the /points endpoint.

The body of the request must contain a JSON object with the following attributes:

  • lat - latitude of the road closure.
  • lon - longitude of the road closure.
  • start_time - date and time of the start of the road closure in RFC 3339 format (for example, 2020-05-15T15:52:01Z).
  • end_time - date and time of the end of the road closure in RFC 3339 format (for example, 2020-05-15T15:52:01Z).
{
    "lat": "54.943207",
    "lon": "82.93057",
    "start_time": "2022-03-01T12:00:00Z",
    "end_time": "2022-04-01T12:00:00Z"
}

If the road closure was successfully added, the response will contain a UUID that can be used to update the road closure or delete it from the database.

To get a list of currently active road closures, send a GET request to the /restrictions endpoint.

The request will return the following information:

  • restriction_id - UUID of the road closure.
  • edge_geometry - geometry of the road closure in WKT format.
  • start_time - date and time of the start of the road closure in RFC 3339 format (for example, 2020-05-15T15:52:01Z).
  • end_time - date and time of the end of the road closure in RFC 3339 format (for example, 2020-05-15T15:52:01Z).
[
    {
        "restriction_id": "ca89008e-186b-4a97-942b-739b646b6952",
        "edge_geometry": "...",
        "start_time": "2022-03-01T12:00:00Z",
        "end_time": "2022-04-01T12:00:00Z"
    }
]

To update the time of a road closure, send a PATCH request to the /restrictions/{id} endpoint, where {id} is the UUID of the road closure.

The body of the request must contain a JSON object with the following attributes:

  • start_time - date and time of the start of the road closure in RFC 3339 format (for example, 2020-05-15T15:52:01Z).
  • end_time - date and time of the end of the road closure in RFC 3339 format (for example, 2020-05-15T15:52:01Z).
{
    "start_time": "2022-03-01T12:00:00Z",
    "end_time": "2022-04-01T12:00:00Z"
}

To delete a road closure, send a DELETE request to the /restrictions/{id} endpoint, where {id} is the UUID of the road closure.

On a successful request, the road closure will be marked as removed and no longer will be taken into account when building routes. All road closures marked this way as well as closures with an end date less than or equal to the current date will be deleted from the database on the next cleanup cycle.

To test that the service is working, send a GET request to the /healthcheck endpoint.