Updated Jan 16, 2009 by gtuco.btuco
Labels:	Phase-Requirements

WebServicesRequirements

Project vision and requirements

Web Services Vision

A georeferencing web service that accepts a DwC record and returns that record along with all georeferences for it generated by the BioGeomancer Core API.

Single Georeference Requirements

Web Service Interface

The web service interface accepts HTTP GET requests using the following case insensitive URL parameters:

Parameter	Description
highergeography, hg	Darwin Core HigherGeography concept
continent, cont	Darwin Core Continent concept
waterbody, wb, w	Darwin Core WaterBody concept
islandgroup, ig	Darwin Core IslandGroup concept
island, is	Darwin Core Island concept
country, cy, gadm0	Darwin Core Country concept
stateprovince, sp, s, gadm1	Darwin Core StateProvince concept
county, co, gadm2	Darwin Core County concept
locality, loc, l	Darwin Core Locality concept
verbatimlatitude, latitude, vlat, lat	Geospatial Extension VerbatimLatitude concept
verbatimlongitude, longitude, vlong, vlng, long, lng	Geospatial Extension VerbatimLongitude concept
interpreter, int, i	BioGeomancer locality interpreter ('yale', 'uiuc', 'tulane'; default is 'yale')
header	BioGeomancer flag to show locality input in output header ('true', 'false'; default is 'false')

Example: http://bg.berkeley.edu/ws/single?locality=Stuttgart&country=Germany&interpreter=yale&header=true

Web Service Output

The web service output format will be XML (UTF-8) with dwcore as the namespace for Darwin Core elementsand "dwgeo" as the namespace for Geospatial Extension elements. All URL request parameters will appear in the output if the header parameter is set to 'true'. For example:

<?xml version="1.0" encoding="utf-8"?>
<biogeomancer xmlns:dwcore="http://rs.tdwg.org/dwc/dwcore/ xmlns:dwgeo="http://rs.tdwg.org/dwc/geospatial/">
  <interpreter>yale</interpreter>
  <dwcore:Country>Germany</dwcore:Country>
  <dwcore:Locality>Stuttgart</dwcore:Locality>
  <georeference>
    <interpretedLocality>Germany (gadm2:58:countries); Stuttgart (GADM:16422:countries, 2nd order divisions)</interpretedLocality>
    <dwgeo:DecimalLatitude>49.1430493</dwgeo:DecimalLatitude>
    <dwgeo:DecimalLongitude>9.6254345</dwgeo:DecimalLongitude>
    <dwgeo:GeodeticDatum>WGS84</dwgeo:GeodeticDatum>
    <dwgeo:CoordinateUncertaintyInMeters>93264.0</dwgeo:CoordinateUncertaintyInMeters>
  </georeference>
</biogeomancer>

Batch Georeference Requirements

Web Service Interface

Batch georeferencing will be supported by HTTP POST of an XML batch request with a 5000 record limit. In addition to an optional field "id" (case sensitive), the following DwC elements are accepted and interpreted as input:

Element	Description
HigherGeography	Darwin Core HigherGeography concept
Continent	Darwin Core Continent concept
WaterBody	Darwin Core WaterBody concept
IslandGroup	Darwin Core IslandGroup concept
Island	Darwin Core Island concept
Country	Darwin Core Country concept
StateProvince	Darwin Core StateProvince concept
County	Darwin Core County concept
Locality	Darwin Core Locality concept
VerbatimLatitude	Geospatial Extension VerbatimLatitude concept
VerbatimLongitude	Geospatial Extension VerbatimLongitude concept
interpreter	BioGeomancer locality interpreter ('yale', 'uiuc', 'tulane'; default is 'yale')
header	BioGeomancer flag to show locality input in output header ('true', 'false'; default is 'false')

Example batch request XML:

<?xml version=\"1.0\" encoding=\"utf-8\"?>"
<biogeomancer xmlns="http://bg.berkeley.edu" xmlns:dwcore="http://rs.tdwg.org/dwc/dwcore" xmlns:dwgeo="http://rs.tdwg.org/dwc/dwgeo">
<request type="batch" interpreter="yale" header="true">
  <record>
   <dwcore:id>1</dwcore:id>
   <dwcore:Locality>Berkeley</dwcore:Locality>
   <dwcore:StateProvince>California</dwcore:StateProvince>
  </record>
  <record>
   <dwcore:Locality>Stuttgart</dwcore:Locality>
   <dwcore:Country>Germany</dwcore:Country>
  </record>
  <record>
   <dwcore:Locality>3 mi E Lolo</dwcore:Locality>
   <dwcore:County>Missoula</dwcore:County>
  </record>
 </request>
</biogeomancer>

Web Service Output

Batch georeferencing output will be XML (UTF-8) with a dwcore and dwgeo namespaces reflecting concepts in the Darwin Core and Geospatial Extension schemas. For example, the response for the request shown above should be:

