= Extended Regions =

|| '''Date''' || 2012/09/14 ||
|| '''Contact(s)''' || [http://wiki.osgeo.org/wiki/User:Jeichar Jesse Eichar] ||
|| '''Last edited''' || ||
|| '''Status''' || Proposed ||
|| '''Assigned to release''' || 2.9.x ||
|| '''Resources''' || Jesse personal time ||
|| '''Code''' || https://github.com/jesseeichar/core-geonetwork/tree/improvement/regions ||

== Overview ==

This proposal intends to extend the existing Regions API with the following features:

 * Add category for each region so they can be displayed in categories (for example continent, country, province)
 * Add API for searching regions based:
  * name
  * category
  * bbox
 * Add optional geometry for each region (in addition to bbox)
 * integrate into !XmlSearch and Csw so that the region id can be used to look up the geometry of the region for a spatial filter
 * Add a configurable strategy object for that allows the region implementation to be easily pluggable.  For example it might be based on a table in the database or wfs 

=== Proposal Type ===
 * '''Type''': Improvement
 * '''App''': Geonetwork
 * '''Module''': Web

=== Links ===
 
 * '''Email discussions''':
 * '''IRC discussions''':
 * '''Related work''':

 
=== Voting History ===

 * None as yet

----


== Proposal == 

The Regions will be backwards compatible but will simply extend the functionality.  Currently the Regions API provides a list of regions, each with a unique id.  Each region has translated labels and a bounding box.  The proposal will extend that API.  The new API will be:


 * Get
  * Params
    * id - required
  * Example Response: 
{{{
<response>
  <record>
    <id>338</id>
    <north>38.2</north>
    <south>-34.6</south>
    <west>-17.3</west>
    <east>51.1</east>
    <label>
      <eng>Africa</eng>
      <fre>Afrique</fre>
      <ger>Afrika</ger>
      <spa>Africa</spa>
      <rus>Africa</rus>
      <por>Africa</por>
      <chi>Africa</chi>
      <dut>Afrika</dut>
      <nor>Africa</nor>
      <fin>Africa</fin>
      <ara>Africa</ara>
      <ita>Africa</ita>
    </label>
    <category>continent</category>
    <hasGeom>false</hasGeom>
  </record>
</response>
}}}
 * List
  * Params
   * category - optional
   * bbox (minx,maxx,miny,maxy, srs) - optional.  SRS is optional and assumed to be EPSG:4326
   * label - searches the labels for regions that contain the text in this parameters - optional
  * Example Response
{{{
<regions count="1">
  <region>
    <id>country.1</id>
    <label>
      <eng>France</eng>
    </label>
  </region>
</regions>
}}}
 * !GetGeom - will return the geometry for the region. If the geometry does not have a geometry then the bbox will be used to construct a polygon.
  * Params
   * id - required (if multiple are provided then multiple geometries will be returned)
   * simplified - optional (if present and true then the geometry will be a simplified version.  Some implementations may ignore this hint and return full geometry)
  * Example Response:
{{{
<response>
  <geom id="2"> MULTIPOLYGON (((30 20, 10 40, 45 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))</geom>
  <geom id="3"> MULTIPOLYGON (((30 20, 10 40, 45 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))</geom>
</response>
}}}

The !XmlSearch API will be modified so the geom parameter can either be WKT or have the form: region:id, where id is the id of the region to use as a geometry.  If the region has a geometry then that geometry will be loaded otherwise the bbox will be used to create a polygon geometry.

The !CatalogSearcher (part of Csw !GetRecords) will be modified to replace elements with the attribute gml:id which have the form: region:id

The actual implementation will consist of the services and a strategy object that can be configured the geonetwork configuration files.  The intention is that for a particular application the strategy object can be implemented and configured for use.  The default implementation will be the current implementation factored out into the strategy object.

=== Backwards Compatibility Issues ===

none

== Risks ==


== Participants ==
 * As above