{"id":23926367,"url":"https://github.com/ixnode/node-geo-sphere","last_synced_at":"2025-06-19T06:35:06.479Z","repository":{"id":271029747,"uuid":"912109379","full_name":"ixnode/node-geo-sphere","owner":"ixnode","description":"A Node.js package for rendering interactive world maps with Mercator projection, customizable languages, and advanced interactivity features such as zoom, pan, and click events.","archived":false,"fork":false,"pushed_at":"2025-02-01T12:45:38.000Z","size":6375,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-25T23:17:01.611Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ixnode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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,"zenodo":null}},"created_at":"2025-01-04T16:22:12.000Z","updated_at":"2025-02-01T12:45:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"77273e07-1f14-4533-8b53-2f4d25efeebd","html_url":"https://github.com/ixnode/node-geo-sphere","commit_stats":null,"previous_names":["ixnode/node-geo-sphere"],"tags_count":48,"template":false,"template_full_name":null,"purl":"pkg:github/ixnode/node-geo-sphere","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ixnode%2Fnode-geo-sphere","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ixnode%2Fnode-geo-sphere/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ixnode%2Fnode-geo-sphere/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ixnode%2Fnode-geo-sphere/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ixnode","download_url":"https://codeload.github.com/ixnode/node-geo-sphere/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ixnode%2Fnode-geo-sphere/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260703114,"owners_count":23049410,"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","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":[],"created_at":"2025-01-05T21:14:04.540Z","updated_at":"2025-06-19T06:35:01.469Z","avatar_url":"https://github.com/ixnode.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @ixnode/geo-sphere\r\n\r\n[![Release](https://img.shields.io/github/v/release/ixnode/node-geo-sphere)](https://github.com/ixnode/node-geo-sphere/releases)\r\n[![Release date](https://img.shields.io/github/release-date/ixnode/node-geo-sphere)](https://github.com/twelvepics-com/php-calendar-builder/releases)\r\n[![npm version](https://badge.fury.io/js/@ixnode%2Fgeo-sphere.svg)](https://www.npmjs.com/package/@ixnode/geo-sphere)\r\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7.3-555555.svg?logo=typescript\u0026logoColor=white\u0026labelColor=3178c6\u0026style=flat)](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html)\r\n[![React](https://img.shields.io/badge/ReactJS-8.3.1-555555.svg?logo=react\u0026logoColor=white\u0026labelColor=87c2d9\u0026style=flat)](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html)\r\n[![Storybook](https://img.shields.io/badge/Storybook-8.4.7-555555.svg?logo=storybook\u0026logoColor=white\u0026labelColor=ff4785\u0026style=flat)](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html)\r\n[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)\r\n\r\n`@ixnode/geo-sphere` is a powerful and flexible Node.js package for rendering interactive maps. It supports various\r\nprojections (_currently only Mercator projection - more are planned_), languages, and advanced interactivity, allowing\r\nyou to display geographical points and create a fully interactive mapping experience.\r\n\r\n## 🚀 Features\r\n\r\n* **Map Display**: Render world maps or other geographical maps in Mercator projection.\r\n* **Point Rendering**: Display geographical points using latitude and longitude.\r\n* **Resizable**: Dynamically adjust the map size to fit different screen dimensions.\r\n* **Integrated Country Database**: Includes all countries with multiple resolution levels by default.\r\n* **Interactive Countries**: Countries can be clicked, triggering a customizable callback function. Hover and title effects are also supported.\r\n* **Multi-language Support**: Available in multiple languages: `cz`|`de`|`en`|`es`|`fr`|`hr`|`it`|`pl`|`sv`.\r\n* **Mouse and Touch Interaction**: The map supports zooming and panning via mouse and touch gestures.\r\n* **Lightweight** and built with TypeScript\r\n* Build on top with [storybook](https://storybook.js.org/)\r\n\r\n## 📦 Installation\r\n\r\n```shell\r\nnpm install @ixnode/geo-sphere\r\n```\r\n\r\nor\r\n\r\n```shell\r\nyarn add @ixnode/geo-sphere\r\n```\r\n\r\n## 🔧 Usage\r\n\r\n### Display example\r\n\r\n#### **Example**: France is selected, but the mouse is hovering over Berlin, Germany.\r\n\r\n![Basic world.](docs/images/map.png \"Example map.\")\r\n\r\n#### **Example**: The United States are selected. The city Austin was clicked.\r\n\r\n![Basic world.](docs/images/map2.png \"Example map.\")\r\n\r\n### Basic Usage\r\n\r\n```tsx\r\nimport React from 'react';\r\nimport { WorldMap } from '@ixnode/geo-sphere';\r\nimport '@ixnode/geo-sphere/dist/styles.css';\r\n\r\nconst App = () =\u003e (\r\n    \u003cWorldMap\r\n        height={500}\r\n        width={1000}\r\n        country=\"de\"\r\n        language=\"en\"\r\n    /\u003e\r\n);\r\n\r\nexport default App;\r\n```\r\n\r\n### Usage with country callback function\r\n\r\n```tsx\r\nimport React from 'react';\r\nimport { WorldMap, CountryData } from '@ixnode/geo-sphere';\r\nimport '@ixnode/geo-sphere/dist/styles.css';\r\n\r\nconst App = () =\u003e (\r\n    \u003cWorldMap\r\n        height={500}\r\n        width={1000}\r\n        country=\"de\"\r\n        language=\"en\"\r\n        dataSource=\"medium\"\r\n        onClickCountry={(data: CountryData) =\u003e { console.log(data); }}\r\n    /\u003e\r\n);\r\n\r\nexport default App;\r\n```\r\n\r\nThe callback function logs something like (according to the clicked country and the given language):\r\n\r\n```json\r\n{\r\n    \"id\": \"de\",\r\n    \"name\": \"Germany\",\r\n    \"latitude\": 50.304018990688554,\r\n    \"longitude\": 7.5794992771470975,\r\n    \"screenPosition\": {\r\n        \"x\": 401,\r\n        \"y\": 333\r\n    },\r\n    \"svgPosition\": {\r\n        \"x\": 843746,\r\n        \"y\": 6499094\r\n    }\r\n}\r\n```\r\n\r\n| Property           | Description                                                     |\r\n|--------------------|-----------------------------------------------------------------|\r\n| `id`               | The id of clicked element.                                      |\r\n| `name`             | The translated name of clicked element.                         |\r\n| `latitude`         | The latitude value. Clicked on the map.                         |\r\n| `longitude`        | The longitude value. Clicked on the map.                        |\r\n| `screenPosition.x` | The x position of the last click. Related to the screen.        |\r\n| `screenPosition.y` | The y position of the last click. Related to the screen.        |\r\n| `svgPosition.x`    | The x position of the last click. Related to the whole svg map. |\r\n| `svgPosition.y`    | The x position of the last click. Related to the whole svg map. |\r\n\r\n### Usage with place callback function\r\n\r\n```tsx\r\nimport React from 'react';\r\nimport { WorldMap, PlaceData } from '@ixnode/geo-sphere';\r\nimport '@ixnode/geo-sphere/dist/styles.css';\r\n\r\nconst App = () =\u003e (\r\n    \u003cWorldMap\r\n        height={500}\r\n        width={1000}\r\n        country=\"de\"\r\n        language=\"en\"\r\n        dataSource=\"medium\"\r\n        onClickPlace={(data: PlaceData) =\u003e { console.log(data); }}\r\n    /\u003e\r\n);\r\n\r\nexport default App;\r\n```\r\n\r\nThe callback function logs something like (according to the clicked place and the given language):\r\n\r\n```json\r\n{\r\n    \"id\": \"place-berlin\",\r\n    \"latitude\": 52.5235,\r\n    \"longitude\": 13.4115,\r\n    \"name\": \"Berlin\",\r\n    \"population\": 3662381, \r\n    \"country\": {\r\n        \"id\": \"de\",\r\n        \"name\": \"Germany\"\r\n    },\r\n    \"state\": {\r\n        \"id\": \"de-be\",\r\n        \"name\": \"Berlin\",\r\n        \"area\": 891.1,\r\n        \"population\": 3662381\r\n    },\r\n    \"screenPosition\": {\r\n        \"x\": 629,\r\n        \"y\": 295 \r\n    },\r\n    \"svgPosition\": {\r\n        \"x\": 1580.7000732421875,\r\n        \"y\": 6909.73095703125\r\n    }\r\n}\r\n```\r\n\r\n| Property           | Description                                                     |\r\n|--------------------|-----------------------------------------------------------------|\r\n| `id`               | The id of clicked element.                                      |\r\n| `name`             | The translated name of clicked element.                         |\r\n| `population`       | The population of clicked element.                              |\r\n| `latitude`         | The latitude value. Clicked on the map.                         |\r\n| `longitude`        | The longitude value. Clicked on the map.                        |\r\n| `screenPosition.x` | The x position of the last click. Related to the screen.        |\r\n| `screenPosition.y` | The y position of the last click. Related to the screen.        |\r\n| `svgPosition.x`    | The x position of the last click. Related to the whole svg map. |\r\n| `svgPosition.y`    | The x position of the last click. Related to the whole svg map. |\r\n\r\n## 🔧 Properties\r\n\r\n| Property         | Type                                                                   | Default | Description                                                                                     |\r\n|------------------|------------------------------------------------------------------------|---------|-------------------------------------------------------------------------------------------------|\r\n| `dataSource`     | `'tiny'\\|'low'\\|'medium'`                                              | `'low'` | The data source to be used.                                                                     |\r\n| `country`        | `string\\|null`                                                         | `null`  | The country that is marked.                                                                     |\r\n| `width`          | `number`                                                               | `1000`  | The width of the map in pixels. Only used for ratio. The svg is always 100% of parent element.  |\r\n| `height`         | `number`                                                               | `500`   | The height of the map in pixels. Only used for ratio. The svg is always 100% of parent element. |\r\n| `language`       | `'cz'`\\|`'de'`\\|`'en'`\\|`'es'`\\|`'fr'`\\|`'hr'`\\|`'it'`\\|`'pl'`\\|`'sv'` | `'en'`  | The language to be used.                                                                        |\r\n| `onClickCountry` | `(data: CountryData) =\u003e void\\|null`                                    | `null`  | An optional country click handler.                                                              |\r\n| `onClickPlace`   | `(data: PlaceData) =\u003e void\\|null`                                      | `null`  | An optional place click handler.                                                                |\r\n| `onHoverCountry` | `(data: CountryData) =\u003e void\\|null`                                    | `null`  | An optional country hover handler.                                                              |\r\n| `onHoverPlace`   | `(data: PlaceData) =\u003e void\\|null`                                      | `null`  | An optional place hover handler.                                                                |\r\n| `debug`          | `boolean`                                                              | `false` | Flag to enable or disable the debug mode.                                                       |\r\n| `logo`           | `boolean`                                                              | `true`  | Flag to enable or disable the logo.                                                             |\r\n\r\n### Common countries (`country`)\r\n\r\nUse `ISO 3166-1 alpha-2` code to select a country. Examples:\r\n\r\n| Country                                              | ISO code |\r\n|------------------------------------------------------|----------|\r\n| United Kingdom of Great Britain and Northern Ireland | `gb`     |\r\n| United States of America                             | `us`     |                       \r\n| Germany                                              | `de`     |                                        \r\n| Sweden                                               | `se`     |                                         \r\n| etc.                                                 |                                      \r\n\r\nSee https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for more information.\r\n\r\n### Common languages (`language`)\r\n\r\nCurrently supported languages:\r\n\r\n| Language | Description |\r\n|----------|-------------|\r\n| `cz`     | Czech       |\r\n| `de`     | German      |\r\n| `en`     | English     |\r\n| `es`     | Spanish     |\r\n| `fr`     | French      |\r\n| `hr`     | Croatian    |\r\n| `it`     | Italian     |\r\n| `pl`     | Polish      |\r\n| `sv`     | Swedish     |\r\n\r\n## 🛠 Development\r\n\r\n### Building the Project\r\n\r\nTo build the project locally:\r\n\r\n```shell\r\nnpm run build\r\n```\r\n\r\n### Running Storybook\r\n\r\nView and develop components in isolation:\r\n\r\n```shell\r\nnpm run storybook\r\n```\r\n\r\nOpen: http://localhost:6006/\r\n\r\n#### **Example**: The country Portugal and language spanisch is selected, but the mouse is hovering over Madrid, Spain.\r\n\r\n![Storybook](docs/images/storybook.png \"Storybook\")\r\n\r\n## 📦 Publishing to npm\r\n\r\n### Check TypeScript Code\r\n\r\n* Runs the TypeScript compiler to detect errors without generating any JavaScript output\r\n* Should not throw an error\r\n\r\n```shell\r\nnpx tsc --noEmit\r\n```\r\n\r\n### Build the project\r\n\r\n* Runs the build process to produce production-ready artifacts\r\n* Test build for a future release process to npmjs.org\r\n* Should not throw an error\r\n\r\n```shell\r\nnpm run build\r\n```\r\n\r\n### Verify the build\r\n\r\n* Checks that the compiled code runs as expected\r\n* Should not throw an error\r\n\r\n#### ES Modules build\r\n\r\n```shell\r\nnode dist/index.js\r\n```\r\n\r\nor to ignore possible warnings:\r\n\r\n```shell\r\nnode --no-warnings dist/index.js\r\n```\r\n\r\n#### CommonJS build\r\n\r\n```shell\r\nnode dist/index.cjs\r\n```\r\n\r\n### Bump the version\r\n\r\nUpdate the version in the package.json, e.g., from 1.0.0 to 1.0.1, to create a new release:\r\n\r\n```shell\r\nnpm version patch\r\n```\r\n\r\nAlternatively:\r\n\r\n* Use `npm version minor` for new features.\r\n* Use `npm version major` for breaking changes.\r\n\r\n### Publish the package\r\n\r\n```shell\r\nnpm publish --access public\r\n```\r\n\r\n### Verify the publication\r\n\r\nCheck the package on npm: [https://www.npmjs.com/package/@ixnode/geo-sphere](https://www.npmjs.com/package/@ixnode/geo-sphere).\r\n\r\n## 📄 License\r\n\r\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for details.\r\n\r\n### Authors\r\n\r\n* Björn Hempel \u003cbjoern@hempel.li\u003e - _Initial work_ - [https://github.com/bjoern-hempel](https://github.com/bjoern-hempel)\r\n\r\n## 🌟 Contributing\r\n\r\nContributions are welcome! Feel free to submit issues or pull requests to improve this project.\r\n\r\n## 🤝 Acknowledgments\r\n\r\nSpecial thanks to the open-source community for providing amazing tools like React, TypeScript, and Storybook.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fixnode%2Fnode-geo-sphere","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fixnode%2Fnode-geo-sphere","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fixnode%2Fnode-geo-sphere/lists"}