Developer guide: URLs, embeds and the JavaScript API

Three ways in

Route	Use it when	Start here
Query string	You have a coordinate, a value or a whole list and you want the calculator to open with it already filled in — from a spreadsheet, a CMS field, an emailed link or an <a href>.	Parameter reference
iframe embed	The calculator belongs inside your own page or intranet but you would rather not rebuild it. Add embed=1 and the header, article and footer drop away.	Embedding
window.Geo	You want the numbers, not the interface — batch-processing a coordinate file, a build step, or your own UI on top of the same engine.	JavaScript API

Query-string API

Parameters are read once, when the page loads. Anything the tool does not recognise is ignored, so a stray parameter in a URL never breaks the calculator — it simply has no effect and the tool keeps its normal defaults. Values must be URL-encoded, and + is decoded as a space, so a pasted coordinate list travels safely.

Once you start interacting with a tool, it rewrites its own address with history.replaceState, so a refresh, a bookmark or a copied address bar entry reproduces exactly what is on screen. The page never reloads to do this, and there is no history entry to click back through. In embed mode the tool leaves the URL alone entirely.

Coordinate tools

If mode is absent the tab is chosen from the parameters you did send: a latitude and longitude pair selects the forward tab, an easting and northing pair selects the inverse tab, and a text value selects batch.

Four links that are already complete — open them and the answer is on screen:

• utm-coordinate-converter?lat=43.642567&lon=-79.387139 Forward: zone 17T, easting 630,084.301 m, northing 4,833,438.586 m.
• utm-coordinate-converter?e=630084.301&n=4833438.586&zone=17N Inverse: back to 43.642567° N, 79.387139° W.
• utm-coordinate-converter?mode=batch&dir=inv&zone=17N&text=… Batch: one grid coordinate in, one latitude and longitude out.
• unit-converter?value=100&from=usft&to=m Units: 100 US survey feet = 30.48006096 m.

Unit converter

Length keys: m ft usft in cm km yd ch lk rd fur fath mi nmi lea vara.
Area keys: m2 ft2 acre ha usacre km2 mi2 yd2 are rood sqch sqrd section township.
Angle keys: deg dms rad grad milN milA turn amin asec.

You do not have to send mode. If it is missing, the converter looks up the from key and switches to whichever family contains it, which is why ?value=1&from=acre&to=ha lands on the area tab with no further help. An unknown unit key is ignored and the default for that family is used instead.

Building a link — live

Change the fields and the URL below updates immediately. Press Preview to load that exact URL into the frame underneath, which is the same thing an iframe on your own page would show.

Embedding a calculator in your own page

Add embed=1 and the page hides everything except the calculator: no site header, no breadcrumb, no headline, no article, no footer. What is left is the tool card itself, at its natural height, ready to sit in a frame.

<iframe
  src="https://coordcalc.com/utm-coordinate-converter?embed=1&lat=43.642567&lon=-79.387139"
  title="UTM to latitude and longitude converter"
  width="100%" height="560" style="border:1px solid #cfd6e0;border-radius:12px"
  loading="lazy"></iframe>

Three details worth keeping. Give the frame a title, because screen readers announce it and an untitled frame is an accessibility dead end. Use loading="lazy" so a tool lower down a long page does not cost anything until it is scrolled into view. And size the frame for the tallest tab, not the one you linked to, so switching tabs inside the frame does not produce a scrollbar.

An embedded tool is the same document as the standalone page, so it keeps every behaviour: tabs switch, results recalculate as you type, Copy link builds a URL, and the batch tab still exports CSV. It also stays quiet — an embedded calculation writes no cookies, sends no request, and never touches the parent frame. Please leave one visible link back to the tool on the page that hosts the embed; an orphaned frame with no attribution is the one usage we ask you to avoid.

Live example — the frame below is utm-coordinate-converter?embed=1&lat=43.642567&lon=-79.387139:

The JavaScript API — window.Geo

The calculators all run on one shared library, inlined into each tool page and published as the global Geo. Open any tool, drop into the browser console, and it is there:

> Geo.utmForward(43.642567, -79.387139)
{ zone: 17, north: true, band: "T", centralMeridian: -81,
  easting: 630084.3008341495, northing: 4833438.585674161,
  convergence: 1.1133056360734274, scaleFactor: 0.9998080873147939 }

It is plain ES5 with no dependencies and no DOM access, so the same file works under Node: the library ends with module.exports = Geo, which means a build script or a test harness can pull it straight out of the page and require it.

Functions

Worked examples

Every value below was produced by the library itself; run the same lines on any tool page and you will get the same numbers.

// Toronto's CN Tower: latitude / longitude -> UTM
var u = Geo.utmForward(43.642567, -79.387139);
Geo.fmt(u.easting, 3);      // "630,084.301"
Geo.fmt(u.northing, 3);     // "4,833,438.586"
u.zone + u.band;            // "17T"
Geo.fmt(u.scaleFactor, 7);  // "0.9998081"

// and back again
var g = Geo.utmInverse(630084.301, 4833438.586, 17, true);
Geo.fmt(g.lat, 8);          // "43.64256700"
Geo.fmt(g.lon, 8);          // "-79.38713900"

