{"id":10936,"library":"geolocation-utils","title":"Geolocation Utilities","description":"geolocation-utils is a JavaScript/TypeScript library designed for performing various calculations and conversions related to geographical locations. As of its latest stable release, version 1.2.6, published approximately a year ago, the library focuses on providing utility functions rather than direct device geolocation access. It enables conversion between common location formats like `[lon, lat]`, `{lat, lon}`, `{lat, lng}`, and `{latitude, longitude}`. Key functionalities include calculating distances and headings between points, moving a specified distance to a new location, determining bounding boxes around a list of locations, and checking if a location falls within a given polygon, circle, or bounding box. The library differentiates itself by using plain JavaScript objects for locations, which simplifies serialization and interoperability with other libraries and REST APIs. While there isn't a strict major release cadence, development appears active on GitHub with periodic updates.","status":"active","version":"1.2.6","language":"javascript","source_language":"en","source_url":"https://github.com/teqplay/geolocation-utils","tags":["javascript","geo","geolocation","location","utils","typescript"],"install":[{"cmd":"npm install geolocation-utils","lang":"bash","label":"npm"},{"cmd":"yarn add geolocation-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add geolocation-utils","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses ES Module syntax. CommonJS `require` might work via transpilation but ESM is recommended. Ships with TypeScript types.","wrong":"const { toLatLon } = require('geolocation-utils')","symbol":"toLatLon","correct":"import { toLatLon } from 'geolocation-utils'"},{"note":"Named export for calculating heading and distance between two locations.","wrong":"const headingDistanceTo = require('geolocation-utils').headingDistanceTo","symbol":"headingDistanceTo","correct":"import { headingDistanceTo } from 'geolocation-utils'"},{"note":"All utility functions are named exports, there is no default export.","wrong":"import insidePolygon from 'geolocation-utils'","symbol":"insidePolygon","correct":"import { insidePolygon } from 'geolocation-utils'"},{"note":"Useful for programmatically creating location objects in a specific format.","symbol":"createLocation","correct":"import { createLocation } from 'geolocation-utils'"}],"quickstart":{"code":"import { \n  toLatLon, headingDistanceTo, moveTo, insidePolygon \n} from 'geolocation-utils';\n\n// Convert various location formats\nconsole.log(toLatLon([4, 51]));                        \n// { lat: 51, lon: 4 }\n\n// Calculate distance and heading, then move to a new location\nconst location1 = {lat: 51, lon: 4};\nconst location2 = {lat: 51.001, lon: 4.001 };\nconst { heading, distance } = headingDistanceTo(location1, location2);\nconsole.log({ heading, distance }); \n// { heading: 32.18..., distance: 131.52... }\n\nconst newLocation = moveTo(location1, {heading, distance});\nconsole.log(newLocation);\n// { lat: 51.001000..., lon: 4.000997... }\n\n// Check if a location is inside a polygon\nconst polygon = [\n  [4.03146, 51.9644],\n  [4.03151, 51.9643],\n  [4.03048, 51.9627],\n  [4.04550, 51.9600],\n  [4.05279, 51.9605],\n  [4.05215, 51.9619],\n  [4.04528, 51.9614],\n  [4.03146, 51.9644]\n];\nconsole.log(insidePolygon([4.03324, 51.9632], polygon)); // true","lang":"typescript","description":"Demonstrates basic usage including format conversion, distance calculation, moving to a new point, and checking if a point is within a polygon."},"warnings":[{"fix":"Always double-check the expected order of coordinates for input arrays. Prefer using object-based location formats (e.g., `{lat, lon}`) which are less ambiguous.","message":"Be extremely careful with coordinate order when using array-based location formats (`LonLatTuple`). The library *expects* `[longitude, latitude]` for these tuples, which is contrary to some other common GIS standards that use `[latitude, longitude]`. To avoid issues, using object-based formats like `{lat: number, lon: number}` is strongly recommended.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Standardize on one object format (e.g., `{lat, lon}`) within your application or use the provided conversion utilities (`toLatLon`, `toLatLng`, etc.) explicitly when interacting with external APIs or different data sources.","message":"The library supports multiple object-based formats, including `{lat, lon}`, `{lat, lng}`, and `{latitude, longitude}`. While flexible, ensure consistency in your application's data structures to prevent unexpected behavior. Functions that return a `Location` will typically maintain the input format if possible, but conversions can lead to different property names.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that `LonLatTuple` inputs are strictly in `[longitude, latitude]` order. For example, use `[4, 51]` for 4° Longitude, 51° Latitude. If possible, refactor to use object literals like `{ lat: 51, lon: 4 }` for clearer intent and to prevent this common pitfall.","cause":"This usually occurs when a `LonLatTuple` (array) is provided with coordinates in the wrong order, i.e., `[latitude, longitude]` instead of the expected `[longitude, latitude]`. The library specifically expects `[lon, lat]` for array inputs, which can lead to misinterpretation of geographical points or errors if the array indices are accessed out of bounds for an object that was not an array.","error":"TypeError: Cannot read properties of undefined (reading '1') or incorrect geographic results when using array inputs."}],"ecosystem":"npm"}