{"id":34701902,"url":"https://github.com/hubmapconsortium/spatial-api","last_synced_at":"2026-05-27T10:02:17.356Z","repository":{"id":37499857,"uuid":"481702906","full_name":"hubmapconsortium/spatial-api","owner":"hubmapconsortium","description":null,"archived":false,"fork":false,"pushed_at":"2024-01-19T17:14:15.000Z","size":310,"stargazers_count":0,"open_issues_count":14,"forks_count":0,"subscribers_count":12,"default_branch":"main","last_synced_at":"2024-04-14T03:54:46.063Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://spatial.api.hubmapconsortium.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hubmapconsortium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-04-14T18:05:25.000Z","updated_at":"2023-02-10T04:47:42.000Z","dependencies_parsed_at":"2023-11-11T03:27:03.562Z","dependency_job_id":"57ec2439-9a72-4997-a44e-9dfe09e95fbc","html_url":"https://github.com/hubmapconsortium/spatial-api","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/hubmapconsortium/spatial-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hubmapconsortium%2Fspatial-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hubmapconsortium%2Fspatial-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hubmapconsortium%2Fspatial-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hubmapconsortium%2Fspatial-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hubmapconsortium","download_url":"https://codeload.github.com/hubmapconsortium/spatial-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hubmapconsortium%2Fspatial-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33560727,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"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":[],"created_at":"2025-12-24T22:53:12.498Z","updated_at":"2026-05-27T10:02:17.350Z","avatar_url":"https://github.com/hubmapconsortium.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HuBMAP Spatial API\n\nThis information will help you get the Spatian API up in running whether locally or on an environment.\nIt is available at\n[DEV](https://spatial-api.dev.hubmapconsortium.org/status), and\n[PROD](https://spatial.api.hubmapconsortium.org/status).\n\n## Configuration File\n\nThe configuration file should be located in `./server/resources/app.properties` for deployment.\nThere is a `./server/resources/app.example.properties` that you can use as a template for `./server/resources/app.properties`.\nThe `./server/resources/application.example.properties` assumes that the database is running in\na docker container with a network common to the Spatial API container.\nThis will likely be the case when running locally (see `scripts/run_local.sh`).\n\nThe `./server/resources/app.local.properties` is used by scripts that wish to access the database\nrunning in the local Docker containers.\nThe notable difference is that when accessing the PostgreSQL server form the container\n(as the microservice would do) the database Services name `db` (from `docker-compose.yml`) should be used.\nWhen accessing the database from a script running on the localhost (anything in `scripts`), `localhost` should be used.\n\nSince this microservice accesses a Neo4j, and a PosgreSQL database you will need to provide the server,\nuser, and password for these.\n\nThe `./server/resources/app.properties` should never be saved to GitHUB as it contains passwords.\nYou should create it on the deployment machine, or locally for testing.\n\n\n## Build, Publish, Deploy Workflow\nThese are the steps used to build, publish, and deploy a Docker image.\n\nBefore doing so you will need to follow the steps outlined in the section `Configuration File`\nto configure the server.\n\nLocal deployment instructions for testing purposes are found in the Section `Local Deployment`.\n\n### Get the Latest Code\nLogin to the deployment server (in this case DEV) and get the latest version of the code from the GitHub repository.\n```bash\n# Access the server, switch accounts and go to the server directory\n$ ssh -i ~/.ssh/id_rsa_e2c.pem cpk36@ingest.dev.hubmapconsortium.org\n$ sudo /bin/su - hive\n$ cd /opt/hubmap/spatial-api\n$ git checkout main\n$ git status\n# On branch main\n...\n$ git pull\n```\nFor production the deployment machine is `ingest.hubmapconsortium.org`.\n```bash\n$ ssh -i ~/.ssh/id_rsa_e2c.pem cpk36@ingest.hubmapconsortium.org\n...\n```\nYou should now have the most recent version of the code which should be in the `main` branch.\nYou can also deploy other branches on DEV for testing.\n\n### Build Docker Image\nIn building the latest image specify the latest tag:\n````bash\n$ ./generate-build-version.sh\n$ docker build -t hubmap/spatial-api:latest .\n````\n\nIn building a release version of the image, use the `main` branch, and specify a version tag (without prefix `v`).\nYou can see the previous version tags at [DockerHub Spatial APi](https://github.com/hubmapconsortium/spatial-api/releases/).\n````bash\n$ ./generate-build-version.sh\n$ docker build -t hubmap/spatial-api:1.0.0 .\n````\n\n### Publish the Image to DockerHub\nSaving the image requires access to the DockerHub account with 'PERMISSION' 'Owner' account.\nYou may also see [DockerHub Spatial APi](https://github.com/hubmapconsortium/spatial-api/releases/).\nTo make changes you must login.\n````bash\n$ docker login\n````\n\nFor DEV/TEST/STAGE, just use the `latest` tag.\n````bash\n$ docker push hubmap/spatial-api:latest\n````\n\nFor PROD, push the released version/tag that you have built above.\n````bash\n$ docker push hubmap/spatial-api:1.0.0\n````\n\n### PROD Documenting the Docker image\n\nReelase workflow:\n- merge code to the release branch (typically 'main') in github\n- bump the version number in ./VERSION\n- create a new github release and tag\n- publish a new image with new tag to DockerHub\n- SSH into the PROD VM and pull the new image to redeploy\n\n#### Bump the number in ./VERSION\n\nThe version found in the Released Version that you will create below must\nmatch that of the ./VERSION file.\nChange this file before building the Docker image that you will push to Docker HUB.\nThe version will show up on [VERSION](https://github.com/hubmapconsortium/spatial-api/blob/main/VERSION).\n\n\n#### Create a new Github Release Tag\n\nFor PROD, after you've created the numbered release you should save it in\nthe project [Release](https://github.com/hubmapconsortium/spatial-api/releases/) page.\nOn this page, click on the `Draft a new release` (white on black) button, or if there are no releases\nclick on the `Create a new release` (white on green) button.\nClick on the `Choose a tag` button, enter the tag name, and then `+ Create new tag: v.?.?.? on publish` (with prefix `v`).\nThe new tag will appear in place of the text on the `Choose a tag` button.\nCreate a new release version in the `Release title` box.\nUse the same release number as was used in DockerHub, but prefix it with the letter v (see `Tag suggestion` on the left),\nand enter release notes in the `Write` section.\nThen click on the `Publish release` (white on green) button.\n\n### Deploy the Saved Image\nFor PROD, download the new numbered release image from DockerHub to the deployment server in the Git repository\ndirectory. If you build the image on the deployment server you can skip this step as it should already be on the server.\nYou can use `docker images` to confirm this.\n````bash\n$ docker pull hubmap/spatial-api:1.0.0\n````\n\nFor DEV, you can use `latest` take rather than the `1.0.0` tag above, or what ever the current tag is in the file ./VERSION.\n\nDetermine the current image version. This will show you which Docker image the process is running under.\nIf the process has stopped for some reason you should try `docker images`.\n````bash\n$ docker ps\nCONTAINER ID        IMAGE                       COMMAND                  CREATED             STATUS                  PORTS                          NAMES\n407cbcc4d15d        hubmap/spatial-api:1.0.0    \"/usr/local/bin/entr…\"   3 weeks ago         Up 3 weeks (healthy)    0.0.0.0:5000-\u003e5000/tcp         spatial-api\n...\n````\nStop the process associated with container (Docker image), delete it. Then build and deploy it.\n````bash\n$ ssh -i ~/.ssh/id_rsa_e2c.pem cpk36@18.205.215.12\n$ sudo /bin/su - hive\n$ cd /opt/hubmap/spatial-api\n$ git checkout main\n$ git pull\n$ export SPATIAL_API_VERSION=1.0.0; docker-compose -f docker-compose.api.deployment.yml down --rmi all\n$ export SPATIAL_API_VERSION=1.0.0; docker-compose -f docker-compose.api.deployment.yml up -d --no-build\n$ docker ps\nCONTAINER ID   IMAGE                     COMMAND                  CREATED          STATUS           PORTS                                        NAMES\naa0b6676c615   spatial-api_spatial_db    \"docker-entrypoint.s…\"   28 seconds ago   Up 28 seconds    0.0.0.0:5432-\u003e5432/tcp, :::5432-\u003e5432/tcp    spatial_db\n````\n\nThe production version of the server should be running at...\n````bash\nhttps://spatial.api.hubmapconsortium.org/\n````\n\n### Examine Server Logs\nTo look at the logs of the running server, you may use.\n```bash\n$ tail -f server/log/uwsgi-spatial-api.log\n```\n\n## Local Deployment\n\nBefore deploying the server you will need to configure it.\nPlease follow the steps outlined in the section `Configuration File`.\nFor the spatial-api to access the PostgreSQL server in the container you will\nwant to use...\n```bash\n[postgresql]\n  Server = db:5432\n  Db = spatial\n  Username = spatial\n```\n\nThen you can restore the Docker Containers, Networks, and Volumes by executing the following script.\nIf you delete one of the Docker images (say the `spatial-api_web-1` container) this will rebuild and restart it.\nWith the indicated optional parameters `-dlt` it will also delete and rebuild the containers, reload the data, and run the tests.\n```bash\n$ ./scripts/run_local.sh -dlt\n```\n\nYou will not need to create the tables on the PostgreSQL database that is running in the container\nas this is done when the database starts up as it by default reads the file `db/initdb.d/initdb.sql`.\n\n\n# Adding New Endpoints\n\nAn endpoint should be created in a Python module using Blueprint with its name (e.g., `server/spatialapi/routes/new_endpoint/__init__.py`).\nIt should then be registered in the `server/__init__.py` file.\n\n## OpenAPI Spec\n\nThe endpoints should be documented using [OpenAPI v3](https://swagger.io/specification/).\nThe specification .yml file should be found at the top lever of the project, and named `spatial-api-spec.yml`\n\n### SmartAPI\n\nAll of the HubMAP APIs are found [here](https://smart-api.info/registry?q=hubmap).\n\nThe Spatial API is found [here](https://smart-api.info/ui/f81c4c1977642e0a9c8adbf0486cad40),\nand is reloaded from the file `spatial-api-spec.yaml` in the `main` branch sometime after midnight Eastern Time US.\nIt contains only the search related endpoints.\n\nThe other administrative endpoints are found in `spatial-api-spec-private.yaml`.\n\n### Registering Endpoints\nAll endpoints should be registered in the `AWS API Gateway`.\nCurrently this is a manual process.\n\nThe urls are as follows:\n[DEV](https://spatial-api.dev.hubmapconsortium.org/),\n[TEST](https://spatial-api.test.hubmapconsortium.org/),\n[STAGE](https://spatial-api.stage.hubmapconsortium.org/),\n[PROD](https://spatial.api.hubmapconsortium.org/).\n\n## Method Verification Data\n\nIt was important to verify that the manner in which we are loading spatial data into the `sample` table produces\nthe results that we were expecting.\nIn order to do this \"well behaved\" data was constructed in the `geom_test` table.\nSeveral 10x10x10 cubes were created and spaced at different intervals by a `Translate` operation.\nThe `db/run_test.sql` file contains a comment which represents the distance between the origin `POINTZ(0 0 0)`\nand a radius (computed using the Pythagorean theorem). A pair of queries are used for each cube.\nThe first query uses a radius which is just a tiny bit shy of the radius that the cube should be found.\nThe second query uses a radius which is just at the radius where the Pythagorean theorem says that the cube should be found.\n\nHere are the first two queries of the test script which illustrates this.\n```bash\n$ ./scripts/run_test.sh\nRunning test queries...\nPassword for user spatial: \n-- sqrt(10^2 + 10^2 + 10^2) = 17.321\nSELECT id FROM geom_test\n   WHERE ST_3DDWithin(geom, ST_GeomFromText('POINTZ(0 0 0)'), 17.32);\n id \n----\n(0 rows)\n\nSELECT id FROM geom_test\n   WHERE ST_3DDWithin(geom, ST_GeomFromText('POINTZ(0 0 0)'), 17.321);\n id \n----\n  1\n(1 row)\n```\nThe first query shows that closest cube to the origin (created in `db/initdb.d/initdb.sql`) is not found\nat radius `17.320`, but is found at radius `17.321` which is where the Pythagorean theorem (in comment)\n```bash\n-- sqrt(10^2 + 10^2 + 10^2) = 17.321\n```\nsays that it should be found.\n\nThis cube corresponds to the first cube created in the `db/initdb.d/iniddb.sql` file.\n```bash\nINSERT INTO geom_test (geom)\n  VALUES (ST_Translate(ST_MakeSolid('POLYHEDRALSURFACE Z(\n        ((-5.0 -5.0 5.0, 5.0 -5.0 5.0, 5.0 5.0 5.0, -5.0 5.0 5.0, -5.0 -5.0 5.0)),\n        ((-5.0 -5.0 -5.0, -5.0 5.0 -5.0, 5.0 5.0 -5.0, 5.0 -5.0 -5.0, -5.0 -5.0 -5.0)),\n        ((-5.0 -5.0 -5.0, -5.0 -5.0 5.0, -5.0 5.0 5.0, -5.0 5.0 -5.0, -5.0 -5.0 -5.0)),\n        ((5.0 -5.0 -5.0, 5.0 5.0 -5.0, 5.0 5.0 5.0, 5.0 -5.0 5.0, 5.0 -5.0 -5.0)),\n        ((-5.0 5.0 -5.0, -5.0 5.0 5.0, 5.0 5.0 5.0, 5.0 5.0 -5.0, -5.0 5.0 -5.0)),\n        ((-5.0 -5.0 -5.0, 5.0 -5.0 -5.0, 5.0 -5.0 5.0, -5.0 -5.0 5.0, -5.0 -5.0 -5.0)) )'),\n         15, 15, 15));\n```\n\nThis cube is constructed as a Polyhedral Surface which is a 3D figure made exclusively of six (6) Polygons.\nIt is a contiguous collection of polygons, which share common boundary segments.\nIn our case the surfaces of the polygons are all `outside` surfaces.\nAn `outside` surface is a polygon that has a `winding order` of counterclockwise,\nthat is the points are specified in a counter clockwise manner.\nAn `inside` suface is a polygon that has a `winding order` of clockwise.\n\nYou can run tests on the geometric objects that are in the database by running\n`geom.py` with an option of `-c`. It checks to make sure that all of the geometries\nare `closed`, `solids`, and have the `correct volume`.\n````bash\n$ (cd server; export PYTHONPATH=.; python3 ./tests/geom.py -c -C $CONFIG)\n````\n\nIf you wish to see what a 3D Polyhedral Surface of a given length, width,\nand height looks like you can use `spatial_manager.py` with the `-p` option.\nHere a Polyhedral Surface is created with a length of 23, a width of 14, and a height of 9.\n````bash\n(cd server; export PYTHONPATH=.; python3 ./spatialapi/manager/spatial_manager.py -p '23 14 9')\n[2022-06-30 16:57:04] INFO in spatial_manager:334: Dimensions given are x: 23.0, y: 14.0, z: 9.0\n'POLYHEDRALSURFACE Z(((-11.5 -7.0 4.5, 11.5 -7.0 4.5, 11.5 7.0 4.5, -11.5 7.0 4.5, -11.5 -7.0 4.5)),((-11.5 -7.0 -4.5, -11.5 7.0 -4.5, 11.5 7.0 -4.5, 11.5 -7.0 -4.5, -11.5 -7.0 -4.5)),((-11.5 -7.0 -4.5, -11.5 -7.0 4.5, -11.5 7.0 4.5, -11.5 7.0 -4.5, -11.5 -7.0 -4.5)),((11.5 -7.0 -4.5, 11.5 7.0 -4.5, 11.5 7.0 4.5, 11.5 -7.0 4.5, 11.5 -7.0 -4.5)),((-11.5 7.0 -4.5, -11.5 7.0 4.5, 11.5 7.0 4.5, 11.5 7.0 -4.5, -11.5 7.0 -4.5)),((-11.5 -7.0 -4.5, 11.5 -7.0 -4.5, 11.5 -7.0 4.5, -11.5 -7.0 4.5, -11.5 -7.0 -4.5)) )'\n````\nIt will create a Polyhedral Surface with it's center at the origin.\nYou can then use `translation` and `rotation` to further place it in the space.\n\n## Deploy Database\n\nThe following will allow you to connect to the database host, destroy the database and rebuild the table structure and stored procedures...\n````bash\n$ ssh -i ~/.ssh/id_rsa_e2c.pem cpk36@18.205.215.12\n$ sudo /bin/su - hive\n$ cd /opt/hubmap/spatial-api\n$ git checkout main\n$ git pull\n$ docker-compose -f docker-compose.db.deployment.yml down --rmi all\n$ docker-compose -f docker-compose.db.deployment.yml up --build -d\n$ docker ps\nCONTAINER ID   IMAGE                     COMMAND                  CREATED          STATUS           PORTS                                        NAMES\naa0b6676c615   spatial-api_spatial_db    \"docker-entrypoint.s…\"   28 seconds ago   Up 28 seconds    0.0.0.0:5432-\u003e5432/tcp, :::5432-\u003e5432/tcp    spatial_db\n````\n\nThe following script will allow you to load data into the database.\nIt will access the spatial-api server and execute several endpoints\nthat will allow for the rebuilding of the: annotation details,\norgan-sample-data (RK \u0026 LK), and the cell type counts.\n\nTo get the BEARER_TOKEN using Firefox open a \"New Private Window\".\nThen access the Developer Tool (Tools \u003e Browser Tools \u003e Web Developer Tools).\nLogin through the [UI](https://portal.hubmapconsortium.org/).\nExamine the Request Header \u003e Authorization, of the search-api calls.\nThe very long string following the text BEARER \u003csp\u003e is what you want.\nAfter you copy that string close the web browser.\n````bash\n$ ./scripts/db_rebuild.sh -H https://spatial-api.dev.hubmapconsortium.org -t BEARER_TOKEN\n````\n\n## Deploy Server\n\nConnect to the server host, destroy the old image, build and redeploy.\n````bash\n$ ssh -i ~/.ssh/id_rsa_e2c.pem cpk36@ingest.dev.hubmapconsortium.org\n$ sudo /bin/su - hive\n$ cd /opt/hubmap/spatial-api\n$ git checkout main\n$ git pull\n$ export SPATIAL_API_VERSION=latest; docker-compose -f docker-compose.api.deployment.yml down --rmi all\n$ docker build -t hubmap/spatial-api:latest .\n$ docker push hubmap/spatial-api:latest\n$ export SPATIAL_API_VERSION=latest; docker-compose -f docker-compose.api.deployment.yml up --no-build -d\n$ docker ps\nCONTAINER ID   IMAGE                     COMMAND                  CREATED         STATUS                           PORTS     NAMES\nb747d2cfd62f   hubmap/spatial-api:latest \"/usr/local/bin/entr…\"   4 seconds ago   Up 3 seconds (health: starting)  5000/tcp\n````\n\nIf deploying other than the `latest` version for test you should give the appropriate version number.\n\n### Server Tests\n\nThere are several scripts that allow you to run tests against the server.\n\nThe following will run tests against the dev server:\n````bash\n$ ./scripts/search_hubmap_id.sh -H https://spatial-api.dev.hubmapconsortium.org\n$ ./scripts/spatial_search_hubmap_id.sh -H https://spatial-api.dev.hubmapconsortium.org\n$ ./scripts/point_search.sh -H https://spatial-api.dev.hubmapconsortium.org\n````\nBy default the tests run agains `http://localhost:5001`\n````bash\n$ ./scripts/search_hubmap_id.sh\n$ ./scripts/spatial_search_hubmap_id.sh \n$ ./scripts/point_search.sh\n````\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhubmapconsortium%2Fspatial-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhubmapconsortium%2Fspatial-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhubmapconsortium%2Fspatial-api/lists"}