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.

  1. 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.

  2. 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 your x-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:

  1. First Retry: Wait 1 second before retrying.
  2. Second Retry: Wait 2 seconds before retrying.
  3. Third Retry: Wait 4 seconds before retrying.
  4. Fourth Retry: Wait 8 seconds before retrying.
  5. 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:

  1. 200 OK: This response signifies that the API is operating as expected or with some reduced functionality. The status property in the response body will be set to Healthy or Degraded.

  2. 503 Service Unavailable: This response means that the API is currently unable to handle the request. The status property in the response body will be set to Unhealthy.

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:

  1. 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
    
  2. 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
    
  3. 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:

  1. Autocomplete Municipalities: Start by using the GET /v1/municipalities/autocomplete endpoint to search for municipalities. This is a GET request that requires a query parameter phrase 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
    
  2. 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 parameter municipalityCode, which is the unique identifier (code) of the municipality obtained from the GET /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
    
  3. 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:

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": []
}