Atoka API User Reference

v20240416.0917

Real Estate Search

This API allows you to search for real estate.

https://api.atoka.io/v2/realestate

All requests must be properly authenticated.

Authentication

Parameters

  • token string required

    All requests must be properly authenticated; see the Authentication section for more info

curl -G "https://api.atoka.io/v2/realestate"

Debug

Use these parameters when you need to understand how your request was evaluated by the API.

Parameters

  • explain boolean,
    default is false

    When using this parameter in your request you'll get and additional property in the results explanation, that contains all the filters actually used during the query.

    Mostly useful for debugging purposes.

curl -G "https://api.atoka.io/v2/realestate" -d "explain=true"

Response modifications

When explain is true, the response will be:

curl -G "https://api.atoka.io/v2/realestate" -d "explain=true"

Response

By default this API endpoint returns the list of real estate matching the selected criteria.

Using these parameters, you'll be able to customize the output you'll get from your searches.

Parameters

  • fields array,
    default is items

    Get just the list of real estate matched, or the search facets (or both!).

    If you set this to value none, you'll get just the meta object, with count of real estate matching your search criteria.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • items
    • facets
    • none

  • facetFields array

    We want to keep our API as fast as possible, but facets are expensive to compute. To avoid slowing things down, you must explicitly state which facets you want when you request them. We want to make your life as simple as possible, though, that's why we support wildcards to be used in here; with them you will be able to have an initial look at the data, and to explicitly specify the facets you need once you start developing your application.

    This field is required when requesting the search facets through the fields parameter

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • * Enable all the facets of all the requested packages
    • base.* Enable all the facets of the package "base"
    • base.address.macroregion
    • base.address.municipality
    • base.address.province
    • base.address.region
    • base.landType
    • base.type
curl -G "https://api.atoka.io/v2/realestate" -d "fields=items,facets" -d "facetFields=base.*"

Response modifications

When fields is items, the response will be:

