====== Project Improvement Proposal ======

===== PIP 1 – Reverse geocoding requests for Monitoring Locations (MLs) =====

==== Overview ====

Allow EDAS2 to support attributing MLs with geographic attributes by calling a simple remote service. Requires implementation of PIP2 – reverse geocoding services.

==== Proposed By ====

John Zastrow
==== Assigned to Release ====

This proposal will be implemented by the v 0.4 release
==== State ====

Under Discussion, **[In Progress]** , Completed, Rejected, Deferred

==== Motivation ====

"Reverse Geocoding" (RG) is the process of finding an address, toponym or an other type of resource for a given lat/lng pair.  

The association of MLs with other geographic features is required for meaningful management and use of the data. Implementation of the ability to request and associate other geographic features with each ML through a reliable service would save users time and improve the accuracy of the data (e.g., reduce entry errors versus manual entry).

==== Proposal, user view ====

The user would like to:
  -  Create a ML by entering relevant information about its location and characteristics.
  -  Once the system completes creating the record, the user would like to cause an event (e.g., click a link for each station record or multiple records) that would call RG services to retrieve and store geographic attributes for one or MLs.


<code>
<GeoCodeRequest>
<InputLocation>
      	<id>123</id>
            <x>-70.246</x>
            <y>43.805</y>
            <z>0</z>			(optional – not used at this time)
            <crs>4326</crs>		(optional – defaulted to 4326)
</InputLocation>
      <InputLocation>
………………………………………
      </InputLocation>
</GeoCodeRequest>
</code>
	
=== where: === 
  * //GeoCodeRequest// indicates an array of input locations submitted to be geo-coded (the request)
  * //InputLocation// is the details of the submitted input location, with the following fields:
    *  Id is the id of the ML, which is used for identification purposes only, will be returned as is
    *  X is the longitude of the ML
    *  Y is the latitude of the ML
    *  Z is the altitude of the ML, is optional
    *  Crs is the projection information, is optional and, if not specified, will default to 4326
=== Request Rules: === 
    *  Each entry must have at least one InputLocation defined
    *  Each InputLocation must have an unique Id field which is mandatory, as well as a valid longitude (X) and a valid latitude (Y) defined
    *  The Z field of each InputLocation is optional and not used at this time
    *  The Crs field of each InputLocation is optional and will be defaulted to 4326 by the web service in case is not specified

<code>
	<GeoCodeResult>
<OutputLocation>
      	<id>123</id>
            <huc8>36273612</huc8>
            <nhd>8494905483853</nhd>    (not yet implemented)
		…………………………………………………………		(others to be implemented)
      </OutputLocation>
   	<OutputLocation>
		…………………………………………………………
</OutputLocation>
</GeoCodeResult>
</code>

=== where: === 
  * //GeoCodeResult // indicates an array of output locations returned by the web service (the response)
  * //OutputLocation // is the result details of the geo-coded input location, with the following fields:
    * Id is the id of the ML, returned as provided in the input location, in order to identify the ML
    * Huc8 is the 8-digit watershed for the United States
    * Other details to be implemented, like NHD, AUnit, and ReachId

=== Response Rules: === 
  * For each submitted //InputLocation //, a corresponding //OutputLocation // will be returned
  * The Id field, submitted in the //InputLocation //, will be returned as it was submitted, in order to properly identify the returned details for the ML

==== Proposal, implementation ====

The current implementation forces users to manually enter all values. The proposed implementation is to provide a button on each ML Detail screen labeled “GeoLocate” that will issue requests to one or more configured RG services to populate the geographic attributes of the ML.

The order of geographic attributes that will be supported are:

^ Implementation order ^ Tag ^ Database destination ^ Description ^
| 1 | huc8 | ED_MONITORING_LOCATION.MLOC_HUC_8: VARCHAR2(8) | 8-digit watersheds for the United States (subbasins) based on the USGS 1:250K subbasin coverage. Geographic layer is entirely polygon feature type and is topologically contiguous. |
| 2 | aunit | ED_MONITORING_LOCATION.MLOC_ASSESS_UNIT: VARCHAR2(50) NEW field | An arbitrary unit for use by the individual database owner. The first users will likely be state users who need to assign MLs to surface water quality management entities commonly referred to as assessment units. May refer to multiple coverages and may be lines or polygons. |
| 3 | reachid |  ED_MONITORING_LOCATION.MLOC_REACHID: VARCHAR2(16) NEW field | 14 Digit reach identifiers from the high-resolution (1:24K) National Hydrography Dataset flowlines feature class. Geographic layer is entirely line feature type. |
| 4 | huc12 | ED_MONITORING_LOCATION.MLOC_HUC_12: VARCHAR2(12) NEW field | 12-digit watersheds for the United States (subwatershed) based on … Geographic layer is entirely polygon feature type and is topologically contiguous. |


==== Feedback ====

None

==== Backwards Compatibility ====

None to maintain


==== Links ====

http://geoserver.org/display/GEOS/GSIP+19+-+Per+layer+security
http://www.geonames.org/export/reverse-geocoding.html 

==== Appendices ====