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

Overview

API for real time autocompletion of address information. To receive access to our product or change your access password, please contact us at support@algolytics.pl.

General information

The following table shows the general HTTP status codes that may appear in any operation:

Status code Usage

200 OK

The request completed successfully.

301 Moved Permanently

The target resource has been assigned a new permanent URI. Any future references to this resource ought to use one of the enclosed URIs.

302 Found

Redirection to a different URI.

405 Method Not Allowed

The specified method 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.

499 Client Closed Request

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

500 Internal Server Error

The server encountered an unexpected condition that prevented it from fulfilling the request.

502 Bad Gateway

The server seems to be unable to handle the requests.

504 Gateway Timeout

The server could not provide response in time.

User operations

Autocomplete: city

Method

POST

Path

api/autocomplete/city

Request is used to autocomplete city name.

HTTP status codes

Status code Usage

400 Bad Request

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

415 Unsupported Media Type

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

503 Service Unavailable

The request was well-formed but server is currently unavailable. Service will be in this state during re indexing process.

Request structure

Table 1. Request headers
Name Description

Content-Type

application/json;charset=UTF-8
Table 2. Request fields
Path Type Description

city

String

Input value for city hints.

street

Null

[Optional] - Ignored when requesting for city hints.

buildingNumber

Null

[Optional] - Ignored when requesting for city hints.

Response structure

Table 3. Response headers
Name Description

Content-Type

application/json;charset=UTF-8
Table 4. Response fields
Path Type Description

hints

Array

City hints for the given request.

hints[].actualName

String

Present city name.

hints[].lookedUpName

String

The name of the city searched by the user, which is not the present name of the city. If null, the present city name has been matched to the user’s query.

hints[].hasStreets

Boolean

Information if the city has streets.

Example

Request
$ curl 'https://autocomplete.example.host/api/autocomplete/city' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "city" : "Pelplin-Nadl",
  "street" : null,
  "buildingNumber" : null
}'
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 132

{
  "hints" : [ {
    "lookedUpName" : "Pelplin-Nadleśnictwo",
    "actualName" : "Nadleśnictwo",
    "hasStreets" : false
  } ]
}

Autocomplete: street

Method

POST

Path

api/autocomplete/street

Request is used to autocomplete name of the street within the given city.

HTTP status codes

Status code Usage

400 Bad Request

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

415 Unsupported Media Type

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

503 Service Unavailable

The request was well-formed but server is currently unavailable. Service will be in this state during re indexing process.

Request structure

Table 5. Request headers
Name Description

Content-Type

application/json;charset=UTF-8
Table 6. Request fields
Path Type Description

city

String

Full present name of the city in which to look for the street.

street

String

Input value for street hints.

buildingNumber

Null

[Optional] - Ignored when requesting for street hints.

Response structure

Table 7. Response headers
Name Description

Content-Type

application/json;charset=UTF-8
Table 8. Response fields
Path Type Description

hints

Array

Street hints for the given request.

hints[].actualName

String

Present street name.

hints[].lookedUpName

String

The name of the street searched by the user, which is not the present name of the street. If null, the present street name has been matched to the user’s query.

Example

Request
$ curl 'https://autocomplete.example.host/api/autocomplete/street' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "city" : "Brzeziny",
  "street" : "Armii Czer",
  "buildingNumber" : null
}'
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 104

{
  "hints" : [ {
    "lookedUpName" : "Armii Czerwonej",
    "actualName" : "Szarych Szeregów"
  } ]
}

Autocomplete: building

Method

POST

Path

api/autocomplete/building

Request is used to autocomplete building number within the given city and street.

HTTP status codes

Status code Usage

400 Bad Request

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

415 Unsupported Media Type

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

503 Service Unavailable

The request was well-formed but server is currently unavailable. Service will be in this state during re indexing process.

Request structure

Table 9. Request headers
Name Description

Content-Type

application/json;charset=UTF-8
Table 10. Request fields
Path Type Description

city

String

Full present name of the city in which to look for the building.

street

String

[Optional] - Full present name of the street on which to look for the building. May be null to indicate that there is no street in the given address.

buildingNumber

String

Input value for building hints.

Response structure

Table 11. Response headers
Name Description

Content-Type

application/json;charset=UTF-8
Table 12. Response fields
Path Type Description

hints

Array

Building hints for the given request.

hints[].buildingNumber

String

Building number.

hints[].postalCode

String

Postal code for the building.

Example

Request
$ curl 'https://autocomplete.example.host/api/autocomplete/building' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "city" : "Suchy Las",
  "street" : "Sucholeska",
  "buildingNumber" : "1"
}'
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 337

{
  "hints" : [ {
    "postalCode" : "62-002",
    "buildingNumber" : "1"
  }, {
    "postalCode" : "62-002",
    "buildingNumber" : "10"
  }, {
    "postalCode" : "62-002",
    "buildingNumber" : "12"
  }, {
    "postalCode" : "62-002",
    "buildingNumber" : "14"
  }, {
    "postalCode" : "62-002",
    "buildingNumber" : "16"
  } ]
}

Autocomplete: postal code

Method

POST

Path

api/autocomplete/postalcode

Request is used to get postal code for given address.

HTTP status codes

Status code Usage

400 Bad Request

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

415 Unsupported Media Type

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

503 Service Unavailable

The request was well-formed but server is currently unavailable. Service will be in this state during re indexing process.