<?xml version="1.0" encoding="UTF-8"?>
<biogeomancer xmlns:dwcore="http://rs.tdwg.org/dwc/dwcore" xmlns:dwgeo="http://rs.tdwg.org/dwc/geospatial">
  <records>
   <record>
    <interpreter>yale</interpreter>
    <dwcore:id>1<dwcore:id>
    <dwcore:StateProvince>California</dwcore:StateProvince>
    <dwcore:Locality>Berkeley</dwcore:Locality>
    <georeference>
     <interpretedLocality>California (gadm2:3691:countries, 1st order divisions); Berkeley (GNIS:78808477:populated places)</interpretedLocality>
     <dwgeo:DecimalLatitude>37.8715897</dwgeo:DecimalLatitude>
     <dwgeo:DecimalLongitude>-122.26812</dwgeo:DecimalLongitude>
     <dwgeo:GeodeticDatum>WGS84</dwgeo:GeodeticDatum>
     <dwgeo:CoordinateUncertaintyInMeters>5391.0</dwgeo:CoordinateUncertaintyInMeters>
    </georeference>
   </record>
   <record>
    <interpreter>yale</interpreter>
    <dwcore:Country>Germany</dwcore:Country>
    <dwcore:Locality>Stuttgart</dwcore:Locality>
    <georeference>
     <interpretedLocality>Germany (gadm2:58:countries); Stuttgart (GADM:16422:countries, 2nd order divisions)</interpretedLocality>
     <dwgeo:DecimalLatitude>49.1430493</dwgeo:DecimalLatitude>
     <dwgeo:DecimalLongitude>9.6254345</dwgeo:DecimalLongitude>
     <dwgeo:GeodeticDatum>WGS84</dwgeo:GeodeticDatum>
     <dwgeo:CoordinateUncertaintyInMeters>93264.0</dwgeo:CoordinateUncertaintyInMeters>
    </georeference>
    <georeference>
     <interpretedLocality>Germany (gadm2:58:countries); Stuttgart (GeoNet Names (NIMA):68012471:agricultural sites)</interpretedLocality>
     <dwgeo:DecimalLatitude>47.6852721</dwgeo:DecimalLatitude>
     <dwgeo:DecimalLongitude>8.9012315</dwgeo:DecimalLongitude>
     <dwgeo:GeodeticDatum>WGS84</dwgeo:GeodeticDatum>
     <dwgeo:CoordinateUncertaintyInMeters>4552.0</dwgeo:CoordinateUncertaintyInMeters>
    </georeference>
    <georeference>
     <interpretedLocality>Germany (gadm2:58:countries); Stuttgart (GeoNet Names (NIMA):68012472:airport features)</interpretedLocality>
     <dwgeo:DecimalLatitude>48.6833324</dwgeo:DecimalLatitude>
     <dwgeo:DecimalLongitude>9.1999998</dwgeo:DecimalLongitude>
     <dwgeo:GeodeticDatum>WGS84</dwgeo:GeodeticDatum>
     <dwgeo:CoordinateUncertaintyInMeters>4242.0</dwgeo:CoordinateUncertaintyInMeters>
    </georeference>
    <georeference>
     <interpretedLocality>Germany (gadm2:58:countries); Stuttgart (GeoNet Names (NIMA):68012473:capitol buildings)</interpretedLocality>
     <dwgeo:DecimalLatitude>48.7666683</dwgeo:DecimalLatitude>
     <dwgeo:DecimalLongitude>9.1833339</dwgeo:DecimalLongitude>
     <dwgeo:GeodeticDatum>WGS84</dwgeo:GeodeticDatum>
     <dwgeo:CoordinateUncertaintyInMeters>2282.0</dwgeo:CoordinateUncertaintyInMeters>
    </georeference>
    <georeference>
     <interpretedLocality>Germany (gadm2:58:countries); Stuttgart (usersdb:8999:user added feature)</interpretedLocality>
     <dwgeo:DecimalLatitude>48.7666702</dwgeo:DecimalLatitude>
     <dwgeo:DecimalLongitude>9.1833296</dwgeo:DecimalLongitude>
     <dwgeo:GeodeticDatum>WGS84</dwgeo:GeodeticDatum>
     <dwgeo:CoordinateUncertaintyInMeters>10048.0</dwgeo:CoordinateUncertaintyInMeters>
    </georeference>
   </record>
   <record>
    <interpreter>yale</interpreter>
    <dwcore:County>Missoula</dwcore:County>
    <dwcore:Locality>3 mi E Lolo</dwcore:Locality>
    <georeference>
     <interpretedLocality>Missoula (gadm2:34036:countries, 2nd order divisions); 3 mi E of Lolo (GNIS:78928362:manmade features)</interpretedLocality>
     <dwgeo:DecimalLatitude>46.7588158</dwgeo:DecimalLatitude>
     <dwgeo:DecimalLongitude>-114.017748</dwgeo:DecimalLongitude>
     <dwgeo:GeodeticDatum>WGS84</dwgeo:GeodeticDatum>
     <dwgeo:CoordinateUncertaintyInMeters>6303.0</dwgeo:CoordinateUncertaintyInMeters>
    </georeference>
    <georeference>
     <interpretedLocality>Missoula (gadm2:34036:countries, 2nd order divisions); 3 mi E of Lolo (GNIS:79784822:populated places)</interpretedLocality>
     <dwgeo:DecimalLatitude>46.7588158</dwgeo:DecimalLatitude>
     <dwgeo:DecimalLongitude>-114.017748</dwgeo:DecimalLongitude>
     <dwgeo:GeodeticDatum>WGS84</dwgeo:GeodeticDatum>
     <dwgeo:CoordinateUncertaintyInMeters>8061.0</dwgeo:CoordinateUncertaintyInMeters>
    </georeference>
    <georeference>
     <interpretedLocality>Missoula (gadm2:34036:countries, 2nd order divisions); 3 mi E of Lolo (CONUS TIGER:8009251:populated places)</interpretedLocality>
     <dwgeo:DecimalLatitude>46.7742577</dwgeo:DecimalLatitude>
     <dwgeo:DecimalLongitude>-114.0447684</dwgeo:DecimalLongitude>
     <dwgeo:GeodeticDatum>WGS84</dwgeo:GeodeticDatum>
     <dwgeo:CoordinateUncertaintyInMeters>8172.0</dwgeo:CoordinateUncertaintyInMeters>
    </georeference>
   </record>
  </records>
</biogeomancer>}}}