The RuralCheck API

Ask for a report from your own program or AI assistant. Name the checks you need and you get those. The API comes with every paid plan, with no limit on the number of reports.

Paid plans are not on sale yet, so API keys are available only to accounts that already have a paid plan.

Keys

Every request needs a key. Make a key on your account page. It is shown once, so copy it then. Send it with every request:

Authorization: Bearer rc_...

An account can hold several keys, one for each program that uses it. Revoke a key on the same page and it stops working at once.

Asking for a report

curl -X POST 'https://ruralcheck.eu/api/v1/reports?wait=30' \
  -H 'Authorization: Bearer rc_...' \
  -H 'Content-Type: application/json' \
  -d '{"lat": 48.015, "lon": 8.19, "checks": ["noise", "flood"]}'

Leave out checks for every check. With wait the request is held open for up to 30 seconds and returns the finished report. Without it, or if the report takes longer, the answer is 202 with an id. Fetch /api/v1/reports/{id}?wait=30 until status is done.

{
  "id": "07f64ea8874d",
  "status": "done",
  "checks": ["noise", "flood"],
  "runs": ["flood", "nuisances", "noise"],
  "modules": {"flood": {...}, "nuisances": {...}, "noise": {...}},
  "errors": {},
  "attribution": ["..."],
  "disclaimer": "..."
}

runs lists what was worked out. Some checks need another one first, and that answer is returned as well. Noise needs the list of roads and railways in nuisances, for example. While a report runs, modules holds the answers so far. Finished reports are kept for one day.

Add drawing=false to either request to leave out outlines, pictures and the horizon. Only a map needs those, and they are most of the size of an answer. attribution lists the sources the checks you asked for used.

Each check's answer is the same data the report on the map shows. GET /api/v1/sample returns a complete report to read before you write any code.

Checks

Ask for any set of the checks below. Some checks need another one first, and that one runs as well. The time is for the check alone. Checks asked for together share the ground they read, so together they take less than the sum.

Name	Check	Time
`municipality`	MunicipalityThe municipality, district and region the plot is in.	under 0.1 s
`parcel`	Land registerThe plot in the national land register: its outline, reference and area.	under 0.1 s
`settlements`	Village and townThe nearest hamlet, village and town, with distance and direction.	under 0.1 s
`remoteness`	People nearbyWhat kind of place it is, and how many people live within 1 km and 5 km.	0.1 s
`transit`	Public transportDistance to the nearest bus stop, station, tram, ferry and airport.	0.4 s
`amenities`	Shops/servicesShops and services within reach, grouped by kind.	under 0.1 s
`swimming`	Bodies of waterBodies of water nearby that a road or path reaches: lakes, rivers, the sea, beaches and pools, with the size of each.	0.5 s
`forest`	TreesThe woods around the plot, and which of them are bare in winter.	0.1 s
`economy`	Local economyHousehold income, unemployment and population change, against the country.	under 0.1 s
`visitors`	VisitorsVisitor nights per resident in the district, and the months they come in.	under 0.1 s
`wildfire`	WildfireMapped wildfires nearby, and the date the record was last updated.	under 0.1 s
`flood`	FloodingWhether a once-a-century river flood reaches the plot. Flood defences not included.	0.1 s
`protected`	Protected areasNature protection areas the plot is in, and those within 5 km.	0.1 s
`landslide`	LandslidesThe official landslide or rockfall hazard zone the plot is in, in the national authority's own classes.	0.1 s
`avalanche`	AvalanchesThe official avalanche zone or known avalanche path the plot is in, in the authority's own classes.	under 0.1 s
`seismic`	EarthquakeEarthquake shaking for the region, on rock.	under 0.1 s
`air`	Air qualityFine particles, traffic fumes and summer ozone, against the WHO guideline.	under 0.1 s
`pollen`	PollenBirch, olive, grass and ragweed pollen: the months each is in the air, and how much against the rest of Europe.	under 0.1 s
`nightsky`	Night skyHow dark the night sky is at the plot.	under 0.1 s
`snow`	SnowDays a winter with snow on the ground since 2001, and when it settles and goes.	under 0.1 s
`groundwater`	GroundwaterThe nearest recorded water levels in wells and boreholes, and the aquifer below.	0.1 s
`emergency`	EmergencyThe nearest fire station and ambulance station on the map, with the drive to each without traffic.	0.4 s
`drive_times`	Drive timesDrive times without traffic to the nearest places and shops, added to the settlements, amenities and emergency rows.	0.4 s
`access`	Paths on the plotPaths across the plot and whether a road reaches it, from the map.	0.2 s
`terrain`	TerrainSlope, aspect, position on the slope and the risk of a frost pocket.	1.1 s
`sealevel`	Coastal floodingWhether a once-a-century storm tide reaches the plot, now and with the sea higher. Gates and pumps not included.	0.1 s
`growing`	What grows hereFrost dates, frost-free days, growing season and vine warmth at the plot itself.	1.5 s
`climate`	Climate in 2050Frost, growing season, heat, rain and dry spells today and around 2050.	1.5 s
`insects`	Bites and stingsBites and stings, nearest first: when ticks, mosquitoes and midges are about, and other kinds recorded nearby.	1.9 s
`wildlife`	Wild animalsWolves, bears, lynx and golden jackals in the plot's 10 km square, and modelled wild boar.	under 0.1 s
`nuisances`	NuisancesMain roads, railways, quarries, farms and similar within 5 km, and whether the land hides each one.	1.2 s
`noise`	NoiseEstimated road and rail noise at the plot, allowing for hills in between.	1.2 s
`aircraft`	AircraftWhether the plot is in line with the runway of an airport with commercial flights, and the nearest airfield.	under 0.1 s
`connectivity`	InternetPhone signal and internet at the plot, as the national regulator publishes them.	under 0.1 s
`planning`	Planning zoneThe zone of the local plan the plot is in, the plan, its date and a link to it.	0.1 s
`wind`	WindHow windy the area is, where the wind comes from, and shelter at the plot.	1.2 s
`roadin`	Access roadThe drive from the nearest town: its steepest stretch, total climb, road surfaces and any winter closure on the map.	0.9 s
`sun`	SunSun hours at the plot through the year, allowing for the hills and for cloud.	7.1 s
`solar`	Solar panelsExpected yield of solar panels at the plot, allowing for the horizon.	7.1 s
`view`	ViewHow far the view runs in each direction, and how much land is in view.	4.3 s
`in_view`	What is in viewWhich named places, water and possible nuisances can be seen from the plot.	4.4 s

