{"id":25135052,"url":"https://github.com/tractr/earth-pixel","last_synced_at":"2025-10-20T01:21:20.691Z","repository":{"id":29710258,"uuid":"122560283","full_name":"tractr/earth-pixel","owner":"tractr","description":"Geo-location approximation algorithm","archived":false,"fork":false,"pushed_at":"2022-12-02T17:43:36.000Z","size":2131,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-02-08T16:17:57.953Z","etag":null,"topics":["approximation","caching","geolocation","search-engine"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tractr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-23T01:58:03.000Z","updated_at":"2021-10-18T17:44:18.000Z","dependencies_parsed_at":"2023-01-14T15:30:45.276Z","dependency_job_id":null,"html_url":"https://github.com/tractr/earth-pixel","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tractr%2Fearth-pixel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tractr%2Fearth-pixel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tractr%2Fearth-pixel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tractr%2Fearth-pixel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tractr","download_url":"https://codeload.github.com/tractr/earth-pixel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246922245,"owners_count":20855345,"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":["approximation","caching","geolocation","search-engine"],"created_at":"2025-02-08T16:17:59.365Z","updated_at":"2025-10-20T01:21:15.636Z","avatar_url":"https://github.com/tractr.png","language":"JavaScript","readme":"# Earth-Pixel\n\nGeo-location approximation algorithm.\n\n[![Build Status](https://travis-ci.com/Tractr/earth-pixel.svg?branch=master)](https://travis-ci.com/Tractr/earth-pixel) [![codecov](https://codecov.io/gh/Tractr/earth-pixel/branch/master/graph/badge.svg)](https://codecov.io/gh/Tractr/earth-pixel)\n\nThe goal of this package is to provide a method to group geo-localized requests in order to share responses cache.\n\nAs a requirement, your app must accept approximation of the position of a geo-localized request.\nIf not, there is no need to use this package.\n\nTo do so, we consider the geo-location as a discreet value and not a continuous value.\nIt's like seeing the earth as a disco ball.\n\nWe split the earth into nearly-squares called pixels. Those pixels have a customizable width.\nEach pixel is identified by a unique key.\nEach location on earth is hosted by a pixel.\nAll the locations contained in a pixel share the same unique key. \nAll the locations contained in a pixel can be approximated to the center of this pixel.\n\nTherefore, each location can be converted into a unique key and shares this key with the neighbourhood.\n\nHere is a visual example:\n\n![Visual EarthPixel](./map/preview.png \"Visual EarthPixel\")\n\n## Installation\n\nTo install this package, run\n\n```bash\nnpm install --save earth-pixel\n```\n\n## Usage\n\n### Import\n\n```javascript\nconst EarthPixel = require(\"earth-pixel\");\n```\n\nor\n\n```javascript\nimport EarthPixel from 'earth-pixel';\n```\n\n### Constructor\n\nFirst of all, you must define the size of the pixel, in meters or in degrees (at latitude 0).\n\nIn meters\n```javascript\nconst ep = new EarthPixel(500);\n```\n\nEquivalent to\n```javascript\nconst ep = new EarthPixel(500, 'meters');\n```\n\nIn degrees:\n```javascript\nconst ep = new EarthPixel(0.05, 'degrees');\n```\n\nThe size of the pixel cannot be greater than 45 degrees.\n\n### Methods\n\n#### Encode position\n\nThis package exposes one main instance method: `get(position)`.\nThis returns the position of the center of the pixel, its bounds, its widths and its unique key.\n\nExample:\n\n```javascript\nconst ep = new EarthPixel(500);\n \n// get method\nep.get({ latitude: 46.4567, longitude: 6.5461 });\n\n// Will return\n// {\n//     center: {\n//         latitude: 46.45799199725,\n//         longitude: 6.5434950828\n//     },\n//     bounds: {\n//         north: 46.4602402548,\n//         east: 6.546758672,\n//         south: 46.4557437397,\n//         west: 6.5402314936\n//     },\n//     widths: {\n//         latitude: 0.0044965152,\n//         longitude: 0.0065271784\n//     },\n//     key: '9c5f-768b-6fa3'\n// }\n```\n\n#### Decode position\n\nYou can reverse a generated key to its pixel's info.\nTo do so, call the static method `extract`.\nThis parses the key and extracts the base pixel's data.\n\nExample:\n\n```javascript\n// extract method\nEarthPixel.extract('9c5f-6bb8-a2c5');\n\n// Will return\n// {\n//     center: {\n//         latitude: 33.99814865515,\n//         longitude: 46.00066283345\n//     },\n//     bounds: {\n//         north: 34.0003969127,\n//         east: 46.003374657,\n//         south: 33.9959003976,\n//         west: 45.9979510099\n//     },\n//     widths: {\n//         latitude: 0.0044965152,\n//         longitude: 0.0054236471\n//     },\n//     key: '9c5f-6bb8-a2c5'\n// }\n```\n\nWith this method, a front-end can request items by passing the pixel key and the back-end will be able to decode the location and perform the request.\nThis is really useful to optimize CDN caching.\n\n#### Debug\n\nFor debugging, you can call the `debug()` function to get the width of the base pixel (in degrees) and the amount of divisions used by the algorithm.\n\nExample:\n\n```javascript\nconst ep = new EarthPixel(500);\n \n// debug method\nep.debug();\n\n// Will return\n// {\n//     width: 0.0044965152,\n//     divisions: 40031\n// }\n```\n\n#### Precision\n\nTo avoid the javascript issue `0.2 + 0.4 = 0.6000000000000001`, all floating values are converted into integers before being manipulated.\nThe factor used to convert floats into integers is called precision.\nTo get this value, call the static method `precision()`. \n\nExample:\n\n```javascript\n// precision method\nEarthPixel.precision();\n\n// Will return 1e10\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftractr%2Fearth-pixel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftractr%2Fearth-pixel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftractr%2Fearth-pixel/lists"}