{"id":17700483,"url":"https://github.com/aaron-schroeder/elevation-query","last_synced_at":"2025-04-23T22:28:01.813Z","repository":{"id":118331058,"uuid":"332272554","full_name":"aaron-schroeder/elevation-query","owner":"aaron-schroeder","description":"Python library for acquiring elevation data from GPS coordinates.","archived":false,"fork":false,"pushed_at":"2021-06-04T21:01:14.000Z","size":23,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-30T04:11:22.074Z","etag":null,"topics":["elevation","elevation-api","gis"],"latest_commit_sha":null,"homepage":"","language":"Python","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/aaron-schroeder.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-23T17:49:52.000Z","updated_at":"2024-06-18T14:14:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"38c0cc50-83cc-4246-88d0-2fc65f5703dd","html_url":"https://github.com/aaron-schroeder/elevation-query","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaron-schroeder%2Felevation-query","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaron-schroeder%2Felevation-query/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaron-schroeder%2Felevation-query/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaron-schroeder%2Felevation-query/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaron-schroeder","download_url":"https://codeload.github.com/aaron-schroeder/elevation-query/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250525685,"owners_count":21445067,"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":["elevation","elevation-api","gis"],"created_at":"2024-10-24T17:42:18.180Z","updated_at":"2025-04-23T22:28:01.794Z","avatar_url":"https://github.com/aaron-schroeder.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# elevation-query\n\n\u003e Python library for getting elevation data from GPS coordinates.\n\n\u003c!--[![Python 3.6](https://img.shields.io/badge/python-3.6-blue.svg)](https://www.python.org/downloads/release/python-360/)--\u003e\n[![License](http://img.shields.io/:license-mit-blue.svg)](http://badges.mit-license.org)\n\n---\n\n## Table of Contents                                                                    \n- [Background](#background)\n- [Introduction](#introduction)\n- [Dependencies and Installation](#dependencies-and-installation)\n  - [Base Installation](#base-installation)\n  - [Extra: Elevation values from Google Maps API](#extra-elevaton-values-from-google-maps-api)\n  - [Extra: Elevation values from `.img` and `.geotiff` files](#extra-elevation-values-from-img-and-geotiff-files)\n  - [Possible future data sources](#possible-future-data-sources)\n- [Example](#example) \u003c!-- - [Project Status](#project-status) --\u003e\n- [Contact](#contact)\n- [License](#license)\n\n\n---\n\n## Background\n\nThis project originated as the part of my \n[spatialfriend package](https://github.com/aaron-schroeder/spatialfriend) that\nretrieved elevation coordinates from various sources locally and around the web.\nLately, I've  been interested in keeping my work in more self-contained modules with \nlighter dependencies, so I split it out.\n\n---\n\n## Introduction\n\n\"How high up do you think we are right now?\"\n\nThere are high-quality models of the Earth's surface out there. From those models,\nit's possible to generate so-called \"digital elevation models\" (DEMs), which represent\nthe elevation above sea level at any point within the geographic bounds of the model.\nAnd when you record an activity with a GPS-enabled device, you'll get (at the very \nleast) a series of coordinates representing your horizontal position on the Earth.\nCombine those two sources of data, and you can find out your elevation at each point\nalong your route. \n\nThe `elevation-query` package attempts to bridge the gap between GPS locations and\nelevation data. Give it a series of (lat, lon) coordinates, and it will give you a series\nof elevation coordinates. I don't like to trust just one source of truth, so I provide multiple\nsources of elevation. That way you can compare and contrast. The National Map, Google Maps,\nopen-elevation, and even your own data files. Compare them all. See how they work for you.\nYou're in charge, buster.\n\n*What about Strava's elevation data, and Garmin's, and ... ?* I don't know where they \nget that stuff, and they love to be opaque about their data sources and algorithms. I don't\ntrust what I don't understand. I figured I could get my hands on better stuff anyways.\n\n*What about my GPS device's elevation?* A constellation of satellites is trying to \ntriangulate your elevation from outer space. The vertical accuracy of these satellites is\nabysmal. You might shouldn't look at that data at all.\n\n*What about my high end barometric altimeter?* From what I've seen, those work ok. Unless\nthe weather changes during your hike, altering the barometric pressure without you climbing.\nOr if you fail to calibrate it. Also, I don't own one, and I'm looking to improve my own \nstation in life!\n\nThere are limitations here that cannot be overcome by this package alone. Even on a\nperfectly accurate model of the Earth, with every little detail modeled down to a hair's\nbreadth, you will not get accurate elevation coordinates if your GPS doesn't have you in\nthe right horizontal location. And even if you have the world's best GPS, you will not get\naccurate data from a poorly modeled DEM. The National Map data that this package grants\neasy access to...that's a good DEM (where it exists). So if you have good GPS coordinates,\nyou should get good elevation data from it! The cruel joke is, GPS devices tend to suffer\ntheir worst accuracy in exactly the places where you want it the most: canyons and mountains\nwhere even a small horizontal inaccuracy would make your elevation all wacky. If your GPS\nsays you're down in the gully, well...the DEM is gonna give you elevation coordinates for\nthat gully. That's where we need to smooth out your series of elevation coordinates, ruling\nout silly elevation gains and losses along your route. Or we could correct your horizontal\nposition to a known trail (a process called map-matching), and then look up your elevation\ncoordinates. I am currently working on \n[correcting your improbable elevation time series](https://github.com/aaron-schroeder/pandas-xyz)\n(\"NO I did NOT fall down in the valley for five seconds before climbing back up a sheer cliff\"),\nand I hope to improve [my map-matching algorithm](https://github.com/aaron-schroeder/mapmatching) \nso you can snap your coordinates back to a real trail.\n\nIn the meantime, enjoy these high quality elevation data!!! You don't need a high-end GPS watch\nwith a barometric altimiter to tell you this stuff - there are workarounds if you are inspired.\n\n---\n\n## Dependencies and Installation\n\n### Base Installation\n\n`elevation-query` allows querying of the National Map's \n[Elevation Point Query Service](https://nationalmap.gov/epqs/). This \nservice exposes data from the National Map's 1/3 arc-second Digital \nElevation Model. 1/3 arc-second refers to the data's horizontal \nresolution in terms of degrees; this equates to roughly 30 meters.\n\n`elevation-query` also provides access to the \n[open-elevation](https://open-elevation.com/) REST API through a similar interface.\nThis is not recommended, because the API has become overloaded as more and more users\nhave discovered it. The National Map's reliable REST API should provide superior\nperformance and data, as long as you are looking for coordinates in the U.S.\n\n\u003c!-- open-elevation also lets you download other data from the web (SRTM etc)\nand self-host your own service. From the looks of the Github repo, the download process\nmight not be working anymore. [There's another updated fork here](https://github.com/Developer66/open-elevation),\nI think...kind of a mess. I honestly have not dug in too deep, because the elevation \nservice from The National Map has been suiting my needs just fine. --\u003e\n\n[requests](https://pypi.org/project/requests/) is required for the \nbase installation.\n\nTo install (since I am not on pypi yet), first clone this repo.\n```\ngit clone https://github.com/aaron-schroeder/elevation-query.git\n```\nNow you have a local version of this package that you can install with `pip`\n(the `setup.py` file is configured to make this work).\n\nActivate whatever virtual environment where you wish to install `query`,\nand then:\n```\npip install ${local_path_to_elevation-query_dir}\n```\n\n### Extra: Elevation values from Google Maps API\n\nGoogle Maps provides access to its Elevation API, but you must provide\nyour own API Key. Google will charge you if you exceed the number of free\nrequests in a month. Use at your own risk!\n\n[Google Maps](https://github.com/googlemaps/google-maps-services-python)\nand [NumPy](http://www.numpy.org/) are required.\n\nTo install the extra requirements, follow the [base installation](#base-installation)\ninstructions with this slight modification:\n```\npip install -e ${local_path_to_elevation-query_dir}[google]\n```\n\n### Extra: Elevation values from `.img` and `.geotiff` files\n\n`elevation-query` allows querying of user-owned `.img` and `.geotiff` files\nthat contain elevation data. Such files are available from \n[the National Map's download page](https://apps.nationalmap.gov/downloader).\n\n:warning: Note :warning: this package extra requires [`rasterio`](https://rasterio.readthedocs.io/en/latest/)\nand [`pyproj`](https://pyproj4.github.io/pyproj/stable/), which\ndepend on some heavy-duty geospatial libraries being installed on your computer. \nI cannot cover how to get them here, as the install processes are system-dependent. Consult \n[`rasterio`](https://rasterio.readthedocs.io/en/latest/installation.html) and\n[`pyproj`](https://pyproj4.github.io/pyproj/stable/installation.html) documentation \nto get these set up (yes, that's me punting).\n\nTo install the extra requirements, follow the [base installation](#base-installation)\ninstructions with this slight modification:\n```\npip install -e ${local_path_to_elevation-query_dir}[local]\n```\n\n### Possible future data sources\n\n#### [Open Topo Data](https://www.opentopodata.org/)\n\nSomething new. I am still investigating it.\n\nYou can host it yourself or use the free public API.\n\n\"The public API has a number of open DEM datasets loaded, including a 30m global dataset, \nthe 25m EU-DEM dataset for Europe, and the 10m NED dataset for the US.\"\n\n---\n\n## Example\n\n```python\nimport query\n\nlatlons = [\n  (40.03488860164351, -105.27230724626),\n  (40.03498860164351, -105.27230724626),\n  (40.03508860164351, -105.27230724626),\n  (40.03518860164351, -105.27230724626),\n  (40.03528860164351, -105.27230724626),\n  (40.03538860164351, -105.27230724626),\n  (40.03548860164351, -105.27230724626),\n  (40.03558860164351, -105.27230724626),\n  (40.03568860164351, -105.27230724626),\n  (40.03578860164351, -105.27230724626)\n]\n\n# Each of the following query functions will return\n# your elevation values in meters.\n\n# Only the first two come with the base installation.\nelevs_eqps = query.national_map_epqs(latlons)\n\n# Usually, this is very slow, or fails altogether...\nelevs_oe = query.open_elevation(latlons)\n\n# Make sure your latlons are within the horizontal bounds of your\n# elevation data files first!\nelevs_1m = query.national_map_1m(latlons, 'data.tif')  # .img files work too\n\n# Need your own gmaps API key. Be careful and keep it\n# from being visible on the web.\nfrom config import user_gmaps_key\nelevs_google = query.google(latlons, user_gmaps_key)\n```\n\n---\n\n## Project Status\n\nGood to go. Not sure if I feel like it makes sense to put on PyPi though.\n\n### Future Work\n\n - Generate series of GPS points to compare elevation datasets with each other,\n   and test the effect of smoothing with `pandas-xyz` algorithms.\n\n---\n\n## Contact\n\nReach out to me at one of the following places!\n\n- Website: [trailzealot.com](https://trailzealot.com)\n- LinkedIn: [linkedin.com/in/aarondschroeder](https://www.linkedin.com/in/aarondschroeder/)\n- Twitter: [@trailzealot](https://twitter.com/trailzealot)\n- Instagram: [@trailzealot](https://instagram.com/trailzealot)\n- GitHub: [github.com/aaron-schroeder](https://github.com/aaron-schroeder)\n\n---\n\n## License\n\n[![License](http://img.shields.io/:license-mit-blue.svg)](http://badges.mit-license.org)\n\nThis project is licensed under the MIT License. See\n[LICENSE](https://github.com/aaron-schroeder/py-activityreaders/blob/master/LICENSE)\nfile for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaron-schroeder%2Felevation-query","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaron-schroeder%2Felevation-query","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaron-schroeder%2Felevation-query/lists"}