Login

API Autocomplete

Algolytics Technologies Sp. z o.o.
version 1.0.0-SNAPSHOT

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.

User operations

Autocomplete: city

Method

POST

Path

api/autocomplete/city

Request is used to autocomplete city name.

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.

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.

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

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;charset=UTF-8' \
    -H 'Accept: application/json;charset=UTF-8' \
    -d '{
  "city" : "Pelplin-Nadl",
  "street" : null,
  "buildingNumber" : null
}'
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
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

200 OK

The request completed successfully.

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.

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 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;charset=UTF-8' \
    -H 'Accept: application/json;charset=UTF-8' \
    -d '{
  "city" : "Brzeziny",
  "street" : "Armii Czer",
  "buildingNumber" : null
}'
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
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

200 OK

The request completed successfully.

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.

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 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;charset=UTF-8' \
    -H 'Accept: application/json;charset=UTF-8' \
    -d '{
  "city" : "Suchy Las",
  "street" : "Sucholeska",
  "buildingNumber" : "1"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
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

200 OK

The request completed successfully.

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.

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 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;charset=UTF-8' \
    -H 'Accept: application/json;charset=UTF-8' \
    -d '{
  "city" : "Warszawa",
  "street" : "Puławska",
  "buildingNumber" : "228"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
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 not exist, status code 404 is returned, along with the message “Postal code doesn’t exist”.

HTTP status codes

Status code Usage

200 OK

The request completed successfully.

404 Not Found

The requested resource could not be found

400 Bad Request

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

503 Service Unavailable

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

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 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
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
Copyright © 2021 Adresowe bazy danych i usługi ich czyszczenia | algomaps.pl
Polityka prywatności (Privacy policy)