Add license file; Partial update to README

project-open-data · db4ed451536ce3dd575043f0817eca93b71427a4 · jmarin committed Oct 25, 2012 · Oct 25, 2012 · db4ed45
1 parent 1ab2017
commit db4ed451536ce3dd575043f0817eca93b71427a4
Unified Split

Showing with 63 additions and 1 deletion.

+19 −0 LICENSE.txt

+44 −1 README.md
diff --git a/LICENSE.txt b/LICENSE.txt
@@ -0,0 +1,19 @@
+Copyright (c) 2012 Juan Marin Otero
+ 
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+ 
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+ 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,2 +1,45 @@
 SpatialSearch
-=============
+=============
+
+SpatialSearch is a RESTful API that allows the user to query geographic entities by latitude and longitude, and extract data. 
+
+Building
+--------
+
+SpatialSearch is built with `Maven <http://maven.apache.org/>`. The build produces a WAR file suitable for deployment on any JEE 5 compliant Web Container (i.e. Jetty, Tomcat, etc.). 
+
+To perform a full build, including integration tests (see dependencies below before doing this):
+
+#. mvn clean install
+
+To run the unit tests (in-memory):
+
+#. mvn test
+
+
+Dependencies
+------------
+
+* `PostGIS <http://postgis.refractions.net/>`, the spatial extension to PostgreSQL, is necessary to run the API in production. The Unit tests included with this project use the H2 `GeoDB <https://github.com/jdeolive/geodb>` in-memory database, allowing for rapid development without the need for a database server. 
+
+* Data. The API exposes the State, County and Census Block geographic layers from the 2010 Census Bureau. These can be obtained from the `TIGER <http://www.census.gov/geo/www/tiger/tgrshp2010/tgrshp2010.html>` download page and need to be imported into PostGIS in order to be able to publish the API. SpatialSearch uses the default schema of the tables, grouped into a census schema within a database called gisdb by default. All these parameters can be changed
+
+* SpatialSearch uses `Hibernate Spatial <http://www.hibernatespatial.org/>` for the geospatial functionality. This library supports the same type of functionality on other Spatial DBMS systems such as Oracle Spatial, Microsoft SQL Server, etc. For more information please visit its website.
+
+Usage
+-----
+
+This first version of the API exposes a "point in polygon" functionality, as follows (example running locally from embedded Jetty Servlet Container)
+
+http://localhost:8081/spatialsearch/census/<geography>?latitude=<latitude>&longitude=<longitude>&format=<format>
+
+where
+
+<geography> is the type of layer being queried. Currently it can take the following values: state2010, county2010, block2010
+
+<longitude> is the Longitude of the position to query on. Expresses in decimal degrees, WGS84 projection is assumed (EPSG code 4326)
+
+<latitude> is the Latitude of the position to query on. Expresses in decimal degrees, WGS84 projection is assumed (EPSG code 4326)
+
+<format> is the output format. Currently it can take the following values: xml, json and jsonp. This parameter is optional, if not specified the response will be enconded as XML
+