Skip to content

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 type and coordinates.
  • tag: Sub category. Only returned inside negozio, with values such as abbigliamento, bellezza and servizi.

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.