The GeoidLife API

POST/transform

Transform coordinates between any two coordinate reference systems. PROJ picks the most accurate operation it knows for the area your points are in, fetching the grid on demand: NADCON5 and HPGN in the US, NTv2 in Canada, Australia and Europe, geocentric and time-dependent Helmert transformations between modern frames.

{
  "from": "EPSG:4267",   // NAD27
  "to": "EPSG:4269",     // NAD83
  "points": [[-118.2437, 34.0522]]
}

{
  "ok": true, "from": "OGC:CRS27", "to": "OGC:CRS83",
  "operation": "NAD27 to NAD83 (7)",
  "accuracy_m": 0.15,
  "grids": [{"name": "us_noaa_nadcon5_nad27_nad83_1986_conus.tif", "available": true, …}],
  "candidates": 2, "count": 1, "failed": 0,
  "points": [[-118.24460641, 34.052212394]]
}

That is a 100 m shift the old datum needs in Los Angeles, applied with the NADCON5 grid. The first call for a new datum pair in a cold container may take one to three seconds while the grid tiles are fetched; after that it is tens of milliseconds.

POST/geoid

Turn ellipsoidal heights (what GNSS gives you) into orthometric heights (what plans, benchmarks and flood maps use), or go the other way, and get the geoid undulation N at each point. GEOID18 and GEOID12B over the contiguous US, EGM2008 and EGM96 worldwide.

{ "points": [[-118.2437, 34.0522, 100.0]] }

{
  "ok": true, "model": "GEOID18", "grid": "us_noaa_g2018u0.tif",
  "operation": "NAD83(2011) to NAVD88 height (3)",
  "units": "metres", "count": 1, "failed": 0,
  "points": [{"lon": -118.2437, "lat": 34.0522,
              "h": 100.0, "H": 135.1082, "N": -35.1082}]
}

h = ellipsoidal height, H = orthometric height (NAVD88 for the GEOID models, EGM height for the EGM models), N = h − H.

GET/crs/{code}

Describe a coordinate reference system: name, datum, ellipsoid, projection, axis order and units, area of use, and on request the WKT2, ESRI WKT1 and PROJJSON definitions. Handy for populating a CRS picker or validating user input before a transform.

GET /crs/2229?format=wkt

{
  "ok": true, "code": "EPSG:2229", "name": "NAD83 / California zone 5 (ftUS)",
  "type": "Projected CRS", "datum": "North American Datum 1983", "ellipsoid": "GRS 1980",
  "projection": "Lambert Conic Conformal (2SP)", "units": "US survey foot",
  "axes": [{"name": "Easting", "direction": "east", …}, {"name": "Northing", …}],
  "area_of_use": {"name": "United States (USA) - California - counties Kern; Los Angeles; …", "bounds": [-121.42, 32.76, -114.12, 35.81]},
  "proj4": "+proj=lcc +lat_0=33.5 +lon_0=-118 +lat_1=35.4666666666667 …",
  "wkt2": "PROJCRS[\"NAD83 / California zone 5 (ftUS)\", …"
}

POST/convert

Convert a geospatial file with GDAL. KMZ, KML, zipped Shapefile, GeoJSON, GPX, CSV and DBF in; Shapefile, KML, GeoJSON or CSV out. You get a download link to a zip, valid for one hour, plus a GeoJSON preview of the input.

# bash: base64 the file inline
curl -s -X POST $BASE/convert -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d "{\"file\":\"$(base64 < parcels.kmz)\",\"filename\":\"parcels.kmz\",\"conversion\":\"kmz-to-shp\"}"

{
  "success": true, "conversion_type": "kmz-to-shp", "output_file": "parcels_shapefile.zip",
  "download_url": "https://…amazonaws.com/output/d5ac96f6_parcels_shapefile.zip?X-Amz-…",
  "files_created": ["parcels.shp", "parcels.shx", "parcels.dbf", "parcels.prj"],
  "preview_type": "map", "preview_data": { "type": "FeatureCollection", … }
}

This endpoint shares its engine with converter.geoidlife.com, so its response shape is the converter's (success rather than ok). GeoPackage, FileGDB and raster formats are on the list for v1.1.

POST/keys

What the form at the top of this page calls. No key needed. Send {"email": "...", "name": "...", "use_case": "..."} and the key is emailed; the response is {"ok": true, "status": "created"} or "resent". Keys are never returned in the response body.

reportErrors, limits and fair use

Every error is JSON with the same shape: {"ok": false, "error": {"code": "...", "message": "..."}}.

• Quotas count requests, not points: one call with 1,000 points is one request.
• Payloads up to 10 MB; /convert files up to 6 MB decoded on the Free plan.
• Timeouts at 29 seconds (the HTTP gateway's limit). Large conversions will move to an asynchronous job endpoint in a later version.
• Fair use: one key per person or project, no reselling, no bulk scraping of the CRS registry. Keys that hammer the service get disabled with an email first.
• Status and versions: GET /health returns the PROJ and pyproj versions; breaking changes will ship as /v2.

sellPlans

Monthly plans, paid by card through Stripe. The key for your email moves to the new quota within seconds of checkout (if the address has no key yet, we create one and email it). Prices in USD before tax; cancel any time. Quotas are hard caps for now; metered overage at the schedule rates ($0.005 / $0.003 / $0.002 per extra request) comes next.

You go to Stripe Checkout to pay; your card never touches our servers. Already on a plan? Use the same email and we will email you a link to switch instead of charging you twice.

Need more than Team, an on-premise container, or a specific grid or datum (NATRF2022 is on the roadmap as soon as NGS publishes it)? Email us.