API Manual
About the API
This API provides a robust interface to our real estate data and services. It has been designed to provide developers with a convenient, flexible, and powerful way to access and manipulate real estate data, enabling the creation of varied applications that leverage our rich database.
Built using REST principles, our API uses standard HTTP methods and status codes, which makes it easy to use with your favorite HTTP client or language-specific library. The API accepts and returns JSON formatted data, allowing for easy integration with existing data structures in your application.
The API uses the open standard for API specifications - OpenAPI (formerly Swagger), providing a clear and concise description of the API endpoints, parameters, and responses.
Authorization
To interact with most of our API endpoints, an API key is required for the authorization process. This key is used to authenticate your application for each API request, ensuring that only authorized clients have access to the API endpoints. Some endpoints like GET /_health
do not require an API key and can be accessed without any authorization.
When making a request to any endpoint that requires authorization, you need to include your API key in the header of the HTTP request. The key should be attached as the value of the x-api-key
field. Here is an example of how to include it:
GET /v1/endpoint
x-api-key: YOUR_API_KEY
In the example above, you should replace YOUR_API_KEY
with your actual API key. If your API key is missing, unknown, or disabled, you will receive a 401 Unauthorized
response from the server with a FailedAuthorization
object in the response body, detailing the reason for the failed authorization.
Remember, always keep your API key secret and never expose it in any public client-side code.
Testing API
To facilitate easy testing of our API, we provide two methods to execute requests in a test mode. These testing requests do not affect your quotas or any production data. Please note that while the responses generated in test mode mimic the format of production responses, the actual content may be placeholder data and not reflect real-time information.
Testing API Key: You can use a special testing API key that always operates in a test mode. This key should be included in the
x-api-key
field in the header of your HTTP requests, just like a standard API key.Here's an example:
GET /v1/endpoint x-api-key: YOUR_TEST_API_KEY
Replace
YOUR_TEST_API_KEY
with your actual testing API key.Testing HTTP Header: Alternatively, you can use your production API key with additional HTTP header
x-api-test: true
in your request. This will put your request in test mode.Here's an example:
GET /v1/endpoint x-api-key: YOUR_API_KEY x-api-test: true
Replace
YOUR_API_KEY
with your actual API key.
Both methods allow you to test the full capabilities of our API without affecting your quotas or production data. We recommend testing all integrations thoroughly before switching to production mode.
Handling Responses and Errors
Our API uses standard HTTP status codes to indicate the success or failure of a request. The status codes are accompanied by a response body that provides additional details about the result of the operation. Implementors must handle each different response state individually to ensure proper functionality and user experience.
Success Responses
200 OK
: The request has succeeded. The meaning of a success varies depending on the HTTP method:GET
: The resource(s) has been fetched and is transmitted in the message body.POST
: The resource describing the result of the action is transmitted in the message body.
No retries should be attempted for these responses.
Client Error Responses
401 Unauthorized
: The request has not been applied because it lacks valid authentication credentials for the target resource. Check yourx-api-key
for any possible mistakes.429 Too Many Requests
: The client has sent too many requests in a given amount of time ("rate limiting").
Retries should never be attempted for 4xx responses, as the issue lies with the request itself and must be corrected by the client.
Server Error Responses
500 Internal Server Error
: The server encountered an unexpected condition that prevented it from fulfilling the request.503 Service Unavailable
: The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. This status code may also be used when one of our external data providers is unavailable.
Retries can be attempted for 5xx responses, but it's important to implement an exponential backoff strategy to avoid overwhelming the server. Here is a basic guideline for retries:
- First Retry: Wait 1 second before retrying.
- Second Retry: Wait 2 seconds before retrying.
- Third Retry: Wait 4 seconds before retrying.
- Fourth Retry: Wait 8 seconds before retrying.
- Fifth Retry: Wait 16 seconds before retrying.
Handling Inaccessible API
In cases where the API is completely inaccessible (e.g., due to network issues or server downtime), implement a retry strategy with exponential backoff as described above. Additionally, consider implementing a maximum retry limit to prevent infinite retry loops and inform the user that the service is currently unavailable.
Best Practices
- Always log error responses for debugging and monitoring purposes.
- Implement user-friendly error messages to provide clear feedback.
- Use appropriate HTTP status codes in your own API responses to ensure consistent behavior.
By following these guidelines, you can ensure a more reliable and user-friendly interaction with our API, even in the face of errors and network issues.
Health Check
Our API provides a health check feature that can be accessed by sending a GET request to the GET /_health
endpoint. This feature offers a simple way to ascertain the current operational status of our API.
The health check will return a status code along with a response object containing the status
property, which reflects the API's health status.
There are two primary responses that you can anticipate from this feature:
200 OK
: This response signifies that the API is operating as expected or with some reduced functionality. Thestatus
property in the response body will be set toHealthy
orDegraded
.503 Service Unavailable
: This response means that the API is currently unable to handle the request. Thestatus
property in the response body will be set toUnhealthy
.
Here is a sample response when the API is healthy:
{
"status": "Healthy"
}
Here is a sample response when the API is in a degraded state:
{
"status": "Degraded"
}
And here is a sample response when the API is unhealthy:
{
"status": "Unhealthy"
}
Degraded State
The Degraded
state is a special condition under the 200 OK
status code. When the API is in a Degraded
state, it implies that while the API is still functioning, certain services or data it relies on may be unavailable. This can result in reduced functionality or performance of the API.
It's important to understand that not all endpoints will be impacted by the Degraded
state. Some endpoints may still operate correctly. This is because the Degraded
state is often associated with specific services or external data providers that the API depends on. If these services or data providers are unavailable, only the endpoints that rely on them will be affected.
Therefore, when the health check feature indicates a Degraded
status, it is advisable to review the specific API endpoints you are using and understand if they rely on the services or data that may be affected.
Quotas and Limits
Our API incorporates a quota system as part of its request management strategy. The specifics of these quotas are determined by the individual contracts we establish with our clients.
There are three types of quotas available:
estimations.create.daily
estimations.create.weekly
estimations.create.monthly
These quotas respectively limit the number of estimation creation operations you can perform within a day, week, and month.
Quotas Endpoint
You can view your current quota usage by sending a GET request to the GET /v1/quotas
endpoint. This endpoint returns a list of all your quotas and their current usage.
Automatic Headers
When you make API requests, the API automatically includes HTTP headers in the responses. These headers provide information about your quota limits and the remaining number of operations you can perform within the quota's time period. The headers for each quota follow the pattern of x-{quota-name}-limit
and x-{quota-name}-remaining
where {quota-name}
is the quota name with dots replaced by dashes. If there is no limit applied, the value is -1.
Testing Requests
Testing requests do not impact any of your quotas.
Quota Periods
Our quotas are not tied to the calendar but operate on a rolling basis. This means, for example, that the estimations.create.daily
quota counts the number of operations performed over the past 24 hours from the current time, rather than resetting at midnight each day. The same principle applies to the weekly and monthly quotas, which roll back 7 and 30 days, respectively.
Getting the Correct Address
Before proceeding with calculations for flats, houses, and lands, it is essential to obtain the correct location information. Our API uses RÚIAN addresses for these estimations. Note that lands always require a RÚIAN municipal part code. On the other hand flats and houses typically require a specific address RÚIAN code.
Exception to this rule can be made per specific use case for your application. In such cases, please contact us for further assistance. This will allow you to calculate flats and houses even when you don't know a specific address. Using only the municipal part code for flats and houses is also available when sending test requests.
Using External Provider
Developers have the option to quickly start developing by utilizing external providers like Smartform, Foxentry, or any other address provider that offers ready-to-use form input fields that are easy to implement. This approach allows for a streamlined and efficient integration process.
If you prefer to manually implement everything using our API, proceed to the next section for detailed instructions.
Implementing Address Search Manually
The workflow to get the address involves two steps:
Autocomplete endpoint (
GET /v1/addresses/autocomplete
): This endpoint helps in fetching possible address suggestions based on the input phrase. The endpoint requires a phrase query parameter, which should be part of the address you are looking for. It responds with a list of suggested addresses, which could be either concrete or generic depending on the clarity of the input phrase. If a concrete address is found in the suggestions, you can use it as input for the next step. Otherwise, refine your search phrase and repeat this step.Here is an example of how to use this endpoint:
GET /v1/addresses/autocomplete?phrase=YOUR_SEARCH_PHRASE
Validation endpoint (
GET /v1/addresses/validate
): Once you have a concrete address, this endpoint is used to validate the address and fetch its RÚIAN address id. The endpoint requires a phrase query parameter, which should be the exact address obtained from the autocomplete endpoint. It responds with the validated address and its RÚIAN address id.Here is an example of how to use this endpoint:
GET /v1/addresses/validate?phrase=YOUR_CONCRETE_ADDRESS
Calculate Flats and Houses: Once you have the correct address, you can use its RÚIAN id (
code
) for flats and houses estimation calculations.
In the end, remember to replace YOUR_SEARCH_PHRASE
with the part of the address you are searching for, and YOUR_CONCRETE_ADDRESS
with the exact address you obtained from the autocomplete endpoint.
Validating Known Address
If you already know the specific address, including the street name, house number, and municipality, you can bypass the autocomplete step and directly use the validation endpoint to obtain the RÚIAN address code.
Tip: For best results, include the zip code (postal code) if available.
Test the Workflow:
Getting the Correct Municipal Part
The correct municipal part is necessary for calculating land estimations. For flats and houses, a specific address is needed instead. Here is the workflow to get the correct municipal part:
Autocomplete Municipalities: Start by using the
GET /v1/municipalities/autocomplete
endpoint to search for municipalities. This is a GET request that requires a query parameterphrase
representing the name of the municipality. The response will be a list of municipalities matching the phrase. Each municipality will have a unique identifier (code
), the municipality's name (name
), and the district name (districtName
).Here is an example of how to use this endpoint:
GET /v1/municipalities/autocomplete?phrase=YOUR_SEARCH_PHRASE
List Municipal Parts: After choosing a municipality from the autocomplete results, use the
GET /v1/municipal-parts
endpoint to list all parts in the selected municipality. This is a GET request that requires a query parametermunicipalityCode
, which is the unique identifier (code
) of the municipality obtained from theGET /v1/municipalities/autocomplete
endpoint. The response will be a list of parts in the selected municipality. Each part will have a unique identifier (code
) and the name of the part (name
).Here is an example of how to use this endpoint:
GET /v1/municipal-parts?municipalityCode=MUNICIPALITY_CODE
Calculate Lands: Once you have the correct municipal part from the list, you can use its RÚIAN id (
code
) for land estimation calculations.
Remember to replace YOUR_SEARCH_PHRASE
and MUNICIPALITY_CODE
with the actual values.
Test the Workflow:
Calculating Estimations
The POST /v1/estimations
endpoint is used to calculate estimations for various types of properties, including flats, houses, and lands. The HTTP POST method is used to send the request.
The request body should be structured according to the CreateEstimationRequest
schema, which includes several properties. Here are some of the key properties:
languageCode
: An ISO 639-1 language code (e.g., 'cs').currencyCode
: An ISO 4217 currency code (e.g., 'CZK').category
: The category of the property.propertyType
: The type of the property (e.g., 'Flat', 'House', 'Land').area
: The living area excluding balcony, loggia, terrace, cellar, garden, etc. It includes basement, stairs, and other areas in the main building when calculating the estimation for houses.
Depending on the category and property type, additional information is required:
- For flats and houses, you need to provide the
addressCode
, which is the RÚIAN address code. This can be obtained using theGET /v1/addresses/autocomplete
andGET /v1/addresses/validate
endpoints. - For lands, you need to provide the
municipalPartCode
, which is the RÚIAN municipal part code. This can be obtained using theGET /v1/municipalities/autocomplete
andGET /v1/municipal-parts
endpoints.
Remember to refer to the CreateEstimationRequest
schema for a complete list of properties and their applicability to specific property types. Examples for different types of properties are provided in the API documentation to guide you on how to structure your request body.
Important notes:
- Carefully review the Swagger documentation and provided examples for this endpoint. You can find them at
POST /v1/estimations
. - Use the provided examples as the minimum set of scenarios your API client must be able to handle before publishing your application to end-users.
- The list of examples does not cover all possible variants and combinations of parameters the endpoint accepts. Be prepared to handle additional scenarios as needed.
Processing Different Response States
The POST /v1/estimations
endpoint provides various kinds of responses based on the input data and internal processing. Implementors must handle each different response state individually to ensure proper functionality and user experience.
Warnings
The API might need to adjust certain input data for successful calculation, such as prefilled missing fields or nullified unsupported fields. In such cases, the warnings
field in the response body includes a list of warning messages detailing these adjustments. These warnings do not inhibit the calculation process but provide you with insights to refine the input data for more accurate estimations.
What to show your users: Result price should be displayed to the user. List of warnings is intended to be read only by developers.
Example Response:
{
"id": "00000000-0000-0000-0000-000000000000",
"name": "Dům, prodej, 2+kk a méně, 66 m², pozemek 333 m², Nad náměstím 84, Praha / Řeporyje okres Hlavní město Praha",
"result": 12851700,
"isTesting": false,
"isAtypical": false,
"atypicalReasons": [],
"warnings": [
"'Disposition' was replaced with 'TwoPlusKitchenetteOrLess' because property type 'House' does not support value 'OnePlusKitchen'."
]
}
Note: The warnings
list can change over time, but the changes will not affect the calculated result
. Implementors should monitor the warnings
and ideally make changes to their API clients based on the suggestions provided in the warnings
list. The warnings
may also indicate potential changes that will be introduced in future API versions.
Atypical Estimations
In certain cases, our algorithm may not be able to automatically calculate the estimation. For example, if the flat living area is too large for the provided disposition. In such scenarios, the response will still be 200 OK
, but the isAtypical
field in the response body is set to true
, and the result
field will always be a zero. The atypicalReasons
field contains an array of human-readable reasons explaining why the automatic calculation was not feasible.
What to show your users: Atypical reasons should be displayed to the user instead of result price.
Example Response:
{
"id": "00000000-0000-0000-0000-000000000000",
"name": "Byt, prodej, 2+1, 55 m², Nad náměstím 84, Praha / Řeporyje okres Hlavní město Praha",
"result": 0,
"isTesting": false,
"isAtypical": true,
"atypicalReasons": [
"velké množství parkovacích míst"
],
"warnings": []
}
Note: The isAtypical
and atypicalReasons
properties can change over time as we continually improve our internal algorithm. It's essential to handle these reasons dynamically and be prepared for potential changes or additions in the future.
Successful Estimation
A successful response with status 200 OK
signifies that the estimation process completed without any issues. The response body contains the estimation data.
What to show your users: Result price should be displayed to the user.
Example Response:
{
"id": "00000000-0000-0000-0000-000000000000",
"name": "Dům, pronájem, 6 a více, 200 m², pozemek 200 m², Nitranská 855/10, Praha / Vinohrady okres Hlavní město Praha",
"result": 59200,
"isTesting": false,
"isAtypical": false,
"atypicalReasons": [],
"warnings": []
}