Automatic address completion
Automatic address completion
Address completion service
We offer you service for filling-in the missing elements of an address. You may use the service, for example, together with the automated export of property listings into the Real estate market Observer.
Pay attention, that all geographical entities up to the second level inclusive (regions and biggest cities) are explicitly defined in the system. When exporting data into the system, we recommend that you check compliance of second level geographical entities in your data with ScanRealty classification.
Service access
Access to the service is free. Before starting you need to receive your private access key.
Contact us and we will send you access key.
Service request
To complete an address you need to send an HTTP request to the page http://www.scanrealty.com/geographer/ together with the known elements, entered as GET-parameters.
Service request structure consist of the following elements:
country — country (see full list),
city — city or region (see full list for each country),
location — district or settlement,
address — additional address in a free form (for example, street name and house number),
lang — language (in ISO 639-2 format) that shall be used in response to express the names of geographical entities (optional parameter, default value: "eng", see full list of supported languages),
encoding — encoding that corresponds the request string data (optional parameter, default value: "UTF-8", however, when sending request data in a different encoding, you should indicate it),
key — your private key that grants you access to the service.
For example, we know country name ("Россия"), city name ("Москва") and address ("Рублевское шоссе, д. 1"), but do not know the district name. In this case our request shall look as follows:
http://www.scanrealty.com/geographer/?country=Россия&city=Москва&address=Рублевское шоссе, д. 1&lang=rus&encoding=windows-1251&key=your_private_key,
or like this:
Request may contain data in any language. All the elements should take their own place. If you can't determine which category does this or that element refer to, we recommend that you place it into the "address" parameter.
Service response
In response to request the service shall return an XML-file in UTF-8 encoding, with a structure consisting of the following elements:
response — grouping element, always exists,
code — service result code (see codes table below), always exists,
geography — grouping element, exists only when at least one geographical element is present,
country — country,
city — city or region,
location — district or settlement,
address — additional address in a free form.
You may see a response example by following the request example link.
Service functionality principles
When entered name of country is not known to the system, further address completion is considered impossible (code 300).
The service first tries returning the official name of a geographical entity in ScanRealty system in the requested language, then in case of failure — any of unofficial names.
When two or more geographical entities of the same level are found under requested address, the choice is considered impossible (code 300 with the names those geographical entities that were successfully found).
The service is self-learning, so if no answer was found for your request today, most likely it will appear some time later.
Service result code
All of the service result codes are listed below.
100 — address completed, all parameters defined,
105 — address completion is not required, all parameters are known,
200 — geographical data is missing in the request,
205 — request contains characters in wrong encoding,
210 — request length exceeds the allowed limit,
300 — could not define one or more parameters,
400 — key is invalid or absent,
405 — daily requests limit for your key is exceeded,
500 — service waiting period has expired,
505 — service not available,
510 — too many request to the service.