# UK Ground Risk API - Coal Mining, Brine, Subsidence (`nabeelbaghoor/uk-ground-risk-mining-api`) Actor

Screen any UK location for coal mining, non-coal mining, brine and ground stability risk, with the mineral types behind a finding, plus mapped environmental datasets as GeoJSON over an area in British National Grid or WGS 84, and your own report orders, findings and invoices.

- **URL**: https://apify.com/nabeelbaghoor/uk-ground-risk-mining-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Real estate, Business, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $15.00 / 1,000 ground risk screening returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## UK Ground Risk API - Coal Mining, Brine, Subsidence

Ask whether the ground under a UK address is a problem, before a conveyancing search tells you it is.

### What it collects

- **Ground risk screening**: whether a location carries a coal mining risk, a non-coal mining risk, a brine risk or a ground stability issue, answered as clear flags for a point or a polygon.
- **Mining risk detail**: the same four subjects with the detail behind them, including the named mining types identified at the location and the minerals associated with each, which is what turns "a non-coal risk exists" into something you can act on.
- **Spatial features**: the provider's mapped environmental datasets as GeoJSON over a bounding box, with every attribute the dataset carries, returned in British National Grid, WGS 84 or Web Mercator regardless of which one you asked in.
- **Product catalogue**: what your account can order, with each product's name, code, price and delivery time.
- **Your own account history**: orders with their status, customer reference, location and completion date, the documents and JSON report findings attached to them, your invoices with totals, tax, currency and report counts, and your organisation record.

### FAQ

#### What is UK ground risk data used for?

Deciding whether a property needs a full environmental search, and pricing the risk when it does. Coal mining, brine extraction and historic non-coal workings are the subsidence risks that stop UK transactions, and screening an address for them takes seconds where ordering a report takes days. Conveyancers, lenders, insurers and developers all use the screen the same way: to triage a list down to the addresses that actually warrant the paid report.

#### What is the difference between the screening and the detail service?

The screening service answers four yes-or-no questions about a location: coal, non-coal, brine, ground stability. The detail service answers the same four and adds the mining types identified there and the minerals behind each one, so a non-coal finding arrives with the reason. Run the screen across a list, then run the detail on the ones that came back positive.

#### Does a "false" mean the data is missing?

No, and this actor is careful about the difference. A false flag is the provider saying it checked and found no such risk at that location, which is the answer most callers are paying to get. A location it holds nothing at all for is a separate row that says so in plain words. Nothing turns a clear result into a blank.

#### How do I give it a location?

One per line, either a `latitude,longitude` pair or a well known text geometry such as `POINT(-0.1387 50.8233)` or a `POLYGON`. Well known text is the provider's own preferred form and is passed through untouched. Pairs are written latitude first, the way people write coordinates, and converted to the longitude-first order the geometry format expects, so a pair typed the natural way cannot silently become a real place somewhere else.

#### Which coordinate system does it use?

Whichever you choose, on both ends, and both travel on every row. The provider accepts British National Grid, WGS 84 and Web Mercator, and it will return the geometry in a different projection from the one you asked in, which is how you supply latitude and longitude and get British National Grid back. Both are recorded because the first two put the same numbers kilometres apart, and a coordinate that did not travel with its projection would not be a location at all.

#### Can this actor order a report and spend my money?

No. The provider publishes routes that create an order and change an organisation's settings, and none of them is wired up here. Every route this actor can reach is a read. That is a deliberate limit, because a scheduled run that could buy reports is a scheduled run that eventually will.

#### Can I read the findings from reports I have already bought?

Yes, which is the point of the account services. The order services list what you have ordered and the documents on each one, including the simplified JSON version of the report findings, so a report you paid for once becomes structured data you can query rather than a PDF in an inbox.

#### Why did a refusal tell me it was an actor bug rather than my key?

Because the gateway in front of this API answers two completely different problems with the same HTTP 403: a refused key, and a path that does not exist. Only the response body separates them. The actor reads the body, so a routing mistake on its side is reported as its own fault instead of sending you off to reissue a credential that was fine all along.

#### Do I need my own API key?

Yes. This actor is bring-your-own-key and never ships a key of its own. Paste your key from your provider account, or set it once as the DATA\_API\_KEY environment secret. The risk and account services take it as a header; the spatial data host only accepts it as a query parameter, because that host also serves map tiles to browsers, and the actor sends whichever each host expects rather than both.

#### What does it cost?

