AMLD Customer API (1.2.0)

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.

Authenticating

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.

Selecting data

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.

Empty results are not errors

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.

Pagination

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.

Reconciling a delivery

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.

Timestamps

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.

Coordinates

All geometry is GeoJSON-shaped, longitude first, in WGS 84 (EPSG:4326).

Records change between deliveries

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.

Request limits

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.

Deliveries

What has been released to you and when, so you can poll for deliveries instead of waiting for a spreadsheet by email.

List released polygons

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.

Authorizations:
EntraClientCredentials
query Parameters
released_from
string <date-time> (Released From)
Examples: released_from=2026-07-01T00:00:00Z

Inclusive lower bound on released_at, ISO 8601. Set it to the newest released_at you have ingested and use it as your watermark.

released_to
string <date-time> (Released To)
Examples: released_to=2026-08-01T00:00:00Z

Exclusive upper bound on released_at, ISO 8601. Omit it when polling forward; pass both bounds to replay a fixed window.

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.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Indications

Leak indications for a polygon, one Point per indication at the estimated source location.

Get Indications

Get indication records, filtered by project, phase, area, and polygon.

You must pass one or more polygon names as a single comma-separated string.

  • e.g. polygon=poly1,poly2,poly3

A 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.

Authorizations:
EntraClientCredentials
query Parameters
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

Responses

Response samples

Content type
application/json
Example

A full response, geometry included. Each record is a Point at the estimated source location.

{
  • "data": [
    ],
  • "meta": {
    }
}

SearchArea

The same indications as /indications, with the Polygon a crew should survey on the ground instead of a point.

Get Searcharea

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.

  • e.g. polygon=poly1,poly2,poly3

A 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.

Authorizations:
EntraClientCredentials
query Parameters
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

Responses

Response samples

Content type
application/json
Example

Requested with include_geometry=false. With geometry, each record carries the Polygon a crew should survey.

{
  • "data": [
    ],
  • "meta": {
    }
}

Coverage

Where the vehicle actually drove for a polygon, and the survey window it was driven in.

Get Coverage

Get coverage records, filtered by project, phase, area, and polygon.

You must pass one or more polygon names as a single comma-separated string.

  • e.g. polygon=poly1,poly2,poly3

A 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.

Authorizations:
EntraClientCredentials
query Parameters
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

Responses

Response samples

Content type
application/json
Example

Requested with include_geometry=false. One record spans the whole survey window for the polygon, here three calendar days.

{
  • "data": [
    ],
  • "meta": {
    }
}

System

Health check. Requires a valid token like every other path, but is excluded from the rate-limit counters.

Health Check

Authorizations:
EntraClientCredentials

Responses

Response samples

Content type
application/json
null