[[TOC]]
= Locations Hierarchy =

Provide a flexible Locations Hierarchy.

These are the 'Admin Boundaries': L0 - L4

Adding of locations within the L0-L4 range should normally be done by the Administrator prior to going live with the deployment so that these can then be locked-down to the !MapAdmin role to prevent duplicate name entries.

Default names (customisable in {{{models/000_config.py}}}):
{{{
deployment_settings.gis.locations_hierarchy = {
    "L0":T("Country"),
    "L1":T("Province"),
    "L2":T("District"),
    "L3":T("Town"),
    "L4":T("Village")
}
}}}

Since most deployments are restricted to just 1 or few countries, it is possible to hard-code which ones are used (in {{{models/000_config.py}}}):
{{{
deployment_settings.L10n.countries = ["PK"]
}}}



== Location Selector ==
Status: PakistanDevelopers#LocationsSelector

There are 6 ways of adding a location, listed in ideal order:
 1. '''Bulk import''' has either Location Names or Lat/Lons
 * This could optionally use Image EXIF headers or a timesynced GPX file
  * NB: This refinement can be added later
 2. '''HTML5 !GeoLocation''': If the resource is one where the user is likely to be physically at the relevant location
 * e.g. pr/person/presence can be recorded automatically upon login
 * We should use a 'nearby' algorithm (like {{{gis.get_features_in_radius()}}}) to re-use existing locations rather than adding a new one each time.
 * NB: This refinement can be added later
 3. '''Map''': User clicks on a location on the map
 * If we have admin boundaries available then:
  * We can zoom to the correct area if a level of hierarchy has been selected
  * The correct hierarchy can be filled-in automatically
 * If not then the user can be prompted to provide these (as per 6)
 * Michael: It would also be useful if existing locations could be displayed on the map (prehaps with the Location Type displayed too), so that the user could add a new location relative to existing locations, or choose a existing location off the map instead.
 4. '''Manual Entry of Lat/Lon''': (either from a GPS or looked up in an online resource like Wikipedia)
 * A Conversion tool is available to convert from Deg/Min/Sec to Decimal Degrees
 * If we have admin boundaries available then the correct hierarchy can be filled-in automatically
 * If not then the user can be prompted to provide these (as per 6)
 5. '''Geocoder''': Street Address is entered & this is matched to a location via a Geocoding service
 * We already have functionality ready for Google & Yahoo in {{{modules/s3gis.py}}}.
 * We need to add at least [http://geonames.org Geonames].
 6. '''Hierarchical Selector''':
 * We have dropdowns for each of the different levels.
 * The country selector should remain hidden if there is only 1 country being used.
 * Initially just a single dropdown should be displayed.
 * When this dropdown is selected then the next dropdown is displayed, along with appropriate values
  * We download the values via AJAX in order to not have to download all Locations, however we could download the next set in the background whilst the user is thinking: means a bigger download to filter client-side, but maybe less time overall. Can be experimented with.
 * When the final dropdown is selected then the user has the option of adding a more specific Name & a Street Address
  * This should not be mandatory as some records need to link directly to the L0-L4 levels.

If adding a new Location, then the name of the location should *not* be the general name, but rather a specific one
 * Where possible, we automate this by using the name of the Shelter or Hospital
  * Should we prevent 'Add Location' from working until that field is filled-in?
 * We need to make this clear in the online help.

We want to be able to optionally specify which levels of hierarchy we are interested in for this resource. This would be part of the API for gis.get_location_id()

== Agasti ==

Sahana Phase2 has a nice hierarchical Locations system:
 * http://wiki.sahanafoundation.org/doku.php?id=dev:location_handler
This is useful for categorising data for Reporting purposes.

It doesn't have any link to GIS though....we need to be able to link the Locations to GIS polygons.
 * [http://thematicmapping.org/downloads/TM_WORLD_BORDERS-0.3.zip Sample Polygons for Country-level boundaries]

The definition of Locations can be different in different sectors (not just the names of the locations, but also their actual boundaries)[[BR]]
e.g.:
 * category = "Health" would have types = National, Regional, Provincial, District, MOH Divisions, PHI areas, etc
 * category = "Governance" would have types = National, Provincial (or state), District, Division, Tribunal (or Gramasevaka area)

----
[wiki:BluePrintGeographicInformationSystems GIS BluePrints]