on Code

PostGIS REST Web Services

Editor’s Note: I moved this project to the Projects page at the top.

Last month I talked about Geospatial Portal, a site I recently rolled out, that is entirely, 100%, based on REST web services - OGC WMS services for the mapping, and some custom REST services I built for data and analysis. The geospatial processing is done with PostgreSQL/PostGIS.

I built the REST web service framework (I use that term loosely) with PHP, and it was one of those not-very-difficult-but-takes-a-lot-of-time-and-planning sorts of things. As such, I thought it might be helpful to release the source code for the framework, including REST services to:

  • Perform attribute queries
  • Buffer points
  • Buffer features
  • Perform point overlays
  • Perform feature overlays
  • List layers
  • List fields
  • Get feature extents
  • Project coordinates
That doesn't sound like a terribly long list. But with those 9 services, you will be astonished with how much of your needs will be met. And not just your needs as a GIS superhero - we have a lot of traffic to our services from traditional IT applications. Want to hold up a permit if the location is in a historic area, floodplain, or within 100 feet of a proposed thoroughfare? Assign a warrant to a particular Sheriff paper delivery area? Find out what County Commissioner district a location is in? Most any basic geoprocessing you can think of will be covered with these services, and once you see how easy it is to make these services, you can easily add your own for whatever else you need, spatial or otherwise. And since we're talking PostgreSQL/PostGIS and PHP, the whole stack costs you zilch.

Without further ado, here’s the download link:

REST Web Services

Unzip the folder to your web server and open your browser to that URL (default.php), and you’ll get the main documentation page. Your web server can be IIS or Apache running PHP with the php_pgsql.dll extension enabled.

The folder layout for the web services is like so:

REST folders

Note the main “rest” folder is the “webservices” folder in the zip file - I’m stealing this image from our wiki :).

The documentation is in the docs folder, with a ws_template.htm template help document should you want to add your own services. It’s a pretty straight-forward format, with all of the styling done elsewhere. Just put a pointer to any new documentation in the navigation.htm file and you’re all set. You’ll find documentation is just as important as, and will probably take longer than, creating the actual REST web services.

The inc folder has some includes, with one you will have to change to get anywhere. The database.inc.php file holds database connections and has a connection set for PostgreSQL/PostGIS. You just need to put in your connection information and all of the web services will start working. For security reasons, you will want to use a Postgres login with read-only permission to the database tables. Also in there are includes for rendering XML or JSON (you can output either from the services), a security include, an error handler that can email you error information from the service if you go in and edit it with your SMTP server information, and the phpmailer and adodb libraries.

Now we get to the v1 folder, which holds the actual web services. The ‘1’ designator is important. Once you roll out your services, you can almost never change them without breaking somebody’s stuff. If you have a service you want to change, put the changed service in a v2 folder, change your docs and point it there for the next projects that come along, and leave the v1 version alone. Messing about with established web services will spell doom for your service oriented architecture.

The script, style, and image folders are what they sound like. I’m using a little jQuery to load some of the documentation (party foul for gratuitous use of Javascript), and I’m using Blueprint CSS for basic styling. Nothing important there for web services - that’s all for the documentation.

That’s about it. There is nothing in the services that is database schema specific - you pass it the table names, fields, parameters, etc., that you want, so it should work for any PostGIS environment. There are examples in the documentation for connecting to the services from PHP, .NET, and jQuery, and in my organization there are people using VB 6 to connect to the services via the Internet Transfer Control. You specify the output you want for each request via the format option - XML or JSON - and the output format is consistent across the services.

Naturally, it’s GNU GPL code - do with it what you will. My name is in the headers in the pages just because it’s my standard header, but you’re not obligated to keep it there. If you find anything in the code that can be handled in a better way (a high likelihood - I’m not very smart), however, please let me know so I can improve the code. If there’s a sudden, unexpected rush of interest, I can always create a project site for the code somewhere or another. Also be aware of this type of framework’s limitations - it’s best for read-only database query and geoprocessing, not for database writes. For that, you’ll want to support more methods (UPDATE, DELETE, etc.), and have a much tighter security model. It’s designed to help you get some basic geoprocessing capabilities throughout your enterprise, and using it for much else will likely turn your life into a furious ball of nothing.

Enjoy. Next month I’ll post some source code from the Geospatial Portal site.