Request structure

Table 13. Request headers
Name Description

Content-Type

application/json;charset=UTF-8
Table 14. Request fields
Path Type Description

city

String

Full present name of the city in which to look for the postal code.

street

String

[Optional] - Full present name of the street on which to look for the postal code. This value will be ignored when city doesn’t contain given street. May be null to indicate that there is no street in the given address. If building number is also null postal codes for the city will be returned.

buildingNumber

String

[Optional] - Building number. This value will be ignored when street doesn’t contain given building number. If null algorithm will search for all postal codes for given city and street.

Response structure

Table 15. Response headers
Name Description

Content-Type

application/json;charset=UTF-8
Table 16. Response fields
Path Type Description

hints

Array

Building hints for the given request.

hints[].postalCode

String

Postal code for the given address. Multiple codes can be returned if they were matched to the city or street level.

Example

Request
$ curl 'https://autocomplete.example.host/api/autocomplete/postalcode' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "city" : "Warszawa",
  "street" : "Puławska",
  "buildingNumber" : "228"
}'
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 53

{
  "hints" : [ {
    "postalCode" : "02-566"
  } ]
}

Autocomplete: check postal code

Method

GET

Path

api/autocomplete/check/{postalcode}

Request is used to check if given postal code exists. Postal code should be provided in format dd-ddd where d is digit from range 0-9. In case the postal code does exist, the HTTP status code 200 is returned (with empty response). Otherwise status code 404 is returned, along with the message "Postal code doesn’t exist".

HTTP status codes

Status code Usage

400 Bad Request

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

404 Not Found

The requested resource could not be found

503 Service Unavailable

The request was well-formed but server is currently unavailable. Service will be in this state during re indexing process.

Request structure

Table 17. /api/autocomplete/check/{postalCode}
Parameter Description

postalCode

Postal code to be checked if it exist.

Example

Request
$ curl 'https://autocomplete.example.host/api/autocomplete/check/02-822' -i -X GET
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Administrative operations

Autocomplete: indexing status

Method

GET

Path

api/autocomplete/status

Request is used to check in what state the application is located. It also provides information on when was the last successful indexing and if reindexing is ongoing.

HTTP status codes

Status code Usage

401 Unauthorized

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

403 Forbidden

User has insufficient permissions to call this method.

Request structure

Table 18. Request headers
Name Description

Authorization

Basic auth credentials

Response structure

Table 19. Response headers
Name Description

Content-Type

application/json;charset=UTF-8
Table 20. Response fields
Path Type Description

lastSuccessfulIndexing

String

Exact time of last successful indexing.

status

String

Application status. Application may be in one of following states:

- OK: Application is serving incoming requests.
- STOPPING: Application has been stopped. No new requests are being accepted, but application is finishing processing ongoing requests.
- STOPPED: Application is stopped. No requests are being accepted nor being served.
- REINDEXING_ERROR: Application is stopped. Last reindexing attempt finished with error, therefore no requests are being accepted.

reindexing

Boolean

Information if data is being re indexed at the moment. Reindexing can be performed only in following states:

- STOPPED
- REINDEXING_ERROR

Example

Request
$ curl 'https://autocomplete.example.host/api/autocomplete/status' -i -u 'admin:p4ssword' -X GET \
    -H 'Accept: application/json'
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 107

{
  "lastSuccessfulIndexing" : "2024-06-21T09:50:05.601+00:00",
  "status" : "OK",
  "reindexing" : false
}

Autocomplete: stop

Method

GET

Path

api/autocomplete/stop

Request is used to stop application. Stopped application doesn’t serve any requests. After successfully stopping application reindexing may be performed.

HTTP status codes

Status code Usage

401 Unauthorized

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

403 Forbidden

User has insufficient permissions to call this method.

503 Service Unavailable

The request was well-formed but server is currently unavailable. Service will be in this state during re indexing process.

Request structure

Table 21. Request headers
Name Description

Authorization

Basic auth credentials

Example

Request
$ curl 'https://autocomplete.example.host/api/autocomplete/stop' -i -u 'admin:p4ssword' -X GET
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Autocomplete: abort

Method

GET

Path

api/autocomplete/abort

Request is used to abort maintenance. Maintenance can be aborted only when application is stopped and you do not wish to perform reindexing.

HTTP status codes

Status code Usage

401 Unauthorized

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

403 Forbidden

User has insufficient permissions to call this method.

503 Service Unavailable

The request was well-formed but server is currently unavailable. Service will be in this state during re indexing process.

Request structure

Table 22. Request headers
Name Description

Authorization

Basic auth credentials

Example

Request
$ curl 'https://autocomplete.example.host/api/autocomplete/abort' -i -u 'admin:p4ssword' -X GET
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Autocomplete: reindex data

Method

GET

Path

api/autocomplete/reindex

Request is used initiate async indexing process. Process will reload dictionary data into memory. During that time other services will not be available.

HTTP status codes

Status code Usage

401 Unauthorized

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

403 Forbidden

User has insufficient permissions to call this method.

503 Service Unavailable

The request was well-formed but server is currently unavailable. Service will be in this state during re indexing process.

Request structure

Table 23. Request headers
Name Description

Authorization

Basic auth credentials

Example

Request
$ curl 'https://autocomplete.example.host/api/autocomplete/reindex' -i -u 'admin:p4ssword' -X GET
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY