Algolytics DQ-online API

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

Overview

API for online and automatic address data cleaning.

General information

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

Status code Usage

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.
`401 Unauthorized`	The request has not been applied because it lacks valid authentication credentials for the target resource.
`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.

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.

401 Unauthorized

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

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

Save process parameters

Method

POST

Path

/api/v1/params

A method for storing particular process parameters. Returns an identifier used to retrieve the stored parameters.

HTTP status codes

Status code Usage

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.

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.

Request structure

Table 1. Request headers
Name	Description
`Authorization`	Basic auth credentials
`Content-Type`	application/json

Table 2. Request fields
Path	Type	Description
`activeModules`	`Array`	Modules that will be used to process input data. Available values are: "ADDRESSES" (enables address processing)
`includeSymbolicNames`	`Boolean`	Enabling this option includes symbolic names (GUS TERYT identifiers) for cities, streets and communes on the output
`includeGusZones`	`Boolean`	Enabling this option includes GUS statistical region and census circuit information on the output
`includeGeographicCoordinates`	`Boolean`	Enabling this option includes geographic coordinates (latitude and longitude) on the output
`includeBuildingsInfo`	`Boolean`	Enabling this option includes number of flats and residents of the buildings on the output
`includeDiagnosticInfo`	`Boolean`	Enabling this option includes detailed information about the status of matching and geocoding on the output

Response structure

Table 3. Response headers
Name	Description
`Content-Type`	text/plain

Example

Request

$ curl 'https://dq-online.example.host/api/v1/params' -i -u 'user:p4ssword' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "activeModules" : [ "ADDRESSES" ],
  "includeSymbolicNames" : false,
  "includeGusZones" : false,
  "includeGeographicCoordinates" : false,
  "includeBuildingsInfo" : true,
  "includeDiagnosticInfo" : false
}'

Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: text/plain;charset=UTF-8
Content-Length: 36
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
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

97fbb9fa-f15e-4567-ace5-76f502cd394a

Load process parameters

Method

GET

Path

/api/v1/params/{processParametersId}

A method for retrieving previously saved process parameters.

HTTP status codes

Status code Usage

Status code	Usage
`400 Bad Request`	The request was malformed. The response body will include an error providing further information.
`404 Not Found`	The given `processParametersId` does not exist

400 Bad Request

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

404 Not Found

The given processParametersId does not exist

Request structure

Table 4. Request headers
Name	Description
`Authorization`	Basic auth credentials

Table 5. /api/v1/params/{processParametersId}
Parameter	Description
`processParametersId`	Identifier of previously saved parameters (returned by POST /api/v1/params)

Response structure

Table 6. Response headers
Name	Description
`Content-Type`	application/json

Table 7. Response fields
Path	Type	Description
`activeModules`	`Array`	Modules that will be used to process input data. Available values are: "ADDRESSES" (enables address processing)
`includeSymbolicNames`	`Boolean`	Enabling this option includes symbolic names (GUS TERYT identifiers) for cities, streets and communes on the output
`includeGusZones`	`Boolean`	Enabling this option includes GUS statistical region and census circuit information on the output
`includeGeographicCoordinates`	`Boolean`	Enabling this option includes geographic coordinates (latitude and longitude) on the output
`includeBuildingsInfo`	`Boolean`	Enabling this option includes number of flats and residents of the buildings on the output
`includeDiagnosticInfo`	`Boolean`	Enabling this option includes detailed information about the status of matching and geocoding on the output

Example

Request

$ curl 'https://dq-online.example.host/api/v1/params/3c921cd2-2551-405e-968f-187b32f3741e' -i -u 'user: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: 0
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: 208

{
  "activeModules" : [ "ADDRESSES" ],
  "includeSymbolicNames" : true,
  "includeGusZones" : true,
  "includeGeographicCoordinates" : true,
  "includeBuildingsInfo" : true,
  "includeDiagnosticInfo" : true
}

Clean rows using saved parameters

Method

POST

Path

/api/v1/rows/{processParametersId}

A method for cleaning given rows of raw data, which uses previously saved process parameters. The order of the input rows is preserved in the output array. There are restrictions on combining address data properties, see Restrictions on combining address data properties for more details. All fields in the output structure are optional and depend on the process parameters.

HTTP status codes

Status code Usage

Status code	Usage
`207 Multi-Status`	There were errors cleansing some records. Records for which processing error has occurred may be partially cleansed. Such records will contain the [error] object in the resulting JSON object.
`400 Bad Request`	The request was malformed. The response body will include an error providing further information.
`404 Not Found`	The given `processParametersId` does not exist
`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 data cleansing is currently unavailable due to maintenance.

207 Multi-Status

There were errors cleansing some records. Records for which processing error has occurred may be partially cleansed. Such records will contain the [error] object in the resulting JSON object.

400 Bad Request

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

404 Not Found

The given processParametersId does not exist

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 data cleansing is currently unavailable due to maintenance.

Request structure

Table 8. Request headers
Name	Description
`Authorization`	Basic auth credentials
`Content-Type`	application/json

Table 9. /api/v1/rows/{processParametersId}
Parameter	Description
`processParametersId`	Identifier of previously saved parameters (returned by POST /api/v1/params)

Table 10. Request fields
Path	Type	Description
`[]`	`Array`	An array of input rows to be processed
`[].postalCode`	`String`	[Optional] Postal code
`[].cityName`	`String`	[Optional] City name
`[].streetName`	`String`	[Optional] Street name
`[].streetNumber`	`String`	[Optional] Street number
`[].apartmentNumber`	`String`	[Optional] Apartment number
`[].streetNumberAndApartmentNumber`	`String`	[Optional] Concatenation of the street number and apartment number (alternative to separate fields: streetNumber, apartmentNumber)
`[].streetNameAndStreetNumberAndApartmentNumber`	`String`	[Optional] Concatenation of the street name, street number and apartment number (alternative to separate fields: streetName, streetNumber, apartmentNumber)
`[].voivodeshipName`	`String`	[Optional] Voivodeship name
`[].countyName`	`String`	[Optional] County name
`[].communeName`	`String`	[Optional] Commune name
`[].generalData`	`String`	[Optional] Concatenation of all address information available

Response structure

Table 11. Response headers
Name	Description
`Content-Type`	application/json

Table 12. Response fields
Path	Type	Description
`[]`	`Array`	An array of output rows containing the cleansed data
`[].addressId`	`String`	Unique address identifier, constant in time. Requires [ADDRESSES] module
`[].cityName`	`String`	Cleaned city name. Requires [ADDRESSES] module
`[].cityDistrictName`	`String`	Cleaned city district name. Requires [ADDRESSES] module
`[].streetAttribute`	`String`	Street attribute (e.g. ul., al., pl.). Requires [ADDRESSES] module
`[].streetName`	`String`	Cleaned street name (without street attribute). Requires [ADDRESSES] module
`[].streetNameMajorPart`	`String`	The main part of the street name (e.g. the surname of the patron). Requires [ADDRESSES] module
`[].streetNameMinorPart`	`String`	A less important part of the street name (does not always exist, e.g. the first name of the patron). Requires [ADDRESSES] module
`[].streetNumber`	`String`	Cleaned street number. Requires [ADDRESSES] module
`[].apartmentNumber`	`String`	Cleaned apartment number. Requires [ADDRESSES] module
`[].numberOfApartments`	`Number`	Number of apartments according to the GUS. Requires [ADDRESSES] module
`[].numberOfJuridicalPersons`	`Number`	Number of juridical persons and organizational units located in a given building according to the REGON register. Requires [ADDRESSES] module
`[].postalCode`	`String`	Cleaned postal code with NN-NNN format where N is a digit (0-9). Requires [ADDRESSES] module
`[].communeName`	`String`	Cleaned commune name. Requires [ADDRESSES] module
`[].countyName`	`String`	Cleaned county name. Requires [ADDRESSES] module
`[].voivodeshipName`	`String`	Cleaned voivodeship name. Requires [ADDRESSES] module
`[].citySymbol`	`String`	Symbolic name for city (GUS TERYT identifier). Requires [ADDRESSES] module and [includeSymbolicNames] option enabled
`[].cityDistrictSymbol`	`String`	Symbolic name for city district (GUS TERYT identifier). Requires [ADDRESSES] module and [includeSymbolicNames] option enabled
`[].streetSymbol`	`String`	Symbolic name for street (GUS TERYT identifier). Requires [ADDRESSES] module and [includeSymbolicNames] option enabled
`[].communeSymbol`	`String`	Commune code with XXYYZZ format where XX is voivodship code, YY is county within voivodship code, ZZ is commune within county code. Requires [ADDRESSES] module and [includeSymbolicNames] option enabled
`[].communeTypeName`	`String`	Name of the commune type, one of: "gmina miejska", "gmina wiejska", "część miejska gminy miejsko-wiejskiej", "część wiejska gminy miejsko-wiejskiej". Requires [ADDRESSES] module and [includeSymbolicNames] option enabled
`[].communeTypeSymbol`	`Number`	Numeric symbol of the commune type, one of: 1 (for gmina miejska), 2 (for gmina wiejska), 4 (for część miejska gminy miejsko-wiejskiej), 5 (for część wiejska gminy miejsko-wiejskiej). Requires [ADDRESSES] module and [includeSymbolicNames] option enabled
`[].statisticalRegionSymbol`	`String`	Commune code, along with its type and statistical region in the given format: XXYYZZTRRRRRRRR where XXYYZZ is [communeSymbol], T is [communeTypeSymbol], RRRRRRRR is 8-digit statistical region code (GUS TERYT identifier). Requires [ADDRESSES] module and [includeGusZones] option enabled
`[].censusCircuitSymbol`	`String`	Commune code, along with its type, statistical region and census circuit within this region in the given format: XXYYZZTRRRRRRRRC where XXYYZZTRRRRRRRR is [statisticalRegionSymbol], C is census circuit within statistical region code (GUS TERYT identifier). Requires [ADDRESSES] module and [includeGusZones] option enabled
`[].taxationAuthority`	`String`	Name of the tax authority competent for the address. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfInhabitedApartmentsByGUS`	`Number`	Number of inhabited apartments according to the GUS. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfInhabitantsByGUS`	`Number`	Number of inhabitants according to the GUS. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfInhabitedApartmentsByPESEL`	`Number`	Number of inhabited apartments according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfInhabitantsByPESEL`	`Number`	Number of inhabitants according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomen`	`Number`	Number of female inhabitants according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMen`	`Number`	Number of male inhabitants according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_0_4_yearsOld`	`Number`	Number of female inhabitants between 0 and 4 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_5_9_yearsOld`	`Number`	Number of female inhabitants between 5 and 9 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_10_14_yearsOld`	`Number`	Number of female inhabitants between 10 and 14 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_15_19_yearsOld`	`Number`	Number of female inhabitants between 15 and 19 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_20_24_yearsOld`	`Number`	Number of female inhabitants between 20 and 24 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_25_29_yearsOld`	`Number`	Number of female inhabitants between 25 and 29 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_30_34_yearsOld`	`Number`	Number of female inhabitants between 30 and 34 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_35_39_yearsOld`	`Number`	Number of female inhabitants between 35 and 39 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_40_44_yearsOld`	`Number`	Number of female inhabitants between 40 and 44 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_45_49_yearsOld`	`Number`	Number of female inhabitants between 45 and 49 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_50_54_yearsOld`	`Number`	Number of female inhabitants between 50 and 54 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_55_59_yearsOld`	`Number`	Number of female inhabitants between 55 and 59 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_60_64_yearsOld`	`Number`	Number of female inhabitants between 60 and 64 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenOver_65_yearsOld`	`Number`	Number of female inhabitants over 65 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_0_4_yearsOld`	`Number`	Number of male inhabitants between 0 and 4 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_5_9_yearsOld`	`Number`	Number of male inhabitants between 5 and 9 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_10_14_yearsOld`	`Number`	Number of male inhabitants between 10 and 14 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_15_19_yearsOld`	`Number`	Number of male inhabitants between 15 and 19 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_20_24_yearsOld`	`Number`	Number of male inhabitants between 20 and 24 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_25_29_yearsOld`	`Number`	Number of male inhabitants between 25 and 29 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_30_34_yearsOld`	`Number`	Number of male inhabitants between 30 and 34 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_35_39_yearsOld`	`Number`	Number of male inhabitants between 35 and 39 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_40_44_yearsOld`	`Number`	Number of male inhabitants between 40 and 44 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_45_49_yearsOld`	`Number`	Number of male inhabitants between 45 and 49 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_50_54_yearsOld`	`Number`	Number of male inhabitants between 50 and 54 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_55_59_yearsOld`	`Number`	Number of male inhabitants between 55 and 59 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_60_64_yearsOld`	`Number`	Number of male inhabitants between 60 and 64 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenOver_65_yearsOld`	`Number`	Number of male inhabitants over 65 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].statuses`	`String`	Concatenation of matching and geocoding statuses in the given format: "<category:result>" or "<category>" where the category can take one of the values: "przypisanie niejednoznaczne", "zmiana nazwy miejscowości", "zmiana nazwy ulicy", "dopasowanie", "geokodowanie". Requires [ADDRESSES] module and [includeDiagnosticInfo] option enabled
`[].matchedTokens`	`Array`	An array of input tokens interpreted as part of the address. Requires [ADDRESSES] module and [includeDiagnosticInfo] option enabled
`[].matchedTokens[].token`	`String`	Input token converted to lowercase
`[].matchedTokens[].tokenType`	`String`	Token type indicating which part of the address it corresponds to
`[].longitude`	`Number`	East longitude degree value. Requires [ADDRESSES] module and [includeGeographicCoordinates] option enabled
`[].latitude`	`Number`	North latitude degree value. Requires [ADDRESSES] module and [includeGeographicCoordinates] option enabled
`[].error`	`Object`	Object indicating that an error occurred while processing the given row. Contains details about the error
`[].error.message`	`String`	An error message explaining that the input row was incorrect or an unexpected application error occurred
`[].error.status`	`String`	Numerical representation of the error. The following codes are provided: "001" - input rows array contains null element eg. [{"postalCode": "26-601"}, null], "002" - violation of Restrictions on combining address data properties, "500" - unexpected server error

Example

Request

$ curl 'https://dq-online.example.host/api/v1/rows/cbdc9a5f-909b-4a9e-9500-6c7138efeb7d' -i -u 'user:p4ssword' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '[ {
  "postalCode" : "22100",
  "cityName" : "CHEŁM",
  "streetNameAndStreetNumberAndApartmentNumber" : "HRUBIESZOWSKA 54/1"
}, {
  "postalCode" : "22-100",
  "cityName" : "CHEŁM",
  "streetName" : "MIKOŁAJA REJA",
  "streetNumber" : "40",
  "apartmentNumber" : "2"
} ]'

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: 0
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: 5264

[ {
  "statuses" : "<dopasowanie: budynek, w którym nie ma mieszkań><geokodowanie: dopasowany budynek>",
  "addressId" : "0929902_06761_54",
  "cityName" : "Chełm",
  "citySymbol" : "0929902",
  "streetName" : "Hrubieszowska",
  "streetSymbol" : "06761",
  "streetAttribute" : "ul.",
  "streetNameMajorPart" : "Hrubieszowska",
  "postalCode" : "22-100",
  "streetNumber" : "54",
  "apartmentNumber" : "1",
  "voivodeshipName" : "lubelskie",
  "countyName" : "Chełm",
  "communeName" : "Chełm",
  "communeSymbol" : "066201",
  "communeTypeSymbol" : 1,
  "communeTypeName" : "gmina miejska",
  "statisticalRegionSymbol" : "0662011120550",
  "censusCircuitSymbol" : "06620111205502",
  "latitude" : 51.1278336866813,
  "longitude" : 23.4870213871788,
  "numberOfApartments" : 1,
  "numberOfInhabitedApartmentsByGUS" : 1,
  "numberOfInhabitedApartmentsByPESEL" : 1,
  "numberOfInhabitantsByGUS" : 2,
  "numberOfInhabitantsByPESEL" : 2,
  "numberOfMen" : 2,
  "numberOfMenBetween_0_4_yearsOld" : 0,
  "numberOfMenBetween_5_9_yearsOld" : 0,
  "numberOfMenBetween_10_14_yearsOld" : 0,
  "numberOfMenBetween_15_19_yearsOld" : 0,
  "numberOfMenBetween_20_24_yearsOld" : 0,
  "numberOfMenBetween_25_29_yearsOld" : 0,
  "numberOfMenBetween_30_34_yearsOld" : 0,
  "numberOfMenBetween_35_39_yearsOld" : 1,
  "numberOfMenBetween_40_44_yearsOld" : 0,
  "numberOfMenBetween_45_49_yearsOld" : 0,
  "numberOfMenBetween_50_54_yearsOld" : 0,
  "numberOfMenBetween_55_59_yearsOld" : 0,
  "numberOfMenBetween_60_64_yearsOld" : 1,
  "numberOfMenOver_65_yearsOld" : 0,
  "numberOfWomen" : 0,
  "numberOfWomenBetween_0_4_yearsOld" : 0,
  "numberOfWomenBetween_5_9_yearsOld" : 0,
  "numberOfWomenBetween_10_14_yearsOld" : 0,
  "numberOfWomenBetween_15_19_yearsOld" : 0,
  "numberOfWomenBetween_20_24_yearsOld" : 0,
  "numberOfWomenBetween_25_29_yearsOld" : 0,
  "numberOfWomenBetween_30_34_yearsOld" : 0,
  "numberOfWomenBetween_35_39_yearsOld" : 0,
  "numberOfWomenBetween_40_44_yearsOld" : 0,
  "numberOfWomenBetween_45_49_yearsOld" : 0,
  "numberOfWomenBetween_50_54_yearsOld" : 0,
  "numberOfWomenBetween_55_59_yearsOld" : 0,
  "numberOfWomenBetween_60_64_yearsOld" : 0,
  "numberOfWomenOver_65_yearsOld" : 0,
  "numberOfJuridicalPersons" : 0,
  "taxationAuthority" : "Urząd Skarbowy w Chełmie",
  "matchedTokens" : [ {
    "token" : "22100",
    "tokenType" : "postalCode"
  }, {
    "token" : "chełm",
    "tokenType" : "cityName"
  }, {
    "token" : "hrubieszowska",
    "tokenType" : "streetName"
  }, {
    "token" : "54/1",
    "tokenType" : "streetNumber"
  } ]
}, {
  "statuses" : "<dopasowanie: budynek, w którym nie ma mieszkań><geokodowanie: dopasowany budynek>",
  "addressId" : "0929902_18565_40",
  "cityName" : "Chełm",
  "citySymbol" : "0929902",
  "streetName" : "Mikołaja Reja",
  "streetSymbol" : "18565",
  "streetAttribute" : "ul.",
  "streetNameMajorPart" : "Reja",
  "streetNameMinorPart" : "Mikołaja",
  "postalCode" : "22-100",
  "streetNumber" : "40",
  "apartmentNumber" : "2",
  "voivodeshipName" : "lubelskie",
  "countyName" : "Chełm",
  "communeName" : "Chełm",
  "communeSymbol" : "066201",
  "communeTypeSymbol" : 1,
  "communeTypeName" : "gmina miejska",
  "statisticalRegionSymbol" : "0662011120412",
  "censusCircuitSymbol" : "06620111204123",
  "latitude" : 51.1328840425146,
  "longitude" : 23.5075517699559,
  "numberOfApartments" : 1,
  "numberOfInhabitedApartmentsByGUS" : 1,
  "numberOfInhabitedApartmentsByPESEL" : 2,
  "numberOfInhabitantsByGUS" : 5,
  "numberOfInhabitantsByPESEL" : 7,
  "numberOfMen" : 3,
  "numberOfMenBetween_0_4_yearsOld" : 0,
  "numberOfMenBetween_5_9_yearsOld" : 0,
  "numberOfMenBetween_10_14_yearsOld" : 0,
  "numberOfMenBetween_15_19_yearsOld" : 0,
  "numberOfMenBetween_20_24_yearsOld" : 1,
  "numberOfMenBetween_25_29_yearsOld" : 0,
  "numberOfMenBetween_30_34_yearsOld" : 0,
  "numberOfMenBetween_35_39_yearsOld" : 0,
  "numberOfMenBetween_40_44_yearsOld" : 0,
  "numberOfMenBetween_45_49_yearsOld" : 0,
  "numberOfMenBetween_50_54_yearsOld" : 1,
  "numberOfMenBetween_55_59_yearsOld" : 0,
  "numberOfMenBetween_60_64_yearsOld" : 1,
  "numberOfMenOver_65_yearsOld" : 0,
  "numberOfWomen" : 4,
  "numberOfWomenBetween_0_4_yearsOld" : 1,
  "numberOfWomenBetween_5_9_yearsOld" : 0,
  "numberOfWomenBetween_10_14_yearsOld" : 0,
  "numberOfWomenBetween_15_19_yearsOld" : 0,
  "numberOfWomenBetween_20_24_yearsOld" : 1,
  "numberOfWomenBetween_25_29_yearsOld" : 0,
  "numberOfWomenBetween_30_34_yearsOld" : 0,
  "numberOfWomenBetween_35_39_yearsOld" : 0,
  "numberOfWomenBetween_40_44_yearsOld" : 0,
  "numberOfWomenBetween_45_49_yearsOld" : 0,
  "numberOfWomenBetween_50_54_yearsOld" : 1,
  "numberOfWomenBetween_55_59_yearsOld" : 0,
  "numberOfWomenBetween_60_64_yearsOld" : 0,
  "numberOfWomenOver_65_yearsOld" : 1,
  "numberOfJuridicalPersons" : 0,
  "taxationAuthority" : "Urząd Skarbowy w Chełmie",
  "matchedTokens" : [ {
    "token" : "22-100",
    "tokenType" : "postalCode"
  }, {
    "token" : "chełm",
    "tokenType" : "cityName"
  }, {
    "token" : "mikołaja",
    "tokenType" : "streetName"
  }, {
    "token" : "reja",
    "tokenType" : "streetName"
  }, {
    "token" : "40",
    "tokenType" : "streetNumber"
  }, {
    "token" : "2",
    "tokenType" : "apartmentNumber"
  } ]
} ]

Clean rows

Method

POST

Path

/api/v1/rows

A method for cleaning given rows of raw data. The order of the input rows is preserved in the output array. There are restrictions on combining address data properties, see Restrictions on combining address data properties for more details. All fields in the output structure are optional and depend on the process parameters.

HTTP status codes

Status code Usage

Status code	Usage
`207 Multi-Status`	There were errors cleansing some records. Records for which processing error has occurred may be partially cleansed. Such records will contain the [error] object in the resulting JSON object.
`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 data cleansing is currently unavailable due to maintenance.

207 Multi-Status

There were errors cleansing some records. Records for which processing error has occurred may be partially cleansed. Such records will contain the [error] object in the resulting JSON object.

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 data cleansing is currently unavailable due to maintenance.

Request structure

Table 13. Request headers
Name	Description
`Authorization`	Basic auth credentials
`Content-Type`	application/json

Table 14. Request fields
Path	Type	Description
`inputRows`	`Array`	An array of input rows to be processed
`processParameters`	`Object`	Parameters configuring the data cleansing process
`inputRows[].postalCode`	`String`	[Optional] Postal code
`inputRows[].cityName`	`String`	[Optional] City name
`inputRows[].streetName`	`String`	[Optional] Street name
`inputRows[].streetNumber`	`String`	[Optional] Street number
`inputRows[].apartmentNumber`	`String`	[Optional] Apartment number
`inputRows[].streetNumberAndApartmentNumber`	`String`	[Optional] Concatenation of the street number and apartment number (alternative to separate fields: streetNumber, apartmentNumber)
`inputRows[].streetNameAndStreetNumberAndApartmentNumber`	`String`	[Optional] Concatenation of the street name, street number and apartment number (alternative to separate fields: streetName, streetNumber, apartmentNumber)
`inputRows[].voivodeshipName`	`String`	[Optional] Voivodeship name
`inputRows[].countyName`	`String`	[Optional] County name
`inputRows[].communeName`	`String`	[Optional] Commune name
`inputRows[].generalData`	`String`	[Optional] Concatenation of all address information available
`processParameters.activeModules`	`Array`	Modules that will be used to process input data. Available values are: "ADDRESSES" (enables address processing)
`processParameters.includeSymbolicNames`	`Boolean`	Enabling this option includes symbolic names (GUS TERYT identifiers) for cities, streets and communes on the output
`processParameters.includeGusZones`	`Boolean`	Enabling this option includes GUS statistical region and census circuit information on the output
`processParameters.includeGeographicCoordinates`	`Boolean`	Enabling this option includes geographic coordinates (latitude and longitude) on the output
`processParameters.includeBuildingsInfo`	`Boolean`	Enabling this option includes number of flats and residents of the buildings on the output
`processParameters.includeDiagnosticInfo`	`Boolean`	Enabling this option includes detailed information about the status of matching and geocoding on the output

Response structure

Table 15. Response headers
Name	Description
`Content-Type`	application/json

Table 16. Response fields
Path	Type	Description
`[]`	`Array`	An array of output rows containing the cleansed data
`[].addressId`	`String`	Unique address identifier, constant in time. Requires [ADDRESSES] module
`[].cityName`	`String`	Cleaned city name. Requires [ADDRESSES] module
`[].cityDistrictName`	`String`	Cleaned city district name. Requires [ADDRESSES] module
`[].streetAttribute`	`String`	Street attribute (e.g. ul., al., pl.). Requires [ADDRESSES] module
`[].streetName`	`String`	Cleaned street name (without street attribute). Requires [ADDRESSES] module
`[].streetNameMajorPart`	`String`	The main part of the street name (e.g. the surname of the patron). Requires [ADDRESSES] module
`[].streetNameMinorPart`	`String`	A less important part of the street name (does not always exist, e.g. the first name of the patron). Requires [ADDRESSES] module
`[].streetNumber`	`String`	Cleaned street number. Requires [ADDRESSES] module
`[].apartmentNumber`	`String`	Cleaned apartment number. Requires [ADDRESSES] module
`[].numberOfApartments`	`Number`	Number of apartments according to the GUS. Requires [ADDRESSES] module
`[].numberOfJuridicalPersons`	`Number`	Number of juridical persons and organizational units located in a given building according to the REGON register. Requires [ADDRESSES] module
`[].postalCode`	`String`	Cleaned postal code with NN-NNN format where N is a digit (0-9). Requires [ADDRESSES] module
`[].communeName`	`String`	Cleaned commune name. Requires [ADDRESSES] module
`[].countyName`	`String`	Cleaned county name. Requires [ADDRESSES] module
`[].voivodeshipName`	`String`	Cleaned voivodeship name. Requires [ADDRESSES] module
`[].citySymbol`	`String`	Symbolic name for city (GUS TERYT identifier). Requires [ADDRESSES] module and [includeSymbolicNames] option enabled
`[].cityDistrictSymbol`	`String`	Symbolic name for city district (GUS TERYT identifier). Requires [ADDRESSES] module and [includeSymbolicNames] option enabled
`[].streetSymbol`	`String`	Symbolic name for street (GUS TERYT identifier). Requires [ADDRESSES] module and [includeSymbolicNames] option enabled
`[].communeSymbol`	`String`	Commune code with XXYYZZ format where XX is voivodship code, YY is county within voivodship code, ZZ is commune within county code. Requires [ADDRESSES] module and [includeSymbolicNames] option enabled
`[].communeTypeName`	`String`	Name of the commune type, one of: "gmina miejska", "gmina wiejska", "część miejska gminy miejsko-wiejskiej", "część wiejska gminy miejsko-wiejskiej". Requires [ADDRESSES] module and [includeSymbolicNames] option enabled
`[].communeTypeSymbol`	`Number`	Numeric symbol of the commune type, one of: 1 (for gmina miejska), 2 (for gmina wiejska), 4 (for część miejska gminy miejsko-wiejskiej), 5 (for część wiejska gminy miejsko-wiejskiej). Requires [ADDRESSES] module and [includeSymbolicNames] option enabled
`[].statisticalRegionSymbol`	`String`	Commune code, along with its type and statistical region in the given format: XXYYZZTRRRRRRRR where XXYYZZ is [communeSymbol], T is [communeTypeSymbol], RRRRRRRR is 8-digit statistical region code (GUS TERYT identifier). Requires [ADDRESSES] module and [includeGusZones] option enabled
`[].censusCircuitSymbol`	`String`	Commune code, along with its type, statistical region and census circuit within this region in the given format: XXYYZZTRRRRRRRRC where XXYYZZTRRRRRRRR is [statisticalRegionSymbol], C is census circuit within statistical region code (GUS TERYT identifier). Requires [ADDRESSES] module and [includeGusZones] option enabled
`[].taxationAuthority`	`String`	Name of the tax authority competent for the address. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfInhabitedApartmentsByGUS`	`Number`	Number of inhabited apartments according to the GUS. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfInhabitantsByGUS`	`Number`	Number of inhabitants according to the GUS. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfInhabitedApartmentsByPESEL`	`Number`	Number of inhabited apartments according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfInhabitantsByPESEL`	`Number`	Number of inhabitants according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomen`	`Number`	Number of female inhabitants according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMen`	`Number`	Number of male inhabitants according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_0_4_yearsOld`	`Number`	Number of female inhabitants between 0 and 4 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_5_9_yearsOld`	`Number`	Number of female inhabitants between 5 and 9 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_10_14_yearsOld`	`Number`	Number of female inhabitants between 10 and 14 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_15_19_yearsOld`	`Number`	Number of female inhabitants between 15 and 19 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_20_24_yearsOld`	`Number`	Number of female inhabitants between 20 and 24 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_25_29_yearsOld`	`Number`	Number of female inhabitants between 25 and 29 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_30_34_yearsOld`	`Number`	Number of female inhabitants between 30 and 34 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_35_39_yearsOld`	`Number`	Number of female inhabitants between 35 and 39 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_40_44_yearsOld`	`Number`	Number of female inhabitants between 40 and 44 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_45_49_yearsOld`	`Number`	Number of female inhabitants between 45 and 49 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_50_54_yearsOld`	`Number`	Number of female inhabitants between 50 and 54 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_55_59_yearsOld`	`Number`	Number of female inhabitants between 55 and 59 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenBetween_60_64_yearsOld`	`Number`	Number of female inhabitants between 60 and 64 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfWomenOver_65_yearsOld`	`Number`	Number of female inhabitants over 65 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_0_4_yearsOld`	`Number`	Number of male inhabitants between 0 and 4 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_5_9_yearsOld`	`Number`	Number of male inhabitants between 5 and 9 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_10_14_yearsOld`	`Number`	Number of male inhabitants between 10 and 14 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_15_19_yearsOld`	`Number`	Number of male inhabitants between 15 and 19 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_20_24_yearsOld`	`Number`	Number of male inhabitants between 20 and 24 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_25_29_yearsOld`	`Number`	Number of male inhabitants between 25 and 29 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_30_34_yearsOld`	`Number`	Number of male inhabitants between 30 and 34 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_35_39_yearsOld`	`Number`	Number of male inhabitants between 35 and 39 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_40_44_yearsOld`	`Number`	Number of male inhabitants between 40 and 44 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_45_49_yearsOld`	`Number`	Number of male inhabitants between 45 and 49 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_50_54_yearsOld`	`Number`	Number of male inhabitants between 50 and 54 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_55_59_yearsOld`	`Number`	Number of male inhabitants between 55 and 59 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenBetween_60_64_yearsOld`	`Number`	Number of male inhabitants between 60 and 64 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].numberOfMenOver_65_yearsOld`	`Number`	Number of male inhabitants over 65 years old according to the PESEL register provided by the Ministry of Digitization. Requires [ADDRESSES] module and [includeBuildingsInfo] option enabled
`[].statuses`	`String`	Concatenation of matching and geocoding statuses in the given format: "<category:result>" or "<category>" where the category can take one of the values: "przypisanie niejednoznaczne", "zmiana nazwy miejscowości", "zmiana nazwy ulicy", "dopasowanie", "geokodowanie". Requires [ADDRESSES] module and [includeDiagnosticInfo] option enabled
`[].matchedTokens`	`Array`	An array of input tokens interpreted as part of the address. Requires [ADDRESSES] module and [includeDiagnosticInfo] option enabled
`[].matchedTokens[].token`	`String`	Input token converted to lowercase
`[].matchedTokens[].tokenType`	`String`	Token type indicating which part of the address it corresponds to
`[].longitude`	`Number`	East longitude degree value. Requires [ADDRESSES] module and [includeGeographicCoordinates] option enabled
`[].latitude`	`Number`	North latitude degree value. Requires [ADDRESSES] module and [includeGeographicCoordinates] option enabled
`[].error`	`Object`	Object indicating that an error occurred while processing the given row. Contains details about the error
`[].error.message`	`String`	An error message explaining that the input row was incorrect or an unexpected application error occurred
`[].error.status`	`String`	Numerical representation of the error. The following codes are provided: "001" - input rows array contains null element eg. [{"postalCode": "26-601"}, null], "002" - violation of Restrictions on combining address data properties, "500" - unexpected server error

