{"id":34924502,"url":"https://github.com/geosensing/geo-sampling","last_synced_at":"2025-12-26T14:18:03.874Z","repository":{"id":57433832,"uuid":"71066467","full_name":"geosensing/geo-sampling","owner":"geosensing","description":"Randomly sample locations on streets","archived":false,"fork":false,"pushed_at":"2025-12-16T04:59:41.000Z","size":4019,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"public","last_synced_at":"2025-12-19T14:51:08.151Z","etag":null,"topics":["osm","random-locations","random-sampling","streetview"],"latest_commit_sha":null,"homepage":"https://geosensing.github.io/geo-sampling/","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/geosensing.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":"Citation.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2016-10-16T17:40:46.000Z","updated_at":"2025-12-16T04:59:45.000Z","dependencies_parsed_at":"2025-04-11T19:54:15.408Z","dependency_job_id":"e4189ce0-00ec-4810-a10f-81fc89c684d8","html_url":"https://github.com/geosensing/geo-sampling","commit_stats":null,"previous_names":["soodoku/geo_sampling","geosensing/geo-sampling"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/geosensing/geo-sampling","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geosensing%2Fgeo-sampling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geosensing%2Fgeo-sampling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geosensing%2Fgeo-sampling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geosensing%2Fgeo-sampling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/geosensing","download_url":"https://codeload.github.com/geosensing/geo-sampling/tar.gz/refs/heads/public","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geosensing%2Fgeo-sampling/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28055966,"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-12-26T02:00:06.189Z","response_time":55,"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":["osm","random-locations","random-sampling","streetview"],"created_at":"2025-12-26T14:18:00.762Z","updated_at":"2025-12-26T14:18:03.865Z","avatar_url":"https://github.com/geosensing.png","language":"Python","readme":"# Geo sampling: Randomly sample locations on streets\n\n[![CI](https://github.com/geosensing/geo-sampling/actions/workflows/ci.yml/badge.svg)](https://github.com/geosensing/geo-sampling/actions/workflows/ci.yml)\n[![PyPI version](https://img.shields.io/pypi/v/geo_sampling.svg?maxAge=3600)](https://pypi.python.org/pypi/geo_sampling)\n[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://geosensing.github.io/geo-sampling/)\n[![Downloads](https://pepy.tech/badge/geo-sampling)](https://pepy.tech/project/geo-sampling)\n\nSay you want to learn about the average number of potholes per kilometer of street in a city. Or estimate a similar such quantity. To estimate the quantity, you need to sample locations on the streets. This package helps you sample those locations. In particular, the package implements the following sampling strategy:\n\n## Sampling Strategy\n\n### 1. Sampling Frame\nGet all the streets in the region of interest from [OpenStreetMap](https://www.openstreetmap.org/#map=5/51.500/-0.100). To accomplish that, the package first downloads administrative boundary data for the country in which the region is located in ESRI format from http://www.gadm.org/country. The administrative data is in multiple levels, for instance, cities are nested in states, which are nested in countries. The user can choose a city or state, but not a portion of a city. And then the package uses the [pyshp package](https://pypi.python.org/pypi/pyshp) to build a URL for the site http://extract.bbbike.org from which we can download the OSM data.\n\n### 2. Sampling Design\n\n* For each street (or road), starting from one end of the street, we split the street into .5 km segments till we reach the end of the street. (The last segment, or if the street is shorter than .5km, the only segment, can be shorter than .5 km.)\n\n* Get the lat/long of starting and ending points of each of the segments. And assume that the street is a straight line between the .5 km segment.\n\n* Next, create a database of all the segments\n\n* Sample rows from the database and produce a CSV of the sampled segments\n\n* Plot the lat/long --- filling all the area within the segment. These shaded regions are regions for which data needs to be collected.\n\n### 3. Data Collection\nCollect data on the highlighted segments.\n\n## Installation\n\n### Prerequisites\n\nThe package requires Python 3.11 or higher. Install the package from PyPI:\n\n```bash\npip install geo-sampling\n```\n\n### Development Installation\n\nFor development, install with development dependencies:\n\n```bash\ngit clone https://github.com/geosensing/geo-sampling.git\ncd geo-sampling\nuv sync --group dev\n```\n\n#### Pre-commit Hooks\n\nTo ensure code quality, install pre-commit hooks:\n\n```bash\nuv run pre-commit install\n```\n\nThis will automatically run linting, formatting, and type checking before each commit. You can also run the hooks manually:\n\n```bash\nuv run pre-commit run --all-files\n```\n\n## Quick Start\n\n### Command Line Interface\n\nComplete workflow in one command:\n\n```bash\n# Install the package\npip install geo-sampling\n\n# Sample 100 road segments from Singapore\ngeo-sampling workflow \"Singapore\" \"Central\" \\\n    --sample-size 100 \\\n    --output singapore_sample.csv \\\n    --plot\n```\n\n### Python API\n\n```python\nimport geo_sampling as gs\n\n# Quick sampling for research\nsample = gs.sample_roads_for_region(\n    \"Singapore\", \"Central\",\n    n=100,\n    strategy=\"random\"\n)\n\n# Plot and save\ngs.quick_plot(sample, title=\"Singapore Sample\")\nsampler = gs.RoadSampler(sample)\nsampler.save_csv(sample, \"singapore_sample.csv\")\n```\n\n## Documentation\n\n📖 **[Complete Documentation](https://geosensing.github.io/geo-sampling/)** - Comprehensive guides and examples\n\n🚀 **[Quick Start Guide](https://geosensing.github.io/geo-sampling/quickstart.html)** - Get up and running in 5 minutes\n\n🐍 **[Python API Examples](https://geosensing.github.io/geo-sampling/examples/python-api.html)** - Complete code examples with real data\n\n💻 **[CLI Usage Guide](https://geosensing.github.io/geo-sampling/examples/cli-usage.html)** - Command-line interface examples\n\n📁 **[Example Outputs](examples/outputs/)** - Download real sample data and plots\n\n## 🔗 Adjacent Repositories\n\n- [geosensing/latlong-to-zip](https://github.com/geosensing/latlong-to-zip) — Reverse Geocode Lat/Long to Zip Codes using GeoNames, AskGeo, or Google. Compare Geocoding Services.\n- [geosensing/autosense](https://github.com/geosensing/autosense) — AutoSense: Automated Street Condition Assessment\n- [geosensing/streetsense](https://github.com/geosensing/streetsense) — Street Sense: Learning from Google Street View\n- [geosensing/women-count](https://github.com/geosensing/women-count) — Missing Women on the streets of Delhi\n- [geosensing/missing_women](https://github.com/geosensing/missing_women) — Missing Women On the Streets: Evidence from Mumbai\n## Authors\n\nSuriyan Laohaprapanon and Gaurav Sood\n\n## License\n\nScripts are released under the [MIT License](LICENSE).\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeosensing%2Fgeo-sampling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeosensing%2Fgeo-sampling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeosensing%2Fgeo-sampling/lists"}