API
The calculation of this site is available as a public HTTP API. Given three portal coordinates, it returns the Mind Units (MU) of the control field they span. It is the same calculation as on the calculator page, the page itself uses this API.
- Base URL:
https://api.investigatexm.com - No API key and no registration.
- Requests and responses are JSON.
- Clients should send a descriptive
User-Agentheader; some default library user agents are rejected at the network edge (Cloudflare). - CORS is open (
Access-Control-Allow-Origin: *), so the API can be called from a browser on any site. - Every calculation response contains
model, an identifier of the calculation model, currentlygrump2000-s2java2011-min6-l6min1.
Results for very large fields (from a few hundred thousand km²) are likely but not confirmed to be correct in every case.
Run it yourself
The API software's own request log records time, client address, user agent, method, path, status and duration, but no coordinates and no results are stored.
If you want to keep OpSec 100% clean and be certain, you can run the identical calculation with the Docker container on the GitHub page. Only NASA Earthdata credentials are needed for the one-time population data download, after that the container needs no further outbound requests to answer API requests. See the README on GitHub for setup, configuration and source code.
Endpoints
| Endpoint | Purpose |
|---|---|
GET /getMU | MU of one field; the coordinates are query parameters. |
POST /getMU | MU of one field; the coordinates are in a JSON body. |
POST /getMUbulk | MU of 1 to 50 fields in one request. |
GET /health | Service status. |
GET / | Short JSON description of the service. |
GET /docs | Generated interactive API documentation (OpenAPI). |
Coordinates
- A point is a string
"latitude,longitude"in decimal degrees, for example"52.324297,10.182664"(spaces around the numbers are allowed), or, in JSON bodies only, an object{"lat": 52.324297, "lng": 10.182664}with exactly these two keys. - Latitude is -90 to 90, longitude is -180 to 180.
- Coordinates are rounded half up to six decimal places before the calculation. The
coordinatesin the response show the rounded values. - A field has exactly three points. They must differ after rounding and form a triangle on the sphere with nonzero area; its edges are great-circle arcs. The order of the points does not matter.
- There is no size limit for the field; every valid triangle is accepted within the time budget (see Limits).
Single field: GET /getMU
Pass the three points as repeated c=latitude,longitude parameters. detail=1 is optional (see Detail). In the query string, 1, 0, true and false (case-insensitive) are accepted as values of detail.
GET /getMU?c=52.324297,10.182664&c=52.244048,10.167482&c=52.295984,10.231064
Response (HTTP 200):
{
"mu": 3046,
"area_km2": 16.311625962717194,
"coordinates": ["52.324297, 10.182664", "52.244048, 10.167482", "52.295984, 10.231064"],
"model": "grump2000-s2java2011-min6-l6min1"
}
| Field | Meaning |
|---|---|
mu | Mind Units of the field, an integer (rounded once, half up, as described on the Method page). |
area_km2 | Spherical area of the field in km² (earth radius 6371.01 km). |
coordinates | The three points after rounding, as "latitude, longitude" strings with six decimals, in the order given. |
model | Identifier of the calculation model. |
Detail
detail=1 in the query string (on both GET and POST) or "detail": true in a JSON body adds the intermediate results. The query parameter takes precedence over the body. In a JSON body, booleans, numbers 1/0, and strings "1", "0", "true", "false" (case-insensitive) are accepted; null disables detail; true/1 values enable detail, false/0 values disable it, and without the flag the fields below are omitted.
| Field | Meaning |
|---|---|
raw_mu | Sum over all covering cells of overlap area times density, before the regional minimum of 1 MU. |
regional_total_mu | Total after the regional minimum, before the final rounding to mu. |
regions[] | One entry per S2 level-6 region that contains covering cells of the field: s2_token (region cell), raw_mu (sum of its cells) and minimum_applied_mu (that sum, but at least 1). |
cells[] | One entry per covering cell: s2_id (S2 cell id as a decimal string), s2_token (the same id as hexadecimal token), level (S2 level), overlap_km2 (area of the field inside the cell), density (MU per km² of the cell) and raw_mu (overlap_km2 times density). |
Example response of GET /getMU?…&detail=1 for the same field. The cells array is shortened here (…); the real response contains all 19 cells.
{
"coordinates": [
"52.324297, 10.182664",
"52.244048, 10.167482",
"52.295984, 10.231064"
],
"mu": 3046,
"area_km2": 16.311625962717194,
"raw_mu": 3045.926491022803,
"regional_total_mu": 3045.9264910228035,
"regions": [
{
"s2_token": "47a5",
"raw_mu": 126.60537791261866,
"minimum_applied_mu": 126.60537791261866
},
{
"s2_token": "47af",
"raw_mu": 2310.924092396028,
"minimum_applied_mu": 2310.924092396028
},
{
"s2_token": "47b1",
"raw_mu": 578.3064609347751,
"minimum_applied_mu": 578.3064609347751
},
{
"s2_token": "47bb",
"raw_mu": 30.090559779381714,
"minimum_applied_mu": 30.090559779381714
}
],
"cells": [
{
"s2_id": "5162626349935886336",
"s2_token": "47a5555",
"level": 12,
"overlap_km2": 1.115324194111231,
"density": 113.51441901922226,
"raw_mu": 126.60537791261866
},
{
"s2_id": "5165626728189526016",
"s2_token": "47affe24",
"level": 13,
"overlap_km2": 0.007949411586318528,
"density": 219.47376251220703,
"raw_mu": 1.7446872706074597
},
…
],
"model": "grump2000-s2java2011-min6-l6min1"
}
Detail contains every covering cell and region, without truncation. Responses for very large fields can be several MB.
Single field: POST /getMU
JSON body with coordinates (an array of three points, strings or {lat, lng} objects, which may be mixed) and optional detail. The response is the same as for GET.
POST /getMU
Content-Type: application/json
{
"coordinates": [
{"lat": 52.324297, "lng": 10.182664},
"52.244048,10.167482",
{"lat": 52.295984, "lng": 10.231064}
],
"detail": false
}
A POST with Content-Type: application/json from a browser on another origin triggers a CORS preflight request, which the API answers.
Several fields: POST /getMUbulk
JSON body with fields, an array of 1 to 50 fields, and optional detail (same rules as above, applied to all fields). Each field is either an array of three points or an object with coordinates and an optional id. An id can be any JSON value and is returned unchanged.
POST /getMUbulk
Content-Type: application/json
{
"fields": [
{"id": "field-1", "coordinates": ["52.324297,10.182664", "52.244048,10.167482", "52.295984,10.231064"]},
["0,0", "0,0", "0,0"]
]
}
Response (HTTP 200):
{
"count": 2,
"results": [
{"index": 0, "id": "field-1", "ok": true, "mu": 3046, "area_km2": 16.311625962717194, "coordinates": ["52.324297, 10.182664", "52.244048, 10.167482", "52.295984, 10.231064"]},
{"index": 1, "ok": false, "error": "The three coordinates must be distinct at six decimal places."}
],
"model": "grump2000-s2java2011-min6-l6min1"
}
resultshas one entry per field, in the order of the request.indexis the position infields;idis present only if it was supplied.- A successful entry has
"ok": trueand the fields of a single result (with the detail fields if requested), withoutmodel, which appears once at the top level. - An invalid field does not affect the others: its entry has
"ok": falseand anerrormessage, and the HTTP status stays 200. - Results are per field. They are not added up, and overlapping fields are not merged.
- A request that is invalid as a whole (malformed JSON,
fieldsmissing or not 1 to 50 entries, invaliddetail) fails with a single error response.
GET /health and GET /
GET /health
{"ok":true,"rasters":234,"model":"grump2000-s2java2011-min6-l6min1","table_max_level":11,"table_levels_ready":[6,7,8,9,10,11]}
GET /
{"description":"Independent empirical Ingress MU calculator.","docs":"https://mu.investigatexm.com","api_docs":"/docs","table_max_level":11,"model":"grump2000-s2java2011-min6-l6min1"}
ok is true once the service has started and passed its start-up self-test. The other fields of /health and / describe the server's data preparation and can change.
Limits
| Limit | Value |
|---|---|
| Points per field | exactly 3 |
| Fields per bulk request | 1 to 50 (otherwise status 400) |
| Request body | 32,768 bytes (larger bodies get status 413) |
| Time per request | 20 seconds, including the time a request waits for other calculations (calculations run one at a time). A single request that exceeds it gets status 504; in a bulk request the fields that were not finished in time get "ok": false and "error": "deadline exceeded". |
Errors
Errors are JSON objects with an error message and model, for example for GET /getMU?c=91,10&c=52.244048,10.167482&c=52.295984,10.231064 (status 400):
{"error":"Coordinate 1: latitude must be -90 to 90; longitude -180 to 180.","model":"grump2000-s2java2011-min6-l6min1"}
| Status | Cause | error |
|---|---|---|
| 400 | Latitude or longitude out of range | Coordinate 1: latitude must be -90 to 90; longitude -180 to 180. |
| 400 | Nonfinite coordinate number | Coordinate 1: numbers must be finite. |
| 400 | Not a number | Coordinate 1: use decimal numbers, such as 52.245944, 10.539506. |
| 400 | Not two comma-separated parts, or a {lat, lng} object with other keys | Coordinate 1: use latitude, longitude. |
| 400 | Not exactly three points | Supply exactly three coordinates. |
| 400 | Points equal after rounding | The three coordinates must be distinct at six decimal places. |
| 400 | Degenerate triangle, for example ["0,0","0,180","0,90"] or ["0,0","0,1","0,2"] | The triangle must have a nonzero area. |
| 400 | Invalid detail value | detail must be true, false, 1 or 0. |
| 400 | Malformed JSON body | Malformed JSON. |
| 400 | JSON body is not an object | Expected a JSON object. |
| 400 | Bulk request without 1 to 50 fields | fields must be an array of 1 to 50 triangles. |
| 404 | Unknown path | Not Found |
| 405 | Method not allowed for the path | Method Not Allowed |
| 413 | Body larger than 32,768 bytes | Request body exceeds limit. |
| 500 | Unexpected failure | Calculation failed. |
| 504 | Time budget exceeded | deadline exceeded |
In a bulk request, coordinate errors are reported per field (status 200, see above). Responses produced by the network in front of the API, for example when it refuses a client, are not necessarily JSON.
Examples
All examples use the same field. Its MU is 3046.
curl
curl "https://api.investigatexm.com/getMU?c=52.324297,10.182664&c=52.244048,10.167482&c=52.295984,10.231064"
curl -X POST https://api.investigatexm.com/getMU \
-H "Content-Type: application/json" \
-d '{"coordinates":["52.324297,10.182664","52.244048,10.167482","52.295984,10.231064"]}'
Both print:
{"mu":3046,"area_km2":16.311625962717194,"coordinates":["52.324297, 10.182664","52.244048, 10.167482","52.295984, 10.231064"],"model":"grump2000-s2java2011-min6-l6min1"}
curl -X POST https://api.investigatexm.com/getMUbulk \
-H "Content-Type: application/json" \
-d '{"fields":[{"id":"field-1","coordinates":["52.324297,10.182664","52.244048,10.167482","52.295984,10.231064"]},["0,0","0,0","0,0"]]}'
This prints the bulk response shown above, on one line.
JavaScript (browser or Node.js 18+, as a module)
const res = await fetch('https://api.investigatexm.com/getMU', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
coordinates: [
{ lat: 52.324297, lng: 10.182664 },
{ lat: 52.244048, lng: 10.167482 },
{ lat: 52.295984, lng: 10.231064 },
],
}),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.mu, data.area_km2); // 3046 16.311625962717194
Python
import json
import urllib.request
body = json.dumps({"coordinates": [
"52.324297,10.182664",
"52.244048,10.167482",
"52.295984,10.231064",
]}).encode()
request = urllib.request.Request(
"https://api.investigatexm.com/getMU",
data=body,
headers={
"Content-Type": "application/json",
"User-Agent": "mu-api-example/1.0",
},
)
with urllib.request.urlopen(request, timeout=30) as response:
data = json.load(response)
print(data["mu"], data["area_km2"]) # 3046 16.311625962717194
The example sets its own User-Agent: requests with the default Python-urllib user agent are refused with status 403 (error code: 1010) by the network in front of the API. A failed request raises urllib.error.HTTPError; API error bodies are JSON, readable with json.load(error), but proxy/CDN errors may use other formats.
The service enforces no rate limit; an operator may add one at a reverse proxy.
Fair use
The API is free to use and provided without a guarantee of availability. Please keep the request rate moderate, and use /getMUbulk instead of many single requests when several fields are needed.