{"id":23148305,"url":"https://github.com/sparkfish/orbitron","last_synced_at":"2025-08-17T17:33:47.844Z","repository":{"id":45414790,"uuid":"335762465","full_name":"sparkfish/orbitron","owner":"sparkfish","description":"\"Near Me\" search API for exposing your geocoded tabular data","archived":false,"fork":false,"pushed_at":"2023-04-11T21:36:38.000Z","size":60,"stargazers_count":4,"open_issues_count":7,"forks_count":2,"subscribers_count":4,"default_branch":"dev","last_synced_at":"2024-05-01T09:37:51.217Z","etag":null,"topics":["find-me","geolocation","geospatial","location-based","location-finder","location-services","nearby-api","nearby-locations","nearby-places","nearest-neighbor-search","nearest-neighbors","nearest-neighbours"],"latest_commit_sha":null,"homepage":"https://orbitron-dev.azurewebsites.net/nearest/100/pharmacies/to/75001","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/sparkfish.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}},"created_at":"2021-02-03T21:39:54.000Z","updated_at":"2024-04-23T01:28:12.000Z","dependencies_parsed_at":"2023-09-25T02:08:50.363Z","dependency_job_id":null,"html_url":"https://github.com/sparkfish/orbitron","commit_stats":{"total_commits":25,"total_committers":5,"mean_commits":5.0,"dds":"0.43999999999999995","last_synced_commit":"cc369a5c5b119a6930eb94ec0b9abc7b302c9c4d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparkfish%2Forbitron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparkfish%2Forbitron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparkfish%2Forbitron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparkfish%2Forbitron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sparkfish","download_url":"https://codeload.github.com/sparkfish/orbitron/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230151965,"owners_count":18181327,"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":["find-me","geolocation","geospatial","location-based","location-finder","location-services","nearby-api","nearby-locations","nearby-places","nearest-neighbor-search","nearest-neighbors","nearest-neighbours"],"created_at":"2024-12-17T17:10:08.377Z","updated_at":"2024-12-17T17:10:09.122Z","avatar_url":"https://github.com/sparkfish.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n        \u003cimg src=\"orbitron.svg\" width=\"500\" align=\"center\"\u003e\u003c/image\u003e \u003cbr /\u003e\n        \u003ch3 align=\"center\"\u003e\u003ci\u003eA \u0026ldquo;near me\u0026rdquo; microservice for exposing your geocoded tabular data\u003c/i\u003e\u003c/h3\u003e\n\u003c/p\u003e\n\n\u003chr size=\"4\" noshade=\"noshade\" /\u003e\n\n**Orbitron** is a microservice that you can deploy into your environment to expose a **location finder service** within your own applications.  The service can be deployed in minutes to a cloud provider with minimal dependencies.  A simple script is provided to help you upload your data to a PorgresSQL server instance.\n\n## Usage\n\nTo perform a search against your endpoint, simply use the following fluent URL: `/nearest/{limit}/{source-name}/to/{zip-code}`.  This will perform a distance search against stored geocoded tabular data using functionality exposed through PostgreSQL.\n\n## Example\nA query for the nearest pharmacies: `/nearest/100/pharmacies/to/75001`\n\n```javascript\n{\n        \"name\": \"Mom \u0026 Pop's Local Pharmacy\",\n        \"latitude\": 33.435921,\n        \"longitude\": -111.720686,\n        ...\n}\n```\n\n#### Custom Data Models\nAdditional data fields may be returned depending upon the contents of \"rowdata\" field in the database.  It may vary depending on the data source type, i.e. if the geopoint represents a store or office, it may be convenient to include a contact phone number, but for something like a national monument, it might be helpful to include a construction date or other historical details of interest.\n\n\n\u003chr size=\"4\" noshade=\"noshade\" /\u003e\n\n## Dependencies\n\nThis software requires access to a postgresql server with PostGIS 2.5.1 (or compatible version), with credentials set in a configuration file named \".env\".  A `sample.env` file is included.\n\nBuilding the postal code geodata also requires the file US.txt from geoname.org's free data at http://download.geonames.org/export/zip/ \n\n## Installation\n\nEdit the file `sample.env` to reflect your postgresql credentials, and save the updated file as `.env` in the root folder of the project.\n\nPlace US.txt in the root folder and execute `python install.py` to perform initial database setup.\n\n## Configuring Location Data\n\nYour location data needs to be tied to a `sourceType` defined in the `Orbitron.Sources` table.  The `Name` field will correspond to the `{source-type}` parameter of the request URL.  The script `load.py` can be used to load the neighbor data, it takes a *csv* file as a parameter, i.e. `python load.py ./example.csv`.  The *csv* file should have columns in the following order:\n\n```javascript\n[ \"SourceId\", \"Name\", \"Latitude\", \"Longitude\", \"RowData\" ]\n```\n\n* `SourceId` is the appropriate Id of a source from the `Orbitron.Sources` table\n* `Name` is the name of the location\n* `Latitude` and `Longitude` are geocoordinates of each location\n* `RowData` is any additional data that is to be associated with the record, formatted as a *JSON* string\n\nFor example, the *csv* file might be formatted as follows, and should not contain a header row:\n\n```javascript\n1,Test Location,42.872004,-87.952139,\"{\"\"phone\"\": \"\"555-555-5555\"\"}\"\n```\n\n#### Geocoding Your Dataset\n\nIf you do not have the *latitude* \u0026 *longitude* information for the locations in your dataset, but you do have address information, then you'll need to run the addresses through a geocoding service, such as https://www.geocod.io/.\n\n## Running\n\nUsing `Python\u003e=3.8`, install dependencies with `pip install -r requirements.txt`.  To start a development server, run `uvicorn main:app --reload`.\n\nSee [http://localhost:8000/docs](http://localhost:8000/docs) for auto-generated Swagger API documentation.\n\n## Quick start using open pharamacy location data on local development server\n1. Set up a postgresql instance with PostGIS\n\n2. Perform installation as indicated in *\"Installation\"* section.\n\n3. Download Rx Open's pharacy location database from https://rxopen.org/api/v1/map/download/facility and place the resulting `facility.csv` in the project's root folder.\n\n4. Execute `python import-pharmacies.py`\n\n5. Run development server, as indicated in *\"Running\"* section.\n\nYou should now be able to issue http requests using the API endpoints against the local server, such as `http://localhost:8000/nearest/100/pharmacies/to/75001`\n\n## Running in Azure\nThis software can run in an Azure App Service with the custom startup command `python -m uvicorn main:app --host 0.0.0.0`\n\n## Credits\n\nA special thanks goes to [Matt McInerney](http://pixelspread.com/) for freely sharing his futuristic Orbitron font.\n\n## License\n\nThis is an open source project licensed under MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparkfish%2Forbitron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsparkfish%2Forbitron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparkfish%2Forbitron/lists"}