Getting started
Welcome to the Context Layer documentation. Use the left navigation to browse endpoints and guides.
Environments
https://context.realitycs.it
https://sandbox-context.realitycs.it
All the requests do require an OAUTH 2.0 auth token in the header, see the authentication page for details.
What the service does
Context Layer describes what surrounds a point: the amenities and transport reachable from it, who lives there, how the area is built and used, and how busy its roads are. There is nothing to create and no state to keep: you pass a latitude and a longitude, and you get the context back.
| Endpoint | Content |
|---|---|
| Full context | Every block below in a single call, plus two exclusive fields |
| Services | Amenities around the point, by category |
| Transport | Public transport stops around the point |
| Population | Demographics of the census area |
| Buildings | Building stock: age, size, condition, density |
| Land use | Breakdown of the land use, and the prevailing one |
| Traffic | Traffic intensity |
| Roads | Breakdown of the road types |
| Services by zone | Nearest amenities, with no radius |
| Transport by zone | Nearest transport hubs, with no radius |
Request format
Every endpoint is a GET and takes its parameters in the query string. There is no request body.
curl --location 'https://sandbox-context.realitycs.it/contesto/servizi?latitudine=43.32215&longitudine=11.3259&raggio=250' \
--header 'Authorization: Bearer <token>'
Common request fields
| Field | Required | Default | Description | Type | Example | Notes |
|---|---|---|---|---|---|---|
latitudine | yes | Latitude of the point | number | 43.32215 | ||
longitudine | yes | Longitude of the point | number | 11.3259 | ||
raggio | optional | 500 | Search radius around the point, in metres | number | 250 | From 1 to 1000, see below |
raggio is capped at 1000 metres
Values outside the 1 to 1000 range are rejected with 422 and the message "Il campo raggio può essere compreso tra 1 e 1000 metri". There is no way to widen the search beyond one kilometre: if you need the nearest amenities regardless of distance, use Services by zone and Transport by zone instead, which ignore the radius entirely.
Radius endpoints and zone endpoints
The service answers the same question in two different ways, and the two are not interchangeable.
| Radius endpoints | Zone endpoints | |
|---|---|---|
| Question | What is within N metres? | What are the nearest ones? |
raggio | Honoured, 1 to 1000 m | Accepted but ignored |
| Result size | Everything found, up to 500 per category | 10 per category, 3 for the distant ones |
| Empty area | Categories come back empty | Always returns the nearest, however far |
Use the radius endpoints to characterise a neighbourhood, and the zone endpoints to answer "where is the closest station" without knowing in advance how far it is. In the examples of Transport by zone the nearest airport is more than 6 km away, a distance no radius endpoint could ever reach.
The zone endpoints also cover wider categories
They are not just the same data without a radius. Transport by zone adds aeroporto, porto and casello_autostradale, and Services by zone adds ufficio_postale — categories that the radius endpoints never return, since they rarely fall within a kilometre.
Response format
Every response is wrapped in a single contesto key, with one sub-block named after the topic (servizi, trasporti, popolazione, edifici, destinazione_uso, strade, traffico_intensita). There is no _metadata envelope.
{
"contesto": {
"servizi": {}
}
}
Empty categories are null, not []
When a category has no result, the key is present but set to null rather than to an empty array. Iterating over the categories without a null check will fail on the first area that has no university or no hospital, which is the common case at small radii.
Points of interest
Across Services, Transport and their zone variants, every point of interest has the same shape:
- nome: Name of the place, in capitals.
- distanza: Distance from the requested point, in metres.
- geojson: Geometry of the place, as standard GeoJSON with
typeandcoordinates. - tag: Sub category. Only returned inside
negozio, with values such asabbigliamento,bellezzaandservizi.
geojson is not always a Point
Most places are returned as a Point, with coordinates ordered longitude first, then latitude. But parcheggio on Services comes back as a MultiPolygon tracing the outline of the car park, with coordinates nested four levels deep.
Branch on geojson.type instead of assuming a point. Note also that the same category is not consistent across endpoints: parcheggio is a MultiPolygon on Services but a Point on Services by zone.
Statistical blocks
Population and Buildings follow a different convention from the rest of the service: each entry is an object carrying a qt value and a desc label in Italian, keyed by its ISTAT census code (p1, pf3_perc, e8_perc). Keys ending in _perc are percentages, the others are absolute counts.
Because every entry describes itself through desc, those blocks can be rendered without hardcoding the key names.
Errors
Validation failures answer 422 with an error code and a message array, one entry per offending field:
{
"error": "input_validation_error",
"message": [
{
"type": "field",
"value": "abc",
"msg": "Il campo raggio può essere compreso tra 1 e 1000 metri",
"path": "raggio",
"location": "query"
}
]
}
| Status | Description |
|---|---|
| 200 | Success |
| 401 | Missing, invalid or expired access token |
| 422 | Missing or malformed parameters |
location can be misleading
Every parameter of this service travels in the query string, but a missing latitudine is reported with "location": "body". Read path to know which field is at fault, and ignore location.
Changes
All updates to the endpoints are tracked in the Changelog.