Example

Request

$ curl 'https://dq-online.example.host/api/v1/rows' -i -u 'user:p4ssword' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "inputRows" : [ {
    "postalCode" : "22100",
    "cityName" : "CHEŁM",
    "streetNameAndStreetNumberAndApartmentNumber" : "HRUBIESZOWSKA 54/1"
  }, {
    "postalCode" : "22-100",
    "cityName" : "CHEŁM",
    "streetName" : "MIKOŁAJA REJA",
    "streetNumber" : "40",
    "apartmentNumber" : "2"
  } ],
  "processParameters" : {
    "activeModules" : [ "ADDRESSES" ],
    "includeSymbolicNames" : true,
    "includeGusZones" : true,
    "includeGeographicCoordinates" : true,
    "includeBuildingsInfo" : true,
    "includeDiagnosticInfo" : true
  }
}'

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: 0
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: 5264

[ {
  "statuses" : "<dopasowanie: budynek, w którym nie ma mieszkań><geokodowanie: dopasowany budynek>",
  "addressId" : "0929902_06761_54",
  "cityName" : "Chełm",
  "citySymbol" : "0929902",
  "streetName" : "Hrubieszowska",
  "streetSymbol" : "06761",
  "streetAttribute" : "ul.",
  "streetNameMajorPart" : "Hrubieszowska",
  "postalCode" : "22-100",
  "streetNumber" : "54",
  "apartmentNumber" : "1",
  "voivodeshipName" : "lubelskie",
  "countyName" : "Chełm",
  "communeName" : "Chełm",
  "communeSymbol" : "066201",
  "communeTypeSymbol" : 1,
  "communeTypeName" : "gmina miejska",
  "statisticalRegionSymbol" : "0662011120550",
  "censusCircuitSymbol" : "06620111205502",
  "latitude" : 51.1278336866813,
  "longitude" : 23.4870213871788,
  "numberOfApartments" : 1,
  "numberOfInhabitedApartmentsByGUS" : 1,
  "numberOfInhabitedApartmentsByPESEL" : 1,
  "numberOfInhabitantsByGUS" : 2,
  "numberOfInhabitantsByPESEL" : 2,
  "numberOfMen" : 2,
  "numberOfMenBetween_0_4_yearsOld" : 0,
  "numberOfMenBetween_5_9_yearsOld" : 0,
  "numberOfMenBetween_10_14_yearsOld" : 0,
  "numberOfMenBetween_15_19_yearsOld" : 0,
  "numberOfMenBetween_20_24_yearsOld" : 0,
  "numberOfMenBetween_25_29_yearsOld" : 0,
  "numberOfMenBetween_30_34_yearsOld" : 0,
  "numberOfMenBetween_35_39_yearsOld" : 1,
  "numberOfMenBetween_40_44_yearsOld" : 0,
  "numberOfMenBetween_45_49_yearsOld" : 0,
  "numberOfMenBetween_50_54_yearsOld" : 0,
  "numberOfMenBetween_55_59_yearsOld" : 0,
  "numberOfMenBetween_60_64_yearsOld" : 1,
  "numberOfMenOver_65_yearsOld" : 0,
  "numberOfWomen" : 0,
  "numberOfWomenBetween_0_4_yearsOld" : 0,
  "numberOfWomenBetween_5_9_yearsOld" : 0,
  "numberOfWomenBetween_10_14_yearsOld" : 0,
  "numberOfWomenBetween_15_19_yearsOld" : 0,
  "numberOfWomenBetween_20_24_yearsOld" : 0,
  "numberOfWomenBetween_25_29_yearsOld" : 0,
  "numberOfWomenBetween_30_34_yearsOld" : 0,
  "numberOfWomenBetween_35_39_yearsOld" : 0,
  "numberOfWomenBetween_40_44_yearsOld" : 0,
  "numberOfWomenBetween_45_49_yearsOld" : 0,
  "numberOfWomenBetween_50_54_yearsOld" : 0,
  "numberOfWomenBetween_55_59_yearsOld" : 0,
  "numberOfWomenBetween_60_64_yearsOld" : 0,
  "numberOfWomenOver_65_yearsOld" : 0,
  "numberOfJuridicalPersons" : 0,
  "taxationAuthority" : "Urząd Skarbowy w Chełmie",
  "matchedTokens" : [ {
    "token" : "22100",
    "tokenType" : "postalCode"
  }, {
    "token" : "chełm",
    "tokenType" : "cityName"
  }, {
    "token" : "hrubieszowska",
    "tokenType" : "streetName"
  }, {
    "token" : "54/1",
    "tokenType" : "streetNumber"
  } ]
}, {
  "statuses" : "<dopasowanie: budynek, w którym nie ma mieszkań><geokodowanie: dopasowany budynek>",
  "addressId" : "0929902_18565_40",
  "cityName" : "Chełm",
  "citySymbol" : "0929902",
  "streetName" : "Mikołaja Reja",
  "streetSymbol" : "18565",
  "streetAttribute" : "ul.",
  "streetNameMajorPart" : "Reja",
  "streetNameMinorPart" : "Mikołaja",
  "postalCode" : "22-100",
  "streetNumber" : "40",
  "apartmentNumber" : "2",
  "voivodeshipName" : "lubelskie",
  "countyName" : "Chełm",
  "communeName" : "Chełm",
  "communeSymbol" : "066201",
  "communeTypeSymbol" : 1,
  "communeTypeName" : "gmina miejska",
  "statisticalRegionSymbol" : "0662011120412",
  "censusCircuitSymbol" : "06620111204123",
  "latitude" : 51.1328840425146,
  "longitude" : 23.5075517699559,
  "numberOfApartments" : 1,
  "numberOfInhabitedApartmentsByGUS" : 1,
  "numberOfInhabitedApartmentsByPESEL" : 2,
  "numberOfInhabitantsByGUS" : 5,
  "numberOfInhabitantsByPESEL" : 7,
  "numberOfMen" : 3,
  "numberOfMenBetween_0_4_yearsOld" : 0,
  "numberOfMenBetween_5_9_yearsOld" : 0,
  "numberOfMenBetween_10_14_yearsOld" : 0,
  "numberOfMenBetween_15_19_yearsOld" : 0,
  "numberOfMenBetween_20_24_yearsOld" : 1,
  "numberOfMenBetween_25_29_yearsOld" : 0,
  "numberOfMenBetween_30_34_yearsOld" : 0,
  "numberOfMenBetween_35_39_yearsOld" : 0,
  "numberOfMenBetween_40_44_yearsOld" : 0,
  "numberOfMenBetween_45_49_yearsOld" : 0,
  "numberOfMenBetween_50_54_yearsOld" : 1,
  "numberOfMenBetween_55_59_yearsOld" : 0,
  "numberOfMenBetween_60_64_yearsOld" : 1,
  "numberOfMenOver_65_yearsOld" : 0,
  "numberOfWomen" : 4,
  "numberOfWomenBetween_0_4_yearsOld" : 1,
  "numberOfWomenBetween_5_9_yearsOld" : 0,
  "numberOfWomenBetween_10_14_yearsOld" : 0,
  "numberOfWomenBetween_15_19_yearsOld" : 0,
  "numberOfWomenBetween_20_24_yearsOld" : 1,
  "numberOfWomenBetween_25_29_yearsOld" : 0,
  "numberOfWomenBetween_30_34_yearsOld" : 0,
  "numberOfWomenBetween_35_39_yearsOld" : 0,
  "numberOfWomenBetween_40_44_yearsOld" : 0,
  "numberOfWomenBetween_45_49_yearsOld" : 0,
  "numberOfWomenBetween_50_54_yearsOld" : 1,
  "numberOfWomenBetween_55_59_yearsOld" : 0,
  "numberOfWomenBetween_60_64_yearsOld" : 0,
  "numberOfWomenOver_65_yearsOld" : 1,
  "numberOfJuridicalPersons" : 0,
  "taxationAuthority" : "Urząd Skarbowy w Chełmie",
  "matchedTokens" : [ {
    "token" : "22-100",
    "tokenType" : "postalCode"
  }, {
    "token" : "chełm",
    "tokenType" : "cityName"
  }, {
    "token" : "mikołaja",
    "tokenType" : "streetName"
  }, {
    "token" : "reja",
    "tokenType" : "streetName"
  }, {
    "token" : "40",
    "tokenType" : "streetNumber"
  }, {
    "token" : "2",
    "tokenType" : "apartmentNumber"
  } ]
} ]