{
"items": [
{
"id": "6da785b3adf219770c9e",
"fullAddress": "foo"
},
...
],
"meta": {
"ordering": "default",
"count": 57,
"limit": 10,
"offset": 30,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}
curl -G "https://api.atoka.io/v2/realestate" -d "fields=items"

When fields is facets, the response will be:

{
"facets": {
},
"meta": {
"count": 34,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}
curl -G "https://api.atoka.io/v2/realestate" -d "fields=facets"

Data packages

This parameter allows you to control the information you want to retrieve about each real estate.

If you have special needs and want to further customize the data returned, we can adapt the output to your specific needs: just get in touch with us at sales@atoka.io.

Parameters

  • packages array

    Fine tune the results to the level of detail your application actually requires.

    The extraction cost per single real estate will be multiplied to the number of results in your query (up to offset parameter value).

    To avoid using any package, don't pass this parameter and the results will contain just the Atoka Real Estate ID (and little more).

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • base
    • owners
    • * (use all the data packages you have an active subscription for)
curl -G "https://api.atoka.io/v2/realestate" -d "packages=*"

Response modifications

When packages is *, the response will be:

{
"items": [
{
"id": "6da785b3adf219770c9e",
"fullAddress": "foo",
"cervedId": 2044622,
},
...
],
"facets": {
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
],
"meta": {
"ordering": "default",
"count": 57,
"limit": 10,
"offset": 30,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}
curl -G "https://api.atoka.io/v2/realestate" -d "packages=*"

Ordering & Pagination

To download long lists of results you can paginate returned items using these parameters.

You can also decide the order in which items are returned.

Parameters

  • limit integer,
    default is 10

    This is the number of individual objects that are returned in each page.

    Use a number between 0 and 50.

  • offset integer,
    default is 0

    This offsets the start of each page by the number specified.

    Use a number between 0 and 9950.

  • ordering string,
    default is "sizeDesc"

    Selects the order in which results are returned.

    Choose only one among:

    • atoka
    • size
    • sizeDesc
curl -G "https://api.atoka.io/v2/realestate" -d "limit=10" -d "offset=30" -d "ordering=sizeDesc"

General info

Here are listed some base filters on Real Estate, such as their type or their cadastral information

Parameters

  • type array base

    Find real estate of the specified type.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • building
    • plotOfLand

  • ids array

    Search via already known Atoka Real Estate IDs.

    Accepts multiple values, separated with , (comma) char.

  • countries array,
    default is it

    Find locations based in the specified countries.

    For the moment the only country covered is Italy (it).

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • it

  • macroregions array base

    Match real estate in the given macroregions.

    Accepts multiple values, separated with , (comma) char.

  • regions array base

    Match real estate in the given regions.

    Accepts multiple values, separated with , (comma) char.

  • provinces array base

    Match real estate in the given provinces.

    Accepts multiple values, separated with , (comma) char.

  • municipalities array base

    Match real estate in the given municipalities.

    Accepts multiple values, separated with , (comma) char.

  • companies array base

    Search via already known Atoka Company IDs.

    Accepts multiple values, separated with , (comma) char.

  • people array base

    Search via already known Atoka People IDs.

    Accepts multiple values, separated with , (comma) char.

curl -G "https://api.atoka.io/v2/realestate"

Response

The response of the real estate

{
"items": [
{
"id": "6da785b3adf219770c9e",
"fullAddress": "foo",
"cervedId": 2044622,
},
...
],
"facets": {
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
],
"meta": {
"ordering": "default",
"count": 57,
"limit": 10,
"offset": 30,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}

Real Estate Details

Show full details of a real estate item.

By default we show all information available using all the data packages you subscribed to. Use the package parameter to fine tune the output format.

If you have special needs and want to further customize the data returned, we can adapt the output to your specific needs: just get in touch with us at sales@atoka.io.

https://api.atoka.io/v2/realestate/{id}

Replace {id} with The Atoka Real Estate ID you want details for (as returned by the [Real Estate Search](#realestate) API endpoint. .

All requests must be properly authenticated.

Authentication

Parameters

  • token string required

    All requests must be properly authenticated; see the Authentication section for more info

curl -G "https://api.atoka.io/v2/realestate/{id}"

Response

By default this API endpoint returns the list of real estate matching the selected criteria.

Using these parameters, you'll be able to customize the output you'll get from your searches.

Parameters

  • allowExpensive array

    Some fields could expensive to be computed and returned; either they are computationally costly (like calling and external API), or they are charged extra fees, or both. Such fields must be explicitly enabled through this parameter.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • cervedIndicators.cgs
    • cervedIndicators.cgr
    • cervedIndicators.negativities
    • cervedIndicators.procurement
curl -G "https://api.atoka.io/v2/realestate/{id}" -d "allowExpensive=cervedIndicators.cgs"

Data Packages

Differently from the Real Estate Search API, by default here in the Real Estate Details API we will return all the information you are allowed to see; this may become expensive, of course.

To avoid getting data you don't need, you can use the packages parameter to fine tune the results to the level your application actually requires; if you want to explicitly get all the data, feel free you use our preferred wildcard: packages=*.

Remember: your subscription gives you access to different levels of detail in data returned!

If you have special needs and want to further customize the data returned, we can adapt the output to your specific needs: just get in touch with us at sales@atoka.io.

Remember: your subscription gives you access to different levels of detail in data returned!

Parameters

  • packages array,
    default is *

    By using this parameter you can fine tune the results to the level of detail your application actually requires.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • base
    • owners
    • * use all the data packages you have an active subscription for
curl -G "https://api.atoka.io/v2/realestate/{id}" -d "packages=*"

Response modifications

When packages is *, the response will be:

{
"item": {
"id": "6da785b3adf219770c9e",
"fullAddress": "foo",
"cervedId": 2044622,
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}
curl -G "https://api.atoka.io/v2/realestate/{id}" -d "packages=*"

Debug

Use these parameters when you need to understand how your request was evaluated by the API.

Parameters

  • explain boolean,
    default is false

    When using this parameter in your request you'll get and additional property in the results explanation, that contains all the filters actually used during the query.

    Mostly useful for debugging purposes.

curl -G "https://api.atoka.io/v2/realestate/{id}" -d "explain=true"

Response modifications

When explain is true, the response will be:

curl -G "https://api.atoka.io/v2/realestate/{id}" -d "explain=true"

Response

Real Estate details output.

{
"item": {
"id": "6da785b3adf219770c9e",
"fullAddress": "foo",
"cervedId": 2044622,
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}