Pay per result. A ground risk screening row costs the most, because one row is a full answer about a location; a mapped feature costs well under half that, because a single area commonly returns many; reading your own orders and invoices costs less again; and the product catalogue is priced near zero, because finding out what something costs should not itself cost anything worth counting. Platform usage is included. Locations the provider holds nothing for are never charged.

### Example output

```json
{
  "recordType": "risk",
  "service": "miningRisk",
  "requested": "50.8233,-0.1387",
  "found": true,
  "inputProjection": "4326",
  "outputProjection": "4326",
  "coalRisk": false,
  "nonCoalRisk": true,
  "nonCoalTypes": ["Hydrocarbon"],
  "brineRisk": false,
  "groundStabilityRisk": true,
  "record": { "...": "every field the provider published, unchanged" }
}
```

### Keyword map

UK ground risk API, coal mining risk search, non-coal mining risk, brine subsidence risk, ground stability data, mining search API, environmental search data, conveyancing search API, UK property risk screening, subsidence risk by postcode, GeoJSON environmental data, British National Grid API, land use data UK, contaminated land screening, property due diligence API, mining report findings JSON, historic landfill data, UK environmental risk data API.

# Actor input Schema

## `service` (type: `string`):

Ground risk screening and mining risk detail answer whether a location carries a coal, non-coal, brine or ground stability risk. Spatial features returns the provider's mapped data as GeoJSON over an area. The remaining services read your own account: the product catalogue, your orders, the documents and JSON findings on them, and your invoices.

## `locations` (type: `array`):

One location per line, either a "latitude,longitude" pair or a well known text geometry such as POINT(-0.1387 50.8233) or a POLYGON. Pairs are written latitude first, the way people write coordinates, and converted to the longitude-first order the geometry format expects, so a pair typed the natural way cannot become a real place somewhere else.

## `boundingBoxes` (type: `array`):

One box per line for the spatial features service, as four comma separated numbers giving the south, west, north and east edges of the area. Each box becomes its own paged read.

## `dataset` (type: `string`):

Which mapped dataset the spatial features service should read. Which datasets your subscription covers comes from your provider account, so this is a free text field rather than a fixed list.

## `inputProjection` (type: `string`):

Which projection the bounding box you supply is written in. This is sent explicitly rather than left to a server default, because British National Grid and WGS 84 put the same numbers kilometres apart.

## `outputProjection` (type: `string`):

Which projection the returned GeoJSON should be in. It can differ from the projection of your request, which is how you supply latitude and longitude and get British National Grid back.

## `orderIds` (type: `array`):

One order id per line, for the single order and order documents services. Run the "Your orders" service first to collect them.

## `orderStatus` (type: `string`):

Filter your orders by status, as the provider labels them.

## `orderItemStatus` (type: `string`):

Filter your orders by the status of the items inside them, which can differ from the order's own status.

## `orderReportType` (type: `string`):

Filter your orders to one report type.

## `orderQuery` (type: `string`):

Free text matched against your orders, such as a customer reference or an address.

## `orderFromDate` (type: `string`):

Only orders placed on or after this date.

## `orderToDate` (type: `string`):

Only orders placed on or before this date.

## `orderSort` (type: `string`):

Which field to sort your orders by, as the provider names it.

## `orderDirection` (type: `string`):

Which way to sort your orders.

## `maxResults` (type: `integer`):

Stop after this many rows. The spatial features service pages 100 features at a time, so a large area can return a great many, and this cap is what bounds it.

## `requestsPerMinute` (type: `integer`):

Pacing ceiling. Lower this if your subscription sets a throughput limit.

## `apiKey` (type: `string`):

Your own API key for the UK environmental data provider. This actor is bring-your-own-key and never ships a key of its own. Leave blank to use the DATA\_API\_KEY environment secret instead.

## `alertsBaseUrl` (type: `string`):

Override the host serving the ground risk and mining services. Set this to the provider's staging host to test against it.

## `dataHubBaseUrl` (type: `string`):

Override the host serving the spatial features service.

## `webApiBaseUrl` (type: `string`):

Override the host serving the product catalogue, orders, documents and invoices.

## Actor input object example

```json
{
  "service": "groundRisk",
  "inputProjection": "4326",
  "outputProjection": "4326",
  "orderDirection": "desc",
  "maxResults": 500,
  "requestsPerMinute": 60
}
```

# Actor output Schema

## `records` (type: `string`):

One row per record, alongside the location or id that produced it.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/uk-ground-risk-mining-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/uk-ground-risk-mining-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call nabeelbaghoor/uk-ground-risk-mining-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/uk-ground-risk-mining-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/4jPYyIgXNuWej1HeK/builds/2pWUau1LRkKw2Uadf/openapi.json