This is preliminary documentation for the HTTP API for Josh's experimental WMS project.
The WMS server maintains a set of geospacial geometry features, polygons and points, and style layers indicating how the geometry should be rendered in an image. Map tile images are served using the WMS protocol, and the tiles can be used in layers with Google Maps, OpenLayers, and other map display widgets for web pages.
Geospacial features are grouped into "datasets". Each dataset has a name. Datasets contain a set of regions, which are named using URIs. Each region can be composed of a set of polygons and points. Polygons and points are specified in longitude/latitude pairs. Access to modify datasets is controlled by an API key password.
Style information are grouped into layers. Each layer has a name. Access to modify layers is controlled by an API key password.
Uploading a dataset means uploading longitude/latitude data for polygons and points in a particular dataset. This can be accomplished by calling the API upload-geometry.cgi with the following parameters:
| Parameter | Explanation |
|---|---|
| key | The API key issued by Josh that gives you write-access to particular datasets and layers. |
| dataset | The name of the dataset to modify. The contents of the dataset are replaced with the new data. |
| geometry | A table of polygon and point data. This parameter is composed of multiple lines. Each line represents a polygon or point. The lines are tab-delimited. The first column is the identifier of the region that this polygon or point is a part of. You are free to choose any string as the identifier, although using a URI is recommended. The second column starts with points: and is followed by a comma-separated list of longitude and latitude values. For a polygon, you will specify three or more pairs of long/lat values. For a point, just specify a single long/lat pair. |
Here is an example of the geometry parameter. A polygon ("region1") and a point ("region2") are created in the dataset.
region1 points:-70,40, -80,40, -75,50 region2 points:-75,45
One way to call the API is using the Linux wget command. Put all of the API parameters into a file, separating the parameters with ampersands:
key=test&dataset=test&geometry= region1 points:-70,40, -80,40, -75,50 region2 points:-75,45
Then run wget:
wget -O - --post-file parametersfile.txt http://www.govtrack.us/perl/wms/upload-geometry.cgi
Uploading a layer means uploading the coloring and other information needed to render the geospacial features in an image. This can be accomplished by calling the API upload-styles.cgi with the following parameters:
| Parameter | Explanation |
|---|---|
| key | The API key issued by Josh that gives you write-access to particular datasets and layers. |
| layer | The name of the layer to modify. The contents of the layer are replaced with the new data. |
| dataset | Optional. The name of the dataset containing the regions to include in this layer. |
| styles | A table of region identifiers and style information. Each row represents a region (which may correspond to more than one polygon or point). Each row is tab-delimited. The first column is the identifier for a region contained in the dataset dataset. If the dataset parameter is not set, or to refer to a region in a different dataset, prefix the region identifier with the name of the dataset followed by the @-sign. The remaining columns specify style information. Each column is a name:value pair. |
For the styles parameter, the following style attributes can be set:
| Style Name | Explanation | Example |
|---|---|---|
| bordercolor | The color of the outline of the shape. Leave out to not draw a border. An RGB color is used. | 255,0,0 (i.e. red) |
| borderweight | The thickness of the outline of the shape, in pixels. Leave out or set to zero to not draw a border. | 2 |
| fillcolor | The color of the interior of the shape. Leave out to not shade the interior. An RGB color is used. | 255,0,0 (i.e. red) |
| radius | The radius of the circle, for point features only, in pixels. | 5 |
| textcolor | The color of text label. An RGB color is used. | 255,0,0 (i.e. red) |
| label | The text of a label. Leave out to not draw a label. | New York |
| markerdata | Arbitrary user data which is stored with the region and can be retreived through the get-markers.cgi API. |
More information on RGB colors can be found here and here. The color components are specified on a 0-to-255 scale.
Here is an example of the styles parameter. Style information is set for "region1" and "region2" for the dataset created above, plus for the region representing New York, which is in the dataset "http://www.rdfabout.com/rdf/usgov/us/states" and is identified as "http://www.rdfabout.com/rdf/usgov/geo/us/ny".
region1 bordercolor:255,0,0 borderweight:1 region2 bordercolor:0,0,255 borderweight:2 fillcolor:0,255,0 radius:5 label:ABC http://www.rdfabout.com/rdf/usgov/us/states@http://www.rdfabout.com/rdf/usgov/geo/us/ny bordercolor:255,0,0 borderweight:2
One way to call the API is using the Linux wget command. Put all of the API parameters into a file, separating the parameters with ampersands:
key=test&layer=test&dataset=test&styles= region1 bordercolor:255,0,0 borderweight:1 region2 bordercolor:0,0,255 borderweight:2 fillcolor:0,255,0 radius:5 label:ABC http://www.rdfabout.com/rdf/usgov/us/states@http://www.rdfabout.com/rdf/usgov/geo/us/ny bordercolor:255,0,0 borderweight:2
Then run wget:
wget -O - --post-file parametersfile.txt http://www.govtrack.us/perl/wms/upload-styles.cgi
Note that when using wget, the values of the parameters like label and markerdata must be URL-encoded.
The list-regions.cgi API returns a table of region identifiers included in a layer or dataset. (A layer may not include all of the regions in the datasets it uses). The API can return additional information for each region. The following parameters can be used:
| Parameter | Explanation |
|---|---|
| layer | Optional. Either the layer or dataset parameter must be given. The layer for which the regions should be listed. |
| dataset | Optional. Either the layer or dataset parameter must be given. The dataset for which the regions should be listed. |
| fields | The additional information to report for each region. This is a comma separated list potentially including "coord" (to return longitude and latitude pairs for a point in each region) and "area" (to report an area column for each region, in square miles), or an empty list to not report additional information. |
| header | Optional. Set to 1 to include column headers in the output. |
| format | Optional. Leave unspecified or set to 'text' to get a tab-separated table. Set to 'json' to get the results in a format suitable for JSON. |
As an example, the following API call returns the region identifiers for the dataset for the U.S. congressional districts and for each polygon that makes up a part of a congressional district a central point within the district:
If the fields parameter is empty, only a unique list of region identifiers is returned, rather than a row for each polygon or point that makes up each region.