Ingress MU calculator Calculator How it works Method API

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.

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

EndpointPurpose
GET /getMUMU of one field; the coordinates are query parameters.
POST /getMUMU of one field; the coordinates are in a JSON body.
POST /getMUbulkMU of 1 to 50 fields in one request.
GET /healthService status.
GET /Short JSON description of the service.
GET /docsGenerated interactive API documentation (OpenAPI).

Coordinates

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"
}
FieldMeaning
muMind Units of the field, an integer (rounded once, half up, as described on the Method page).
area_km2Spherical area of the field in km² (earth radius 6371.01 km).
coordinatesThe three points after rounding, as "latitude, longitude" strings with six decimals, in the order given.
modelIdentifier 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.

FieldMeaning
raw_muSum over all covering cells of overlap area times density, before the regional minimum of 1 MU.
regional_total_muTotal 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"
}

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

LimitValue
Points per fieldexactly 3
Fields per bulk request1 to 50 (otherwise status 400)
Request body32,768 bytes (larger bodies get status 413)
Time per request20 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"}
StatusCauseerror
400Latitude or longitude out of rangeCoordinate 1: latitude must be -90 to 90; longitude -180 to 180.
400Nonfinite coordinate numberCoordinate 1: numbers must be finite.
400Not a numberCoordinate 1: use decimal numbers, such as 52.245944, 10.539506.
400Not two comma-separated parts, or a {lat, lng} object with other keysCoordinate 1: use latitude, longitude.
400Not exactly three pointsSupply exactly three coordinates.
400Points equal after roundingThe three coordinates must be distinct at six decimal places.
400Degenerate triangle, for example ["0,0","0,180","0,90"] or ["0,0","0,1","0,2"]The triangle must have a nonzero area.
400Invalid detail valuedetail must be true, false, 1 or 0.
400Malformed JSON bodyMalformed JSON.
400JSON body is not an objectExpected a JSON object.
400Bulk request without 1 to 50 fieldsfields must be an array of 1 to 50 triangles.
404Unknown pathNot Found
405Method not allowed for the pathMethod Not Allowed
413Body larger than 32,768 bytesRequest body exceeds limit.
500Unexpected failureCalculation failed.
504Time budget exceededdeadline 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.