{"id":26289949,"url":"https://github.com/aashari/nodejs-geocoding","last_synced_at":"2025-08-08T12:07:27.639Z","repository":{"id":95958711,"uuid":"477407140","full_name":"aashari/nodejs-geocoding","owner":"aashari","description":"A lightweight, high-performance TypeScript/Node.js library for geocoding and reverse geocoding operations. Converts between addresses and coordinates with caching support, error handling, and multiple provider integration for reliable location services.","archived":false,"fork":false,"pushed_at":"2025-03-22T07:40:00.000Z","size":329,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-04T03:36:40.864Z","etag":null,"topics":["coordinates","geocoding","geolocation","google-maps","javascript","latitude-longitude","location","maps","nodejs","npm","npm-package","reverse-geocoding","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/aashari/nodejs-geocoding#readme","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aashari.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-03T16:59:21.000Z","updated_at":"2025-03-22T07:40:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"c585db2e-661e-4258-849c-689ded7deb56","html_url":"https://github.com/aashari/nodejs-geocoding","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/aashari/nodejs-geocoding","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashari%2Fnodejs-geocoding","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashari%2Fnodejs-geocoding/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashari%2Fnodejs-geocoding/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashari%2Fnodejs-geocoding/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aashari","download_url":"https://codeload.github.com/aashari/nodejs-geocoding/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashari%2Fnodejs-geocoding/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269417455,"owners_count":24413380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coordinates","geocoding","geolocation","google-maps","javascript","latitude-longitude","location","maps","nodejs","npm","npm-package","reverse-geocoding","typescript"],"created_at":"2025-03-14T23:17:26.461Z","updated_at":"2025-08-08T12:07:27.607Z","avatar_url":"https://github.com/aashari.png","language":"JavaScript","readme":"# @aashari/nodejs-geocoding\n\n[![npm version](https://img.shields.io/npm/v/@aashari/nodejs-geocoding.svg)](https://www.npmjs.com/package/@aashari/nodejs-geocoding)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-\u003e=22.0.0-green.svg)](https://nodejs.org/)\n[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/aashari/nodejs-geocoding/ci-semantic-release.yml?label=build)](https://github.com/aashari/nodejs-geocoding/actions/workflows/ci-semantic-release.yml)\n\n## Overview\n\nA lightweight TypeScript/Node.js library for geocoding and reverse geocoding operations with multilingual support. This library provides a simple, dependency-free solution for converting between addresses and geographic coordinates.\n\n\u003e ⚠️ **Disclaimer**: This library is intended for non-commercial, low-volume applications. For production or commercial use, please use the official [Google Maps API](https://developers.google.com/maps/documentation/geocoding/overview).\n\n## Features\n\n- **Zero External Dependencies**: Lightweight implementation with no third-party dependencies\n- **TypeScript Support**: Full TypeScript definitions included for type safety\n- **Promise-based API**: Modern async/await compatible interface\n- **Multilingual Support**: Get results in different languages (e.g., English, Indonesian, French, etc.)\n- **Forward Geocoding**: Convert addresses to coordinates (latitude/longitude)\n- **Reverse Geocoding**: Convert coordinates to formatted addresses\n- **Google Plus Codes**: Get Google Plus Codes for locations\n- **Simple Integration**: Easy to integrate with any Node.js project\n\n## Installation\n\n```bash\nnpm install @aashari/nodejs-geocoding\n```\n\n## Quick Start\n\n### Geocoding (Address to Coordinates)\n\n```javascript\nconst geocoding = require('@aashari/nodejs-geocoding');\n\n// Convert address to coordinates\ngeocoding\n\t.encode('Empire State Building, New York')\n\t.then((locations) =\u003e console.log(locations))\n\t.catch((error) =\u003e console.error(error));\n```\n\n### Reverse Geocoding (Coordinates to Address)\n\n```javascript\nconst geocoding = require('@aashari/nodejs-geocoding');\n\n// Convert coordinates to address\ngeocoding\n\t.decode(40.7484, -73.9857)\n\t.then((location) =\u003e console.log(location))\n\t.catch((error) =\u003e console.error(error));\n```\n\n## API Reference\n\n### encode(address, language?)\n\nConverts an address string to geographic coordinates.\n\n```typescript\nfunction encode(\n\tformattedAddress: string,\n\tlanguage?: string = 'en',\n): Promise\u003cLocation[]\u003e;\n```\n\n**Returns**: Array of location objects with coordinates and formatted address.\n\n### decode(latitude, longitude, language?)\n\nConverts geographic coordinates to an address.\n\n```typescript\nfunction decode(\n\tlatitude: number,\n\tlongitude: number,\n\tlanguage?: string = 'en',\n): Promise\u003cLocation | null\u003e;\n```\n\n**Returns**: Location object with formatted address and Google Plus Code, or null if not found.\n\n### Location Interface\n\n```typescript\ninterface Location {\n\tlatitude?: number;\n\tlongitude?: number;\n\tgoogle_plus_code?: string;\n\tformatted_address?: string;\n}\n```\n\n## Language Support\n\nSpecify a language code as the last parameter to get results in different languages:\n\n```javascript\n// Get results in French\ngeocoding\n\t.encode('Tour Eiffel, Paris', 'fr')\n\t.then((locations) =\u003e console.log(locations));\n\n// Get results in Japanese\ngeocoding\n\t.decode(35.6895, 139.6917, 'ja')\n\t.then((location) =\u003e console.log(location));\n```\n\nSupports all language codes that Google Maps supports (e.g., `en`, `fr`, `de`, `ja`, `zh-CN`, `es`, etc.)\n\n## Example Output\n\n### Geocoding Result\n\n```javascript\n[\n\t{\n\t\tformatted_address:\n\t\t\t'Empire State Building, 20 W 34th St, New York, NY 10001, United States',\n\t\tlatitude: 40.7484405,\n\t\tlongitude: -73.9856644,\n\t},\n];\n```\n\n### Reverse Geocoding Result\n\n```javascript\n{\n\tlatitude: 40.7484,\n\tlongitude: -73.9857,\n\tformatted_address: 'Empire State Building, 20 W 34th St, New York, NY 10001, United States',\n\tgoogle_plus_code: '87G8Q2M4+96'\n}\n```\n\n## Using with TypeScript\n\n```typescript\nimport { encode, decode, Location } from '@aashari/nodejs-geocoding';\n\nasync function getLocationData(): Promise\u003cvoid\u003e {\n\ttry {\n\t\t// Forward geocoding\n\t\tconst locations: Location[] = await encode('Tokyo Tower, Japan');\n\n\t\t// Reverse geocoding\n\t\tif (locations.length \u003e 0) {\n\t\t\tconst { latitude, longitude } = locations[0];\n\t\t\tconst address: Location | null = await decode(latitude, longitude);\n\t\t\tconsole.log(address);\n\t\t}\n\t} catch (error) {\n\t\tconsole.error('Error:', error);\n\t}\n}\n```\n\n## Advanced Usage Examples\n\n### With Async/Await\n\n```javascript\nasync function getLocationInfo() {\n\ttry {\n\t\t// Geocoding\n\t\tconst coordinates = await geocoding.encode('Colosseum, Rome');\n\t\tconsole.log('Coordinates:', coordinates);\n\n\t\t// Reverse Geocoding using the first result\n\t\tif (coordinates \u0026\u0026 coordinates.length \u003e 0) {\n\t\t\tconst { latitude, longitude } = coordinates[0];\n\t\t\tconst address = await geocoding.decode(latitude, longitude);\n\t\t\tconsole.log('Address:', address);\n\t\t}\n\t} catch (error) {\n\t\tconsole.error('Error:', error);\n\t}\n}\n```\n\n### Error Handling\n\n```javascript\nasync function safeGeocode(address) {\n\ttry {\n\t\tconst results = await geocoding.encode(address);\n\t\tif (!results || results.length === 0) {\n\t\t\tconsole.log(`No results found for address: ${address}`);\n\t\t\treturn null;\n\t\t}\n\t\treturn results;\n\t} catch (error) {\n\t\tconsole.error(`Error geocoding address \"${address}\":`, error);\n\t\treturn null;\n\t}\n}\n```\n\n## License\n\nThis project is licensed under the MIT License.\n\n---\n\nMade with ❤️ by [aashari](https://github.com/aashari)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faashari%2Fnodejs-geocoding","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faashari%2Fnodejs-geocoding","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faashari%2Fnodejs-geocoding/lists"}