Instructions, Tips and Tricks

Here is a hodgepodge of instructions, tips, and tricks for working with GIS REST web services.

Service Output

Service output is standardized for all REST web services. Format for all REST services comes in three flavors set by the format paramater: xml, json, or geojson. XML is a standard data exchange format and is most appropriate for use in server or application side coding, where XML parsers frequently exist. JSON is most appropriate for consumption by Javascript. Each return is essentially a XML or JSON representation of a record set.

XML output looks like this:

	<rows count="2">
	  <row>
	    <column name="column1">column value</column>
	    <column name="column2">column value</column>
	  </row>
	  <row>
	    <column name="column1">column value</column>
	    <column name="column2">column value</column>
	  </row>
	</rows>
	

The XML container tag is "rows". The "rows" tag contains child "row" tags, one for each record returned. Note the "rows" tag has a "total-rows" property, which indicates the number of rows returned by the query. Each "row" tag has any number of child "column" tags. The "column" tag represents a field or column in the return record set, with the "name" property being the name of the field or column. The value of the "column" tag is the value of that column for that record.

JSON output looks like this:

	{rows:[
	  {column1:"column value",column2:"column value"},
	  {column1:"column value",column2:"column value"}
	]}
	

GeoJSON output simply outputs any returned geometry into GeoJSON formats for points, lines, and polygons for consumption by Javascript mapping libraries (OpenLayers, ArcGIS API for Javascript).

Customizing Fields and Parameters

Many of our GEO REST services off you the ability to set custom parameters and fields for your query. We do this because (a) we don't know what you want, and (b) we're not going to write web services to handle every request. By keeping the services generic we maximize code reuse and interoperability.

The parameters argument lets you set additional parameters for the query as you would in a SQL where request. For example, suppose you are doing a point buffer and you want to buffer your point by 500 feet and return the voting precincts in that buffer. But suppose you also want to only return voting precincts in the buffer where the precinct (precno) number is greater than 100. Simply add that as a parameter (URL encoding left off here for readability):

	parameters = acctno > 100
	

If you don't need additional parameters, simply leave the parameters argument empty.

The fields argument allows you to specify what fields you would like returned. You can get a list of fields for a geotable with the Get Fields GEO service.

You can also use the fields parameter to change the field name used in your return. For example (URL encoding left off here for readability):

	fields = precno as precinct_number, cc as county_commissioner_district
	

One of the really cool things you can do with the fields argument is to return geometry. You can return geometry as KML, GML, WKT, or SVG. Here are some exampes:

	KML
	fields = askml(the_geom) as the_geom
	
	GML
	fields = asgml(the_geom) as the_geom
	
	WKT
	fields = asewkt(the_geom) as the_geom
	
	SVG
	assvg(the_geom) as the_geom

There are a number of things to note here. First the_geom is the name of the geometry column in all of our geotables, hence the (the_geom) argument. The second thing to note is the return value is in the projection of the geotable (which you can find out with the Get Layers web service). If you want it in a different projection, you would need to use the transform option, as seen here:

	KML projected to SRID 4326
	fields = askml(transform(the_geom, 4326)) as the_geom

4326 is the SRID we want the data returned in. So, in this example, we want the geometry converted to 4326 (decimal degrees) and then returned as KML.

General Tips