Endpoints

POST /api/v1/reports: Ask for a report on a point. Key needed.
GET /api/v1/reports/{id}: Progress, or the finished report. Key needed.
GET /api/v1/checks: Every check, with what it holds and how long it takes. Key needed.
GET /api/v1/coverage?lat=&lon=: Whether reports are made for a point. Key needed.
GET /api/v1/search?q=: Find a town or village by name. Street addresses are not searchable. Key needed.
GET /api/v1/sample: The sample report. Key needed.
POST /api/v1/listings: Send up to 2,000 listings as {"name", "listings": [{"name", "lat", "lon", "reference"}]}. Each one becomes a saved plot with a full report and a client link. 100 run from one upload, one after another, and every listing that is not run says why. Professional plan.
GET /api/v1/listings/{id}: An upload's progress: each listing's status, its client link, or the reason it was not run. GET /api/v1/listings lists your uploads.

Saved plots

The plots your account keeps, their folders and the Trash. Key needed for each.

GET /api/v1/plots?folder_id=&in_trash=: Your saved plots, newest first, with the key figure of each check. Plots in the Trash are listed only with in_trash=true.
GET /api/v1/plots/{id}: One plot, with its report as it was kept.
POST /api/v1/plots: Keep a finished report: {"report_id": "…", "name": "…", "folder_id": 3}. Only a report run with every check can be kept.
PATCH /api/v1/plots/{id}: Change name, note or folder_id. A folder_id of null takes the plot out of its folder.
DELETE /api/v1/plots/{id}: Move a plot to the Trash. It is deleted for good 30 days later, after the date in deleted_after. The API cannot delete a plot at once.
POST /api/v1/plots/{id}/restore: Take a plot out of the Trash, back into its folder.
GET, POST /api/v1/folders PATCH, DELETE /api/v1/folders/{id}: List, make, rename and delete folders. Deleting a folder keeps its plots.

The full description, for code generators and AI tools, is at /openapi.json.

Limits

One new report a minute for each account, and one running at a time. If you need more, ask us about the Business plan.
60 requests a minute for everything else, such as fetching a report, for each account, however many keys it holds.

Errors

Every refusal carries detail, one sentence you can show to a person as it is.

401: No key, or a key that is not valid.
402: The account is on the free plan. The API comes with the paid plans.
404: No report, plot or folder with that id on this account.
409: Reports are not available for this location. The body also carries coverage. For a plot or folder, the change is not possible as it stands, and detail says why.
422: The request is not valid. An unknown check name also returns the list of valid names in valid.
429: A limit was reached. Retry-After says how many seconds to wait.

AI assistants

Our MCP server gives an assistant the same checks as tools. The assistant can then look a place up, check that reports are made there, and ask for the checks your question needs. Connect an assistant

Using the results

Results from the API are for your own use, the same as a report on the map. A program or assistant may read them for you. You may not pass them on to other people, show them in a website or app, or collect them to build a dataset. The sources in attribution have to stay with any copy you keep. The terms set this out in full.