Download OpenAPI specification:
Read-only access to AMLD (Advanced Mobile Leak Detection) survey deliverables for your own projects.
Sparus surveys a polygon, a single work area, with a vehicle-mounted methane analyser. Three endpoints return the three deliverables for a polygon.
| Endpoint | One record per | Geometry |
|---|---|---|
/indications |
leak indication | Point, the estimated source location |
/searcharea |
leak indication | Polygon, the area to survey on the ground |
/coverage |
survey window | Polygon, where the vehicle actually drove |
/indications and /searcharea return the same records carrying the same
attributes. Only the geometry differs. Indications give you a point to place on
a map, search areas give a crew a boundary to walk.
Every call needs an Entra ID bearer token obtained with the OAuth 2.0 client credentials flow, using the client ID and secret issued to you by Sparus.
POST https://login.microsoftonline.com/cde28249-57d0-4382-88f5-21846928ae61/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=<your client id>
&client_secret=<your client secret>
&scope=api://6fdc452d-ed1d-4074-89c7-84a9d4bbe365/.default
Send the result as Authorization: Bearer <access_token>. No subscription key
is required.
Your token scopes every response to your own organisation. There is no scoping parameter to pass and nothing to configure.
project, phase, area and polygon are all required, and they are the same
four values that identify a polygon in the delivery spreadsheet you receive.
Values are case-sensitive.
polygon takes a comma-separated list, up to 100 per request, for example
polygon=9,10,11. Records from every requested polygon are combined into one
response and de-duplicated. Every record carries its own customer, project,
phase, area and polygon, so group by those fields to split the response
back out per polygon.
Set include_geometry=false to omit geometry. Coverage geometry in particular is
large and can exceed 300 kB of JSON for a single record, so omit it when you only
need the drive window.
A polygon can be surveyed and legitimately produce no indications. That is a
200 with an empty data array and meta.total_count of 0, and it is the
same response whether the underlying file is empty or absent.
204 No Content is deliberately not used, so the meta envelope is present on
every successful response and a client never has to branch on status code before
parsing.
A 0 on /searcharea is also the "no indications found" signal, so one call
answers both "was anything found" and "what was found". Note that a polygon with
no indications still has coverage: /coverage returns its drive window normally.
page starts at 1 and page_size defaults to 100.
meta.total_count is a record count for the whole request, across all
polygons you asked for, not a count of polygons. meta.has_more tells you
whether another page exists. Requesting a page that starts past the end of a
non-empty result set is a 400.
For a single polygon, meta.total_count on /searcharea is the number of search
area records Sparus holds for it, which is the same quantity as the
Search Area Count column of the delivery spreadsheet. Compare the two to
confirm you received everything. A mismatch is worth raising with Sparus.
Per-area totals in the delivery email are sums of Search Area Count across that
area's polygons, so they do not equal a polygon count.
first_time, last_time, drive_start and drive_end are formatted
YYYY-MM-DD HH:MM:SS in US Eastern time, adjusted for daylight saving. They
carry no timezone offset and no T separator, so they are not RFC 3339 and a
strict ISO 8601 parser will reject them.
Eastern is used for every project regardless of where the survey took place, so a
survey in a Central time zone is still stamped Eastern. Convert with the
America/New_York zone, not with a fixed offset.
Indications are recombined as more observations arrive, so a later delivery for
the same polygon can return more records or fewer, and amld_id values can
change. Treat each response as a full replacement for that polygon rather than
diffing it against a previous one, and do not rely on amld_id as a stable
primary key across deliveries.
You may make 100 calls per minute and 1000 calls per day. Exceeding either returns a 429 with a Retry-After header giving the seconds to wait. /healthz is not counted.
What has been released to you and when, so you can poll for deliveries instead of waiting for a spreadsheet by email.
Returns one row per released polygon, newest release first, carrying the delivery parameters you need to call the data endpoints.
A drop-in replacement for the delivery spreadsheet, so you can poll for
releases instead of waiting for an email. Hold your own cursor: set
released_from to the newest released_at you have already ingested and you
get only what has been released since.
Deliveries are partial and repeated. A single area is normally released
across several batches, so treat (project, phase, area, polygon) as the key
and released_at as the version, rather than expecting an area to arrive
once and complete.
A polygon can also be re-delivered, when it is corrected or reprocessed after
release. It comes back with a newer released_at and its original
batch_id, so the same poll picks it up. Replace what you hold for that
polygon rather than merging with it.
A window with no releases is not an error. The response is 200 with an empty
data array and meta.total_count of 0. If the list cannot be read at all,
the response is 503 instead, so an outage is never mistaken for a quiet
period. Retry it without moving your watermark.
| released_from | string <date-time> (Released From) Examples: released_from=2026-07-01T00:00:00Z Inclusive lower bound on |
| released_to | string <date-time> (Released To) Examples: released_to=2026-08-01T00:00:00Z Exclusive upper bound on |
| project | string (Project) Optional filter. Omit to get every project. |
| phase | string (Phase) Optional filter. |
| area | string (Area) Optional filter. |
| page | integer (Page) >= 1 Default: 1 Page number, from 1. |
| page_size | integer (Page Size) [ 1 .. 1000 ] Default: 100 Rows per page. |
{- "data": [
- {
- "customer": "Duke",
- "project": "DukeTaskableCBD2026",
- "phase": "1",
- "area": "Charlotte",
- "polygon": "9",
- "search_area_count": 9,
- "coverage_geometry": "Polygon",
- "released_at": "2026-07-30T20:00:14Z",
- "batch_id": "Duke-20260730-01",
- "grid_id": "S06E08"
}
], - "meta": {
- "total_count": 9,
- "page": 1,
- "page_size": 100,
- "has_more": false
}
}Leak indications for a polygon, one Point per indication at the estimated source location.
Get indication records, filtered by project, phase, area, and polygon.
You must pass one or more polygon names as a single comma-separated string.
polygon=poly1,poly2,poly3A polygon with no records is not an error. The response is 200 with an empty
data array and meta.total_count of 0, whether the polygon's file is empty
or absent.
| project required | string (Project) |
| phase required | string (Phase) |
| area required | string (Area) |
| polygon required | string (Polygon) Comma-separated polygon names (max 100) |
| include_geometry | boolean (Include Geometry) Default: true |
| page | integer (Page) >= 1 Default: 1 Page number for pagination |
| page_size | integer (Page Size) >= 1 Default: 100 Number of results per page |
A full response, geometry included. Each record is a Point at the estimated source location.
{- "data": [
- {
- "amld_id": "Duke_DukeTaskableCBD2026_1_Charlotte_9_1783474727.0",
- "overall_lon": -80.854691,
- "overall_lat": 35.226658,
- "mean_em_lpm": 0.1,
- "med_em_lpm": 0.098,
- "mean_em_scfh": 0.209,
- "med_em_scfh": 0.209,
- "max_ch4_ab": 0.171,
- "mean_logch4": -1.765,
- "numtimes": 1,
- "max_c2h6_ab": 9.2,
- "base_ch4": 2.14,
- "mean_peak_dist": 0.019,
- "c1c2_cor": 0.995,
- "c2c1_ratio": 0.0537,
- "ng_status": true,
- "pk_type": "TYP",
- "wind_mps": 0.189,
- "wd_ccwe_rad": 0.961,
- "first_time": "2026-07-07 21:38:47",
- "last_time": "2026-07-07 21:38:47",
- "customer": "Duke",
- "project": "DukeTaskableCBD2026",
- "phase": "1",
- "area": "Charlotte",
- "polygon": "9",
- "algo_version": "v1.3.2",
- "geometry": {
- "type": "Point",
- "coordinates": [
- -80.854691,
- 35.226658
]
}
}, - {
- "amld_id": "Duke_DukeTaskableCBD2026_1_Charlotte_9_1783475457.0",
- "overall_lon": -80.849594,
- "overall_lat": 35.22274,
- "mean_em_lpm": 0.33,
- "med_em_lpm": 0.332,
- "mean_em_scfh": 0.705,
- "med_em_scfh": 0.705,
- "max_ch4_ab": 0.289,
- "mean_logch4": -1.242,
- "numtimes": 1,
- "max_c2h6_ab": 18.01,
- "base_ch4": 2.127,
- "mean_peak_dist": 9.835,
- "c1c2_cor": 0.997,
- "c2c1_ratio": 0.0624,
- "ng_status": true,
- "pk_type": "TYP",
- "wind_mps": 3.982,
- "wd_ccwe_rad": 0.784,
- "first_time": "2026-07-07 21:50:57",
- "last_time": "2026-07-07 21:50:57",
- "customer": "Duke",
- "project": "DukeTaskableCBD2026",
- "phase": "1",
- "area": "Charlotte",
- "polygon": "9",
- "algo_version": "v1.3.2",
- "geometry": {
- "type": "Point",
- "coordinates": [
- -80.849594,
- 35.22274
]
}
}
], - "meta": {
- "total_count": 9,
- "page": 1,
- "page_size": 100,
- "has_more": false
}
}The same indications as /indications, with the Polygon a crew should survey on the ground instead of a point.
Get search-area records, filtered by project, phase, area, and polygon.
You must pass one or more polygon names as a single comma-separated string.
polygon=poly1,poly2,poly3A polygon with no records is not an error. The response is 200 with an empty
data array and meta.total_count of 0, whether the polygon's file is empty
or absent.
| project required | string (Project) |
| phase required | string (Phase) |
| area required | string (Area) |
| polygon required | string (Polygon) Comma-separated polygon names (max 100) |
| include_geometry | boolean (Include Geometry) Default: true |
| page | integer (Page) >= 1 Default: 1 Page number for pagination |
| page_size | integer (Page Size) >= 1 Default: 100 Number of results per page |
Requested with include_geometry=false. With geometry, each record carries the Polygon a crew should survey.
{- "data": [
- {
- "amld_id": "Duke_DukeTaskableCBD2026_1_Charlotte_9_1783474727.0",
- "overall_lon": -80.854691,
- "overall_lat": 35.226658,
- "mean_em_lpm": 0.1,
- "med_em_lpm": 0.098,
- "mean_em_scfh": 0.209,
- "med_em_scfh": 0.209,
- "max_ch4_ab": 0.171,
- "mean_logch4": -1.765,
- "numtimes": 1,
- "max_c2h6_ab": 9.2,
- "base_ch4": 2.14,
- "mean_peak_dist": 0.019,
- "c1c2_cor": 0.995,
- "c2c1_ratio": 0.0537,
- "ng_status": true,
- "pk_type": "TYP",
- "wind_mps": 0.189,
- "wd_ccwe_rad": 0.961,
- "first_time": "2026-07-07 21:38:47",
- "last_time": "2026-07-07 21:38:47",
- "customer": "Duke",
- "project": "DukeTaskableCBD2026",
- "phase": "1",
- "area": "Charlotte",
- "polygon": "9",
- "algo_version": "v1.3.2",
- "geometry": null
}, - {
- "amld_id": "Duke_DukeTaskableCBD2026_1_Charlotte_9_1783475457.0",
- "overall_lon": -80.849594,
- "overall_lat": 35.22274,
- "mean_em_lpm": 0.33,
- "med_em_lpm": 0.332,
- "mean_em_scfh": 0.705,
- "med_em_scfh": 0.705,
- "max_ch4_ab": 0.289,
- "mean_logch4": -1.242,
- "numtimes": 1,
- "max_c2h6_ab": 18.01,
- "base_ch4": 2.127,
- "mean_peak_dist": 9.835,
- "c1c2_cor": 0.997,
- "c2c1_ratio": 0.0624,
- "ng_status": true,
- "pk_type": "TYP",
- "wind_mps": 3.982,
- "wd_ccwe_rad": 0.784,
- "first_time": "2026-07-07 21:50:57",
- "last_time": "2026-07-07 21:50:57",
- "customer": "Duke",
- "project": "DukeTaskableCBD2026",
- "phase": "1",
- "area": "Charlotte",
- "polygon": "9",
- "algo_version": "v1.3.2",
- "geometry": null
}
], - "meta": {
- "total_count": 9,
- "page": 1,
- "page_size": 100,
- "has_more": false
}
}Get coverage records, filtered by project, phase, area, and polygon.
You must pass one or more polygon names as a single comma-separated string.
polygon=poly1,poly2,poly3A polygon with no records is not an error. The response is 200 with an empty
data array and meta.total_count of 0, whether the polygon's file is empty
or absent.
| project required | string (Project) |
| phase required | string (Phase) |
| area required | string (Area) |
| polygon required | string (Polygon) Comma-separated polygon names (max 100) |
| include_geometry | boolean (Include Geometry) Default: true |
| page | integer (Page) >= 1 Default: 1 Page number for pagination |
| page_size | integer (Page Size) >= 1 Default: 100 Number of results per page |
Requested with include_geometry=false. One record spans the whole survey window for the polygon, here three calendar days.
{- "data": [
- {
- "customer": "Duke",
- "project": "DukeTaskableCBD2026",
- "phase": "1",
- "area": "Charlotte",
- "polygon": "9",
- "grid_id": null,
- "drive_start": "2026-07-07 21:37:09",
- "drive_end": "2026-07-09 21:45:18",
- "geometry": null
}
], - "meta": {
- "total_count": 1,
- "page": 1,
- "page_size": 100,
- "has_more": false
}
}Health check. Requires a valid token like every other path, but is excluded from the rate-limit counters.