Restrictions on combining address data 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 002 [error].

Administrative operations

Start maintenance

Method

POST

Path

/api/v1/maintenance

Prepares application for reloading new dictionaries into memory. After this method is called no new requests will be accepted. All ongoing requests will be finished properly.

HTTP status codes

Status code Usage

Status code	Usage
`403 Forbidden`	User has insufficient permissions to call this method.
`503 Service Unavailable`	The request was well-formed but action is currently unavailable due to maintenance. Occurs when operation can’t be performed from the current state (see Maintenance status).

403 Forbidden

User has insufficient permissions to call this method.

503 Service Unavailable

The request was well-formed but action is currently unavailable due to maintenance. Occurs when operation can’t be performed from the current state (see Maintenance status).

Request structure

Table 17. Request headers
Name	Description
`Authorization`	Basic auth credentials

Example

Request

$ curl 'https://dq-online.example.host/api/v1/maintenance' -i -u 'admin:p4ssword' -X POST

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: 0
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

Reload data

Method

POST

Path

/api/v1/reload

Sends a signal to the application to reload new dictionaries into memory. This method can only be invoked after Start maintenance method have bean called and all ongoing requests have finished.

HTTP status codes

Status code Usage

Status code	Usage
`403 Forbidden`	User has insufficient permissions to call this method.
`503 Service Unavailable`	The request was well-formed but action is currently unavailable due to maintenance. Occurs when operation can’t be performed from the current state (see Maintenance status).

