# GPS Coordinate Converter and Distance Calculator (`mangudai/gps-coordinate-converter`) Actor Convert GPS coordinates between decimal degrees, DMS, DDM, UTM, MGRS, Maidenhead and geohash, in bulk. Also measures geodesic distance, bearing and midpoint between two points, projects a destination point, and builds bounding boxes. Runs fully offline on WGS84, no API key needed. - **URL**: https://apify.com/mangudai/gps-coordinate-converter.md - **Developed by:** [Mangudäi](https://apify.com/mangudai) (community) - **Categories:** Developer tools, Automation, Open source - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.01 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## GPS coordinate converter and distance calculator Convert a point between every common coordinate notation and run geodesic calculations on it. Decimal degrees, degrees minutes seconds, degrees decimal minutes, UTM, MGRS, Maidenhead grid locator and geohash, all in one row. Then measure the distance and bearing between two points, project a destination point, or build a bounding box around a location. Everything is computed offline from WGS84 constants. No API key, no rate limit, no third-party service that can go down. ### What it does Give it a list of calculations. Each one produces one row. **convert** takes a single point and returns it in every supported format, plus the UTM zone and band, hemispheres, and ready-made Google Maps and OpenStreetMap links. **distance** takes two points and returns the geodesic distance on the WGS84 ellipsoid in metres, kilometres, miles, nautical miles and feet, plus the great-circle distance, the initial and final bearing, a 16-point compass direction, and the midpoint. **destination** takes a point, a bearing and a distance, and returns where you end up. **bbox** takes a point and a radius and returns the bounding box, formatted both as `minLon,minLat,maxLon,maxLat` for map APIs and as latitude-first for everything else. ### Input formats it understands You can write a point as free-form text and the actor works out the notation: | Notation | Example | | --- | --- | | Decimal degrees | `40.748440, -73.985664` | | Decimal with hemispheres | `40.7484 N, 73.9857 W` | | Degrees minutes seconds | `48°51'30.1"N 2°17'40.1"E` | | Colon separated DMS | `51:28:40N 0:00:05W` | | UTM | `18T 585631 4511327` | | MGRS | `31UDQ4825011951` | | Maidenhead locator | `JN58td` | | Geohash | `u4pruydqqvj` | You can also skip the text and pass `latitude` and `longitude` as numbers. ### Input ```json { "calculations": [ { "label": "Empire State Building", "type": "convert", "point": "40.748440, -73.985664" }, { "label": "Decode a geohash", "type": "convert", "point": "u4pruydqqvj" }, { "label": "New York to London", "type": "distance", "point": "40.7128, -74.0060", "point2": "51.5074, -0.1278" }, { "label": "100 km east of Greenwich", "type": "destination", "point": "51.4778, -0.0015", "bearing": 90, "distanceKm": 100 }, { "label": "10 km around Times Square", "type": "bbox", "point": "40.7580, -73.9855", "radiusKm": 10 } ], "geohashPrecision": 9, "mgrsPrecision": 5 } ```` `geohashPrecision` accepts 1 to 12 characters, where 9 resolves to about 5 metres. `mgrsPrecision` accepts 1 to 5 digits per axis, where 5 resolves to 1 metre. ### Output One row per calculation. A convert row looks like this: ```json { "label": "Empire State Building", "type": "convert", "inputPoint": "40.748440, -73.985664", "inputFormat": "degrees", "latitude": 40.74844, "longitude": -73.985664, "latitudeDMS": "40°44'54.38\"N", "longitudeDMS": "073°59'08.39\"W", "latitudeDDM": "40°44.9064'N", "longitudeDDM": "073°59.1398'W", "utm": "18T 585631 4511327", "utmZone": 18, "utmBand": "T", "utmEasting": 585631.397, "utmNorthing": 4511326.923, "mgrs": "18TWL8563111326", "geohash": "dr5ru6j2c", "maidenhead": "FN30ar19", "hemisphereNS": "North", "hemisphereEW": "West", "googleMapsUrl": "https://www.google.com/maps?q=40.74844,-73.985664" } ``` A distance row adds `distanceMeters`, `distanceKm`, `distanceMiles`, `distanceNauticalMiles`, `distanceFeet`, `greatCircleKm`, `initialBearing`, `finalBearing`, `compassDirection`, `midpointLatitude` and `midpointLongitude`. A destination row adds `bearing`, `resultLatitude`, `resultLongitude`, `resultDMS` and `resultGeohash`. A bbox row adds `radiusKm`, `minLatitude`, `maxLatitude`, `minLongitude`, `maxLongitude`, `bbox` and `bboxLatLon`. ### Accuracy Projections and distances use the WGS84 ellipsoid. The UTM transform is the standard Snyder series, checked against PROJ at sub-millimetre agreement on points from Svalbard to the Ross Ice Shelf. Distances use Vincenty's inverse formula, which agrees with PROJ's geodesic solver to the last printed digit. MGRS round-trips within the 1 metre grid square it names. UTM and MGRS are defined between 80° south and 84° north. Outside that range those two columns come back empty and a `note` field explains why, while every other format still works. A calculation that cannot be parsed returns an `error` on its own row instead of stopping the run, so one bad line never costs you the rest of the batch. ### Common uses Migrate survey data between DMS and decimal degrees. Feed a bounding box to an OpenStreetMap or Overpass query. Turn field notes written in MGRS into something a mapping tool will accept. Build geohash keys for spatial indexing. Work out how far apart two sites are without opening a mapping service. Convert a ham radio grid square to coordinates. ### Pricing Pay per event. You pay per result row, so a run costs what it produces and nothing more. # Actor input Schema ## `calculations` (type: `array`): One entry per calculation. Set type to convert, distance, destination or bbox. Give a point either as free-form text (decimal degrees, DMS, UTM, MGRS, Maidenhead or geohash) or as separate latitude and longitude numbers. For distance add point2 or latitude2 and longitude2, for destination add bearing and distanceKm, for bbox add radiusKm. ## `geohashPrecision` (type: `integer`): Number of geohash characters, 1 to 12. Nine characters resolve to roughly 5 metres. ## `mgrsPrecision` (type: `integer`): Digits per axis in the MGRS reference, 1 to 5. Five digits resolve to 1 metre. ## Actor input object example ```json { "calculations": [ { "label": "Empire State Building", "type": "convert", "point": "40.748440, -73.985664" }, { "label": "Eiffel Tower from degrees, minutes and seconds", "type": "convert", "point": "48°51'30.1\"N 2°17'40.1\"E" }, { "label": "Sydney Opera House from latitude and longitude", "type": "convert", "latitude": -33.856784, "longitude": 151.215297 }, { "label": "Decode a geohash", "type": "convert", "point": "u4pruydqqvj" }, { "label": "Decode an MGRS reference", "type": "convert", "point": "31UDQ4825011951" }, { "label": "New York to London", "type": "distance", "point": "40.7128, -74.0060", "point2": "51.5074, -0.1278" }, { "label": "100 km due east of Greenwich", "type": "destination", "point": "51.4778, -0.0015", "bearing": 90, "distanceKm": 100 }, { "label": "10 km bounding box around Times Square", "type": "bbox", "point": "40.7580, -73.9855", "radiusKm": 10 } ], "geohashPrecision": 9, "mgrsPrecision": 5 } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "calculations": [ { "label": "Empire State Building", "type": "convert", "point": "40.748440, -73.985664" }, { "label": "Eiffel Tower from degrees, minutes and seconds", "type": "convert", "point": "48°51'30.1\"N 2°17'40.1\"E" }, { "label": "Sydney Opera House from latitude and longitude", "type": "convert", "latitude": -33.856784, "longitude": 151.215297 }, { "label": "Decode a geohash", "type": "convert", "point": "u4pruydqqvj" }, { "label": "Decode an MGRS reference", "type": "convert", "point": "31UDQ4825011951" }, { "label": "New York to London", "type": "distance", "point": "40.7128, -74.0060", "point2": "51.5074, -0.1278" }, { "label": "100 km due east of Greenwich", "type": "destination", "point": "51.4778, -0.0015", "bearing": 90, "distanceKm": 100 }, { "label": "10 km bounding box around Times Square", "type": "bbox", "point": "40.7580, -73.9855", "radiusKm": 10 } ] }; // Run the Actor and wait for it to finish const run = await client.actor("mangudai/gps-coordinate-converter").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "calculations": [ { "label": "Empire State Building", "type": "convert", "point": "40.748440, -73.985664", }, { "label": "Eiffel Tower from degrees, minutes and seconds", "type": "convert", "point": "48°51'30.1\"N 2°17'40.1\"E", }, { "label": "Sydney Opera House from latitude and longitude", "type": "convert", "latitude": -33.856784, "longitude": 151.215297, }, { "label": "Decode a geohash", "type": "convert", "point": "u4pruydqqvj", }, { "label": "Decode an MGRS reference", "type": "convert", "point": "31UDQ4825011951", }, { "label": "New York to London", "type": "distance", "point": "40.7128, -74.0060", "point2": "51.5074, -0.1278", }, { "label": "100 km due east of Greenwich", "type": "destination", "point": "51.4778, -0.0015", "bearing": 90, "distanceKm": 100, }, { "label": "10 km bounding box around Times Square", "type": "bbox", "point": "40.7580, -73.9855", "radiusKm": 10, }, ] } # Run the Actor and wait for it to finish run = client.actor("mangudai/gps-coordinate-converter").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "calculations": [ { "label": "Empire State Building", "type": "convert", "point": "40.748440, -73.985664" }, { "label": "Eiffel Tower from degrees, minutes and seconds", "type": "convert", "point": "48°51'\''30.1\\"N 2°17'\''40.1\\"E" }, { "label": "Sydney Opera House from latitude and longitude", "type": "convert", "latitude": -33.856784, "longitude": 151.215297 }, { "label": "Decode a geohash", "type": "convert", "point": "u4pruydqqvj" }, { "label": "Decode an MGRS reference", "type": "convert", "point": "31UDQ4825011951" }, { "label": "New York to London", "type": "distance", "point": "40.7128, -74.0060", "point2": "51.5074, -0.1278" }, { "label": "100 km due east of Greenwich", "type": "destination", "point": "51.4778, -0.0015", "bearing": 90, "distanceKm": 100 }, { "label": "10 km bounding box around Times Square", "type": "bbox", "point": "40.7580, -73.9855", "radiusKm": 10 } ] }' | apify call mangudai/gps-coordinate-converter --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=mangudai/gps-coordinate-converter", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "GPS Coordinate Converter and Distance Calculator", "description": "Convert GPS coordinates between decimal degrees, DMS, DDM, UTM, MGRS, Maidenhead and geohash, in bulk. Also measures geodesic distance, bearing and midpoint between two points, projects a destination point, and builds bounding boxes. Runs fully offline on WGS84, no API key needed.", "version": "0.0", "x-build-id": "Mb9XLo7FiEqlExFJ6" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/mangudai~gps-coordinate-converter/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-mangudai-gps-coordinate-converter", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/mangudai~gps-coordinate-converter/runs": { "post": { "operationId": "runs-sync-mangudai-gps-coordinate-converter", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/mangudai~gps-coordinate-converter/run-sync": { "post": { "operationId": "run-sync-mangudai-gps-coordinate-converter", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "calculations" ], "properties": { "calculations": { "title": "Calculations", "type": "array", "description": "One entry per calculation. Set type to convert, distance, destination or bbox. Give a point either as free-form text (decimal degrees, DMS, UTM, MGRS, Maidenhead or geohash) or as separate latitude and longitude numbers. For distance add point2 or latitude2 and longitude2, for destination add bearing and distanceKm, for bbox add radiusKm." }, "geohashPrecision": { "title": "Geohash precision", "minimum": 1, "maximum": 12, "type": "integer", "description": "Number of geohash characters, 1 to 12. Nine characters resolve to roughly 5 metres.", "default": 9 }, "mgrsPrecision": { "title": "MGRS precision", "minimum": 1, "maximum": 5, "type": "integer", "description": "Digits per axis in the MGRS reference, 1 to 5. Five digits resolve to 1 metre.", "default": 5 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```