= 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 rdf file 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: 
{{{
<regions>
  <region id="338" hasGeom="false" categoryId="continent">
    <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>
         <fre>Continent</fre>
         <eng>Continent</eng>
    </category>
  </record>
</response>
}}}
 * List
  * Params
   * category - only return labels contained in the given category - optional
   * label - searches the labels for regions that contain the text in this parameters - optional
   * maxRecords - limit the number of results returned - optional
  * Example Response
{{{
<regions count="1">
  <region id="country.1" hasGeom="true" categoryId="country">
    <label>
      <eng>France</eng>
    </label>
    <category>
         <fre>Pays</fre>
         <eng>Country</eng>
    </category>
  </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
   * 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:
{{{
  MULTIPOLYGON (((30 20, 10 40, 45 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))
}}}
 * !GetMap - return a rendering of the geometry as a png.  If no background is specified the image will be a transparent png
  * id - required
  * srs - (optional) default is EPSG:4326 otherwise it is the project to use when rendering the image
  * width - (optional) width of the image that is created.  Only one of width and height are permitted
  * height - (optional) height of the image that is created.  Only one of width and height are permitted
  * background - URL for loading a background image for regions.   A WMS Getmap request is the typical example.  The URL must be parameterized with the following parameters: 
   * minx
   * maxx
   * miny
   * maxy
   * width
   * height
   * srs (Optional)

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