API Routes

For more Algolytics products visit us at https://algolytics.com/.

Overview

API for calculating the best route connecting two points. To receive access to our product create an free account.

UZYSKAJ DOSTĘP DO API ROUTES

User operations

Get route details

Method	POST
Path	api/scenario/code/remote/score?name=routes_auth&key=93d8dd88-6162-4e0a-a220-82b2d3ce6129

Method

POST

Path

api/scenario/code/remote/score?name=routes_auth&key=93d8dd88-6162-4e0a-a220-82b2d3ce6129

Calculate the best route connecting two points and return its distance. Points can be given as addresses or their geographical coordinates, however there are restrictions on combining address properties, see Restrictions on combining address properties for more details.

HTTP status codes

STATUS CODE	USAGE
200 OK	The request completed successfully.
400 Bad Request	The request was malformed. The response body will include an error providing further information.
401 Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource.
404 Not Found	Unable to geocode input address.
405 Method Not Allowed	The specified HTTP method (e.g. GET, POST) was recognized, but it is not appropriate for the requested resource.
408 Request Timeout	The server did not receive a complete request message from the client within the time that it was prepared to wait.
415 Unsupported Media Type	The request entity has a media type which the server does not support.
499 Client Closed Request	The client closed the connection while the server is processing the request.
503 Service Unavailable	The request was well-formed but geocoding service is currently unavailable due to maintenance.
5xx Unexpected Server Error	The server failed to fulfill an apparently valid request. If an unspecified error in range 500-599 occurred contact our support at support@algolytics.pl.

STATUS CODE

USAGE

200 OK

The request completed successfully.

400 Bad Request

The request was malformed. The response body will include an error providing further information.

401 Unauthorized

The request has not been applied because it lacks valid authentication credentials for the target resource.

404 Not Found

Unable to geocode input address.

405 Method Not Allowed

The specified HTTP method (e.g. GET, POST) was recognized, but it is not appropriate for the requested resource.

408 Request Timeout

The server did not receive a complete request message from the client within the time that it was prepared to wait.

415 Unsupported Media Type

The request entity has a media type which the server does not support.

499 Client Closed Request

The client closed the connection while the server is processing the request.

503 Service Unavailable

The request was well-formed but geocoding service is currently unavailable due to maintenance.

5xx Unexpected Server Error

The server failed to fulfill an apparently valid request. If an unspecified error in range 500-599 occurred contact our support at support@algolytics.pl.

Request structure

Table 1. Request headers
NAME	DESCRIPTION
Content-Type	application/json;charset=UTF-8

Table 2. Request fields
PATH	TYPE	DESCRIPTION
secret_key	String	An authorization token obtained by the registration e-mail
query	Object	Points between which the distance is to be calculated
query.start	Object	Route start point. It can be given as the address or its geographical coordinates
query.start.postalCode	String	[Optional] Postal code
query.start.cityName	String	[Optional] City name
query.start.streetName	String	[Optional] Street name
query.start.streetNumber	String	[Optional] Street number
query.start.apartmentNumber	String	[Optional] Apartment number
query.start.streetNumberAndApartmentNumber	String	[Optional] Concatenation of the street number and apartment number (alternative to separate fields: streetNumber, apartmentNumber)
query.start.streetNameAndStreetNumberAndApartmentNumber	String	[Optional] Concatenation of the street name, street number and apartment number (alternative to separate fields: streetName, streetNumber, apartmentNumber)
query.start.voivodeshipName	String	[Optional] Voivodeship name
query.start.countyName	String	[Optional] County name
query.start.communeName	String	[Optional] Commune name
query.start.generalData	String	[Optional] Concatenation of all address information available
query.start.longitude	Number	[Optional] East longitude degree value. Providing longitude it is mandatory to provide [latitude] – in this case all other fields are ignored
query.start.latitude	Number	[Optional] North latitude degree value. Providing latitude it is mandatory to provide [longitude] – in this case all other fields are ignored
query.end	Object	Route end point. It can be given as the address or its geographical coordinates
query.end.postalCode	String	[Optional] Postal code
query.end.cityName	String	[Optional] City name
query.end.streetName	String	[Optional] Street name
query.end.streetNumber	String	[Optional] Street number
query.end.apartmentNumber	String	[Optional] Apartment number
query.end.streetNumberAndApartmentNumber	String	[Optional] Concatenation of the street number and apartment number (alternative to separate fields: streetNumber, apartmentNumber)
query.end.streetNameAndStreetNumberAndApartmentNumber	String	[Optional] Concatenation of the street name, street number and apartment number (alternative to separate fields: streetName, streetNumber, apartmentNumber)
query.end.voivodeshipName	String	[Optional] Voivodeship name
query.end.countyName	String	[Optional] County name
query.end.communeName	String	[Optional] Commune name
query.end.generalData	String	[Optional] Concatenation of all address information available
query.end.longitude	Number	[Optional] East longitude degree value. Providing longitude it is mandatory to provide [latitude] – in this case all other fields are ignored
query.end.latitude	Number	[Optional] North latitude degree value. Providing latitude it is mandatory to provide [longitude] – in this case all other fields are ignored

Response structure

Table 3. Response headers
NAME	DESCRIPTION
Content-Type	application/json;charset=UTF-8

Table 4. Response fields
PATH	TYPE	DESCRIPTION
result.response.distance	Number	Total route distance, in meters
result.response.haversine	Number	Distance in a straight line, in meters
result.error	String	An error message explaining that the input data was incorrect or an unexpected application error occurred

Example

$ curl 'https://server.address/api/scenario/code/remote/score?name=routes_auth&key=93d8dd88-6162-4e0a-a220-82b2d3ce6129' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "query" : {
    "start" : {
      "postalCode" : "00-024",
      "cityName" : "Warszawa",
      "streetNameAndStreetNumberAndApartmentNumber" : "Al. Jerozolimskie 54"
    },
    "end" : {
      "latitude" : 52.25637,
      "longitude" : 20.9839567
    }
  },
  "secret_key":"****"
}'

HTTP/1.1 200 OK
Pragma: no-cache
X-XSS-Protection: 1; mode=block
Expires: 0
X-Content-Type-Options: nosniff
Content-Type: application/json;charset=UTF-8
Strict-Transport-Security: max-age=31536000
Cache-Control: no-cache, no-store, max-age=0, must-revalidate

{
    "type": "SCENARIO",
    "name": "routes_auth",
    "version": 1,
    "beginTime": "2021-03-15T10:59:06.022880Z",
    "endTime": "2021-03-15T10:59:07.815564Z",
    "result": {
        "error": null,
        "response": {
            "distance": 4207.954,
            "haversine": 3354.811373922318
        }
    },
    "userId": "dataquality",
    "sceuid": "a148fde9-cdc3-4cc4-8e12-37e0a4fda8e5"
}

Restrictions on combining address properties

It is forbidden to pass different properties, but with the same information (e.g. streetName and streetNameAndStreetNumberAndApartmentNumber both contain street name information). Therefore, the following groups of mutually exclusive properties can be distinguished:

generalData | streetNameAndStreetNumberAndApartmentNumber | streetName
generalData | streetNameAndStreetNumberAndApartmentNumber | streetNumberAndApartmentNumber | streetNumber
generalData | streetNameAndStreetNumberAndApartmentNumber | streetNumberAndApartmentNumber | apartmentNumber
generalData | postalCode
generalData | cityName
generalData | voivodeshipName
generalData | countyName
generalData | communeName

Only one property from each group can be present at a time. Violation of these restrictions results in an error.

Algolytics Routes API

Table of Contents