403 Forbidden

User has insufficient permissions to call this method.

503 Service Unavailable

The request was well-formed but action is currently unavailable due to maintenance. Occurs when operation can’t be performed from the current state (see Maintenance status).

Request structure

Table 18. Request headers
Name	Description
`Authorization`	Basic auth credentials

Example

Request

$ curl 'https://dq-online.example.host/api/v1/reload' -i -u 'admin:p4ssword' -X POST

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: 0
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

Abort maintenance

Method

POST

Path

/api/v1/abort

Sends signal to application that no reload is required and application should continue serving requests. This method can only be invoked after Start maintenance method have bean called.

HTTP status codes

Status code Usage

Status code	Usage
`403 Forbidden`	User has insufficient permissions to call this method.
`503 Service Unavailable`	The request was well-formed but action is currently unavailable due to maintenance. Occurs when operation can’t be performed from the current state (see Maintenance status).

403 Forbidden

User has insufficient permissions to call this method.

503 Service Unavailable

The request was well-formed but action is currently unavailable due to maintenance. Occurs when operation can’t be performed from the current state (see Maintenance status).

Request structure

Table 19. Request headers
Name	Description
`Authorization`	Basic auth credentials

Example

Request

$ curl 'https://dq-online.example.host/api/v1/abort' -i -u 'admin:p4ssword' -X POST

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: 0
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