// MGRS
Geo.mgrsForward(43.642567, -79.387139, 5).mgrs;   // "17TPJ3008433438"
Geo.mgrsInverse("17TPJ3008433438");               // { lat, lon, zone: 17, band: "T", … }

// ellipsoidal distance and bearing, Toronto to Beijing
var d = Geo.vincentyInverse(43.642567, -79.387139, 39.906111, 116.3974);
Geo.fmt(d.distance, 1);      // "10,616,473.2"  metres
Geo.fmt(d.initialBearing, 4);// "347.9204"      degrees
d.converged;                 // true

// ground area and perimeter of a parcel, from its corners
var parcel = [[43.641000, -79.388000], [43.641000, -79.385517],
              [43.642356, -79.385517], [43.642356, -79.388000]];
var a = Geo.polygonArea(parcel);
Geo.fmt(a.area, 1);          // "30,184.0"      square metres
Geo.fmt(a.perimeter, 2);     // "702.01"        metres
a.orientation;               // "counter-clockwise"

polygonArea is the one that needs a word of explanation. It projects the ring onto a tangent plane centred on the polygon's own centroid — that is what localPlane returns — so the area is a ground area, not a Web Mercator area, and it stays correct at any latitude. The corner ordering does not matter: the shoelace sum is taken in absolute value, and orientation simply reports which way round you went. The perimeter is summed from Vincenty distances along each edge, so it is an ellipsoidal length; geodesicPerimeter tells you whether Vincenty converged on every edge.

Constants

Geo.UNITS carries the factors the tools are built on, so a caller never has to restate them: M_PER_FT 0.3048, M_PER_MI 1609.344, M_PER_NM 1852, HA_M2 10000, ACRE_M2 4046.8564224 and SQFT_PER_M2 10.763910416709722. The ellipsoid parameters are on Geo.A (6378137 m) and Geo.F (1 / 298.257223563), for WGS84.

Accuracy, and one caveat

The transverse Mercator series is the published one, and the inverse is solved by Newton iteration rather than by a truncated reverse series. Measured against PROJ — the reference implementation behind pyproj and QGIS — the easting agrees to better than 0.1 mm and the northing to better than 0.9 mm over test points spread from the equator to 78° N and from 0° to 180° longitude. A forward-then-inverse round trip closes to a few nanometres, which is to say the limit of double precision.

The caveat is MGRS. A five-digit reference such as 17TPJ3008433438 does not name a point, it names a 1 m square, and mgrsInverse returns that square's south-west corner. Convert to MGRS and back and you should expect to land up to about 1.4 m from where you started — that is the format, not an error. Ask for six digits instead and the square is 0.1 m across.

Reference values

Southern-hemisphere northings include the 10,000,000 m false northing, exactly as printed on a survey plan.

Notes, limits and terms

• No key, no quota. There is nothing to register and nothing to meter. The pages are static files and every calculation runs in the browser, so a tool that is slow is a slow device, not a throttled account.
• Nothing is uploaded. No coordinate, value or pasted list leaves the page. The only requests are for the document itself, one stylesheet and one small script.
• Horizontal only. The library works in two dimensions on the WGS84 ellipsoid. It takes no account of a local datum shift, a geoid model, or a state plane zone; for those, use the state plane converter and check the projection your file actually carries against the EPSG code lookup.
• Reference, not a substitute for a standard. Results are for checking and planning. Confirm anything that governs construction, a boundary or a procurement against the specification that applies to the job.
• Attribution. Embedding is welcome; keep one visible link back to the tool. Do not present the calculators as your own, and do not rehost a modified copy under a name that suggests it computes something it does not.
• Versioning. The library is inlined per page rather than served from a shared file, so a page you have copied keeps working when the tools here are updated. The cost is that a fix does not reach a copy automatically — re-copy it if you depend on it.

Related calculators

Frequently asked questions

Can I prefill a calculator from a link?

Yes. Every tool reads its state from the query string. ?lat=43.642567&lon=-79.387139 opens the UTM converter already converted; ?value=100&from=usft&to=m opens the unit converter on a survey-foot conversion. Missing or unrecognised parameters are ignored and the tool falls back to its defaults.

Is there an API key or a rate limit?

Neither. The pages are static and every calculation runs in the visitor's browser, so there is nothing to authorise and nothing to meter. No coordinate is ever sent to a server.

How do I embed a calculator in my own page?

Add embed=1 and load the URL in an iframe. That hides the header, breadcrumb, article and footer and leaves the calculator at roughly 520 px tall for the single-coordinate tools. Everything still works inside the frame, including tab switching and CSV export.

What is window.Geo?

The shared geodesy library inlined into the tool pages, on the WGS84 ellipsoid. It exposes utmForward, utmInverse, mgrsForward, mgrsInverse, vincentyInverse, polygonArea, parseAngle and the rest, plus unit constants. It is dependency-free ES5 and also exports through module.exports for Node.

How accurate is the UTM conversion?

Against PROJ, the easting agrees to better than 0.1 mm and the northing to better than 0.9 mm across test points from the equator to 78° N, and a forward-then-inverse round trip closes to a few nanometres. The inverse is solved by Newton iteration, not a truncated reverse series.

Why is an MGRS round trip out by about a metre?

Because a five-digit reference names a 1 m square rather than a point, and the inverse returns its south-west corner. Expect up to about 1.4 m of offset. Use six digits and the square is 0.1 m across.