Atoka API User Reference
v20241007.0859Real 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.
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 itemsGet just the list of real estate matched, or the search facets (or both!).
If you set this to value
none
, you'll get just themeta
object, with count of real estate matching your search criteria.Accepts multiple values, separated with
,
(comma) char: will match on any value (logicOR
).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 (logicOR
).Possible values are:
*
Enable all the facets of all the requested packagesbase.*
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:
curl -G "https://api.atoka.io/v2/realestate" -d "fields=items"
When fields
is facets
, the response will be:
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 (logicOR
).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:
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 10This is the number of individual objects that are returned in each page.
Use a number between 0 and 50.
-
offset integer,
default is 0This 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 (logicOR
).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 itFind 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 (logicOR
).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
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 (logicOR
).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 (logicOR
).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:
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.
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.