Maintenance status

Method

GET

Path

/api/v1/status

Returns maintenance status. Maintenance is divided into subsequent stages (see Maintenance stages description): RUNNING, STOPPING, STOPPED, RELOADING, ERROR. Dictionaries should only be changed when maintenance is in STOPPED status - after invoking Start maintenance method.

HTTP status codes

Status code Usage

Status code	Usage
`403 Forbidden`	User has insufficient permissions to call this method.

403 Forbidden

User has insufficient permissions to call this method.

Request structure

Table 20. Request headers
Name	Description
`Authorization`	Basic auth credentials

Response structure

Table 21. Response headers
Name	Description
`Content-Type`	text/plain

Example

Request

$ curl 'https://dq-online.example.host/api/v1/status' -i -u 'admin:p4ssword' -X GET

Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: text/plain;charset=UTF-8
Content-Length: 7
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
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

RUNNING

Maintenance stages description

Status Description

Status	Description
`RUNNING`	There is no maintenance. User requests are processed normally
`STOPPING`	Application prepares for maintenance. Ongoing requests are being completed. New data cleansing requests result in 503 HTTP code
`STOPPED`	Application has been stopped and maintenance has begun. No requests are being processed and administrative work can begin. New data cleansing requests result in 503 HTTP code
`RELOADING`	Dictionaries are being reloaded. New data cleansing requests result in 503 HTTP code
`ERROR`	Reloading dictionaries has failed. The administrator should repair new dictionaries or restore old ones and reload them again. New data cleansing requests result in 503 HTTP code

RUNNING

There is no maintenance. User requests are processed normally

STOPPING

Application prepares for maintenance. Ongoing requests are being completed. New data cleansing requests result in 503 HTTP code

STOPPED

Application has been stopped and maintenance has begun. No requests are being processed and administrative work can begin. New data cleansing requests result in 503 HTTP code

RELOADING

Dictionaries are being reloaded. New data cleansing requests result in 503 HTTP code

ERROR

Reloading dictionaries has failed. The administrator should repair new dictionaries or restore old ones and reload them again. New data cleansing requests result in 503 HTTP code

Additionals

We can customize DQ to return additional information according to Your needs. For more information contact our support at support@algolytics.pl.