{"id":13529822,"url":"https://github.com/neo4j-contrib/spatial","last_synced_at":"2025-05-14T21:08:43.601Z","repository":{"id":44586563,"uuid":"511373","full_name":"neo4j-contrib/spatial","owner":"neo4j-contrib","description":"Neo4j Spatial is a library of utilities for Neo4j that faciliates the enabling of spatial operations on data. In particular you can add spatial indexes to already located data, and perform spatial operations on the data like searching for data within specified regions or within a specified distance of a point of interest.","archived":false,"fork":false,"pushed_at":"2025-04-01T16:19:55.000Z","size":8906,"stargazers_count":787,"open_issues_count":85,"forks_count":193,"subscribers_count":77,"default_branch":"master","last_synced_at":"2025-04-06T14:06:35.996Z","etag":null,"topics":["geoserver","geotools","gis","hacktoberfest","neo4j","neo4j-database","neo4j-procedures","neo4j-spatial-plugin","postgis","procedures","spatial-data"],"latest_commit_sha":null,"homepage":"https://neo4j.com/labs/spatial/","language":"Scheme","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neo4j-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2010-02-10T15:23:02.000Z","updated_at":"2025-04-01T09:37:52.000Z","dependencies_parsed_at":"2022-08-20T04:10:07.352Z","dependency_job_id":"a6c1278a-0f3d-4006-9e63-03aa8f5be45c","html_url":"https://github.com/neo4j-contrib/spatial","commit_stats":{"total_commits":1037,"total_committers":49,"mean_commits":"21.163265306122447","dds":0.6692381870781099,"last_synced_commit":"3a4486e4a830d84ef85321585633a8ac238da394"},"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j-contrib%2Fspatial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j-contrib%2Fspatial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j-contrib%2Fspatial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j-contrib%2Fspatial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neo4j-contrib","download_url":"https://codeload.github.com/neo4j-contrib/spatial/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248750008,"owners_count":21155682,"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":["geoserver","geotools","gis","hacktoberfest","neo4j","neo4j-database","neo4j-procedures","neo4j-spatial-plugin","postgis","procedures","spatial-data"],"created_at":"2024-08-01T07:00:39.708Z","updated_at":"2025-04-13T16:54:02.434Z","avatar_url":"https://github.com/neo4j-contrib.png","language":"Scheme","funding_links":[],"categories":["Scheme","Extensions","Database","gis","REST API"],"sub_categories":["REST API","Other"],"readme":"# Neo4j Spatial\n\n[![build](https://github.com/neo4j-contrib/spatial/actions/workflows/pr-build.yaml/badge.svg?branch=master)](https://github.com/neo4j-contrib/spatial/actions/workflows/pr-build.yaml)\n\nNeo4j Spatial is a library facilitating the import, storage and querying of spatial data in\nthe [Neo4j open source graph database](http://neo4j.org/).\n\nThis project's manual is deployed to the [Neo4j Labs page](https://neo4j.com/labs/neo4j-spatial/5/).\n## Versioning\n\nSince version 5.19.0, the versioning of Neo4j Spatial is aligned with the versioning of Neo4j itself.\nThis means that Neo4j Spatial 5.19.0 is build against Neo4j 5.19, and so on.\n\n## Installation\n\n1. Copy the desired neo4j-spatial-x.x.x-server-plugin.jar from the [release page](https://github.com/neo4j-contrib/spatial/releases) to your neo4j plugin directory.\n2. set up your database with the following configuration in your `neo4j.conf` file:\n\n    ```\n    dbms.security.procedures.unrestricted=spatial.*\n    ```\n\n   NOTE: If you're concerned about the security risks of unrestricted access, we recommend reviewing the code to assess\n   the level of risk for your use case. For example, the method \n   [`IndexAccessMode.withIndexCreate`](/src/main/java/org/neo4j/gis/spatial/index/IndexManager.java#L42) grants index\n   creation capabilities within the security model. This allows users without index creation privileges to generate the\n   required spatial support indexes. This behavior was not intentionally designed to bypass security but was necessary\n   due to Neo4j’s security model, where procedures with WRITE mode are not permitted to create indexes.\n   As a result, this adjustment was required even in the Community Edition of Neo4j.\n\n3. Restart your Neo4j server.\n4. Run `CALL spatial.procedures` in the Neo4j browser to see the available spatial procedures.\n\n## Concept Overview\n\nThe key concepts of this library include:\n\n* Allow the user to model geograph data in whatever way they wish, through providing an adapter (\n  extend `GeometryEncoder`).\n  Built-in encoders include:\n\t* WKT and WKB stored as properties of nodes\n\t* Simple points as properties of nodes (two doubles, or a double[] or a native Neo4j `Point`)\n\t* OpenStreetMap with complex geometries stored as sub-graphs to reflect the original topology of the OSM model\n* Multiple CoordinationReferenceSystem support using GeoTools\n* Support the concept of multiple geographic layers, each with its own CRS and Index\n* Include an index capable of searching for complex geometries (in-graph RTree index)\n* Support import and export in a number of known formats (e.g. Shapefile and OSM)\n* Embed the library and Neo4j within GIS tools like uDig and GeoServer\n\nSome key features include:\n\n* Utilities for importing from ESRI Shapefile as well as Open Street Map files\n* Support for all the common geometry types\n* An RTree index for fast searches on geometries\n* Support for topology operations during the search (contains, within, intersects, covers, disjoint, etc.)\n* The possibility to enable spatial operations on any graph of data, regardless of the way the spatial data is stored,\n  as long as an adapter is provided to map from the graph to the geometries.\n* Ability to split a single layer or dataset into multiple sub-layers or views with pre-configured filters\n* Server Plugin for Neo4j Server 2.x and 3.x\n\t* REST API for creating layers and adding nodes or geometries to layers\n\t* IndexProvider API (2.x only) for Cypher access using `START node=node:geom({query})`\n\t* Procedures (3.x only) for much more comprehensive access to spatial from Cypher\n\n## Index and Querying ##\n\nThe current index is an RTree index, but it has been developed in an extensible way allowing for other indices to be\nadded if necessary.\nThe spatial queries implemented are:\n\n* Contain\n* Cover\n* Covered By\n* Cross\n* Disjoint\n* Intersect\n* Intersect Window\n* Overlap\n* Touch\n* Within\n* Within Distance\n\n## Building ##\n\nThe simplest way to build Neo4j Spatial is by using maven. Just clone the git repository and run\n\n~~~bash\nmvn install\n~~~\n\nThis will download all dependencies, compiled the library, run the tests and install the artifact in your local\nrepository.\nThe spatial plugin will also be created in the `target` directory, and can be copied to your local server using\ninstructions from the [installation section](#installation).\n\n## Layers and GeometryEncoders ##\n\nThe primary type that defines a collection of geometries is the Layer. A layer contains an index for querying. In\naddition, a Layer can be an EditableLayer if it is possible to add and modify geometries in the layer. The next most\nimportant interface is the GeometryEncoder.\n\nThe DefaultLayer is the standard layer, making use of the WKBGeometryEncoder for storing all geometry types as byte[]\nproperties of one node per geometry instance.\n\nThe OSMLayer is a special layer supporting Open Street Map and storing the OSM model as a single fully connected graph.\nThe set of Geometries provided by this layer includes Points, LineStrings and Polygons, and as such cannot be exported\nto Shapefile format, since that format only allows a single Geometry per layer. However, OMSLayer extends DynamicLayer,\nwhich allow it to provide any number of sub-layers, each with a specific geometry type and in addition based on an OSM\ntag filter. For example, you can have a layer providing all cycle paths as LineStrings, or a layer providing all lakes\nas\nPolygons. Underneath these are all still backed by the same fully connected graph, but exposed dynamically as apparently\nseparate geometry layers.\n\n## Examples ##\n\n### Importing a shapefile ###\n\nSpatial data is divided in Layers and indexed by a RTree.\n\n~~~java\nGraphDatabaseService database = new GraphDatabaseFactory().newEmbeddedDatabase(storeDir);\ntry{\n\tShapefileImporter importer = new ShapefileImporter(database);\n\timporter.importFile(\"roads.shp\",\"layer_roads\");\n} finally {\n\tdatabase.shutdown();\n}\n~~~\n\nIf using the server, the same can be achieved with spatial procedures (3.x only):\n\n~~~cypher\nCALL spatial.addWKTLayer('layer_roads', 'geometry')\nCALL spatial.importShapefileToLayer('layer_roads', 'roads.shp')\n~~~\n\n### Importing an Open Street Map file ###\n\nThis is more complex because the current OSMImporter class runs in two phases, the first requiring a batch-inserter on\nthe database. There is ongoing work to allow for a non-batch-inserter on the entire process, and possibly when you have\nread this that will already be available. Refer to the unit tests in classes TestDynamicLayers and TestOSMImport for the\nlatest code for importing OSM data. At the time of writing the following worked:\n\n~~~java\nOSMImporter importer = new OSMImporter(\"sweden\");\nMap\u003cString, String\u003e config = new HashMap\u003cString, String\u003e();\nconfig.put(\"neostore.nodestore.db.mapped_memory\", \"90M\" );\nconfig.put(\"dump_configuration\", \"true\");\nconfig.put(\"use_memory_mapped_buffers\", \"true\");\nBatchInserter batchInserter = BatchInserters.inserter(new File(dir), config);\nimporter.importFile(batchInserter, \"sweden.osm\", false);\nbatchInserter.shutdown();\n\nGraphDatabaseService db = new GraphDatabaseFactory().newEmbeddedDatabase(dir);\nimporter.reIndex(db, 10000);\ndb.shutdown();\n~~~\n\n### Executing a spatial query ###\n\n~~~java\nGraphDatabaseService database = new GraphDatabaseFactory().newEmbeddedDatabase(storeDir);\ntry {\n\tSpatialDatabaseService spatialService = new SpatialDatabaseService(database);\n\tLayer layer = spatialService.getLayer(\"layer_roads\");\n\tSpatialIndexReader spatialIndex = layer.getIndex();\n\t\t\n\tSearch searchQuery = new SearchIntersectWindow(new Envelope(xmin, xmax, ymin, ymax));\n\tspatialIndex.executeSearch(searchQuery);\n\tList\u003cSpatialDatabaseRecord\u003e results = searchQuery.getResults();\n} finally {\n\tdatabase.shutdown();\n}\n~~~\n\nIf using the server, the same can be achieved with spatial procedures (3.x only):\n\n~~~cypher\nCALL spatial.bbox('layer_roads', {lon: 15.0, lat: 60.0}, {lon: 15.3, lat: 61.0})\n~~~\n\nOr using a polygon:\n\n~~~cypher\n\nWITH 'POLYGON((15.3 60.2, 15.3 60.4, 15.7 60.4, 15.7 60.2, 15.3 60.2))' AS polygon\nCALL spatial.intersects('layer_roads', polygon) YIELD node\nRETURN node.name AS name\n~~~\n\nFor further Java examples, refer to the test code in the\n[LayersTest](src/test/java/org/neo4j/gis/spatial/LayersTest.java) and\nthe [TestSpatial](src/test/java/org/neo4j/gis/spatial/TestSpatial.java) classes.\n\nFor further Procedures examples, refer to the code in\nthe [SpatialProceduresTest](src/test/java/org/neo4j/gis/spatial/procedures/SpatialProceduresTest.java)\nclass.\n\n## Neo4j Spatial Geoserver Plugin ##\n\n*IMPORTANT*: Examples in this readme were originally tested with GeoServer 2.1.1.\nHowever, regular testing of new releases of Neo4j Spatial against GeoServer is not done,\nand so we welcome feedback on which versions are known to work, and which ones do not,\nand perhaps some hints as to the errors or problems encountered.\n\nEach release of Neo4j Spatial builds against a specific version of GeoTools and should then be used in the version of\nGeoServer that corresponds to that.\nThe list of releases below starting at Neo4j 2.0.8 were built with GeoTools 9.0 for GeoServer 2.3.2,\nbut most release for Neo4j 3.x were ported to GeoTools 14.4 for GeoServer 2.8.4.\n\nFor the port to Neo4j 4.0 we needed to upgrade GeoTools to 24.x to avoid bugs with older GeoTools in Java 11.\nThis also required a complete re-write of the Neo4jDataStore and related classes.\nThis has not been tested at all in any GeoTools enabled application, but could perhaps work with GeoServer 2.18.\n\n### Building ###\n\n~~~bash\nmvn clean install\n~~~\n\n### Deployment into Geoserver ###\n\n* unzip the `target/xxxx-server-plugin.zip` and the Neo4j libraries from your Neo4j download under `$NEO4J_HOME/lib`\n  into `$GEOSERVER_HOME/webapps/geoserver/WEB-INF/lib`\n* restart geoserver\n* configure a new workspace\n* configure a new datasource neo4j in your workspace. Point the \"The directory path of the Neo4j database:\" parameter to\n  the relative (form the GeoServer working dir) or absolute path to a Neo4j Spatial database with layers (\n  see [Neo4j Spatial](https://github.com/neo4j/spatial))\n* in Layers, do \"Add new resource\" and choose your Neo4j datastore to see the existing Neo4j Spatial layers and add\n  them.\n\n### Testing in GeoServer trunk ###\n\n* check out the geoserver source\n\n~~~bash\nsvn co https://svn.codehaus.org/geoserver/trunk geoserver-trunk\n~~~\n\n* build the source\n\n~~~bash\ncd geoserver-trunk\nmvn clean install\n~~~\n\n* check that you can run the web app as\n  of [The GeoServer Maven build guide](http://docs.geoserver.org/latest/en/developer/maven-guide/index.html#running-the-web-module-with-jetty)\n\n~~~bash\ncd src/web/app\nmvn jetty:run\n~~~\n\n* in `$GEOSERVER_SOURCE/src/web/app/pom.xml` https://svn.codehaus.org/geoserver/trunk/src/web/app/pom.xml, add the\n  following lines under the profiles section:\n\n~~~xml\n\u003cprofile\u003e\n\t\u003cid\u003eneo4j\u003c/id\u003e\n\t\u003cdependencies\u003e\n\t\t\u003cdependency\u003e\n\t\t\t\u003cgroupId\u003eorg.neo4j\u003c/groupId\u003e\n\t\t\t\u003cartifactId\u003eneo4j-spatial\u003c/artifactId\u003e\n\t\t\t\u003cversion\u003e5.26.0\u003c/version\u003e\n\t\t\u003c/dependency\u003e\n\t\u003c/dependencies\u003e\n\u003c/profile\u003e\n~~~\n\nThe version specified on the version line can be changed to match the version you wish to work with (based on the\nversion of Neo4j itself you are using). To see which versions are available see the list\nat [Neo4j Spatial Releases](https://github.com/neo4j-contrib/m2/tree/master/releases/org/neo4j/neo4j-spatial).\n\n* start the GeoServer webapp again with the added neo4j profile\n\n~~~bash\n    cd $GEOSERVER_SRC/src/web/app\n    mvn jetty:run -Pneo4j\n~~~\n\n* find Neo4j installed as a datasource under http://localhost:8080\n\n## Using Neo4j Spatial with uDig ##\n\nFor more info head over to [Neo4j Wiki on uDig](http://wiki.neo4j.org/content/Neo4j_Spatial_in_uDig) (This wiki is\ncurrently dead, but there appears to be a working mirror in Japan\nat http://oss.infoscience.co.jp/neo4j/wiki.neo4j.org/content/Neo4j_Spatial_in_uDig.html).\n\n## Using the Neo4j Spatial Server plugin ##\n\nThe server plugin provides access to the internal spatial capabilities using three APIs:\n\n* Procedures for much more comprehensive access to spatial from Cypher\n\t* Documentation is not yet available, but you can list the available procedures within Neo4j using the\n\t  query `CALL spatial.procedures`\n\t* This API uses the _Procedures_ capabilities released in Neo4j 3.0, and is therefor not available for Neo4j 2.x\n\nDuring the Neo4j 3.x releases, support for spatial procedures changed a little,\nthrough the addition of various new capabilities.\nThey were very quickly much more capable than the older REST API,\nmaking them by far the best option for accessing Neo4j remotely or through Cypher.\n\nThe Java API (the original API for Neo4j Spatial) still remains, however, the most feature rich,\nand therefor we recommend that if you need to access Neo4j server remotely, and want deeper access to Spatial functions,\nconsider writing your own Procedures. The Neo4j 3.0 documentation provides some good information on how to do this,\nand you can also refer to\nthe [Neo4j Spatial procedures source code](src/main/java/org/neo4j/gis/spatial/procedures/SpatialProcedures.java)\nfor examples.\n\n## Building Neo4j spatial ##\n\n~~~bash  \ngit clone https://github.com/neo4j-contrib/spatial/spatial.git\ncd spatial\nmvn clean package\n~~~\n\n## Running Neo4j spatial code from the command-line ##\n\nSome of the classes in Neo4j-Spatial include main() methods and can be run on the command-line.\nFor example there are command-line options for importing SHP and OSM data. See the main methods\nin the OSMImporter and ShapefileImporter classes. Here we will describe how to set up the dependencies\nfor running the command-line, using the OSMImporter and the sample OSM file two-street.osm.\nWe will show two ways to run this on the command line, one with the java command itself, and the\nother using the 'exec:java' target in maven. In both cases we use maven to set up the dependencies.\n\n### Compile ###\n\n~~~bash\ngit clone git://github.com/neo4j-contrib/spatial.git\ncd spatial\nmvn clean compile\n~~~\n\n### Run using JAVA command ###\n\n~~~bash\nmvn dependency:copy-dependencies\njava -cp target/classes:target/dependency/* org.neo4j.gis.spatial.osm.OSMImporter osm-db two-street.osm \n~~~\n\n_Note: On windows remember to separate the classpath with ';' instead of ':'._\n\nThe first command above only needs to be run once, to get a copy of all required JAR files into the directory\ntarget/dependency.\nOnce this is done, all further java commands with the -cp specifying that directory will load all dependencies.\nIt is likely that the specific command being run does not require all dependencies copied, since it will only be using\nparts of the Neo4j-Spatial library, but working out exactly which dependencies are required can take a little time, so\nthe above approach is most certainly the easiest way to do this.\n\n### Run using 'mvn exec:java' ###\n\n~~~bash\nmvn exec:java -Dexec.mainClass=org.neo4j.gis.spatial.osm.OSMImporter -Dexec.args=\"osm-db two-street.osm\"\n~~~\n\nNote that the OSMImporter cannot re-import the same data multiple times,\nso you need to delete the database between runs if you are planning to do that.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneo4j-contrib%2Fspatial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneo4j-contrib%2Fspatial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneo4j-contrib%2Fspatial/lists"}