materio-base-d7/sites/all/modules/contrib/fields/location/location_API.txt

This file describes the public API for the CivicSpace location system as defined by
 in the library implemented by "location.inc" and its supporting files.

For a example of this API's usage, please consult "location.module"


FUNCTION SPECIFICATIONS DESCRIBED IN THIS FILE:
----------------------------------------------
  location_get_postalcode_data(): A function that takes a (postalcode,country) pair an returns lat/lon, city, province.  This
                  function is meant to replace location_latlon_rough(); see below.

  location_latlon_rough(): A function that returns the latitude and longitude of the specified postal-code/country pair.
                  This latitude and longitude will be of the approximate center of the postal-code's area.  This function
                  will soon be removed from the API as it has been replaced by the more comprehensive
                  location_get_postalcode_data() described above. [TO BE DEPRECATED]

  location_latlon_exact(): A function that returns the latitude and longitude of the given full location.  Typically implemented
                  on top of a web-service. [TO BE IMPLEMENTED]

  location_map_link(): A function that returns, based on the site configuration, either NULL or 1 or more deep-links to mapping
                   web sites for the parameter location array.

  location_driving_directions_link(): A function that returns, given 2 locationes, a deep-link to Yahoo! Maps or some other site
                  that provides driving directions.  The site chosen depends on the implementation at the country-level.

  location_proximity_form(): A function that generates a form for collecting proximity search parameters.

  location_valid(): A function for validating locationes. [TO BE SPECIFIED]

  theme_location(): A function that takes in an location and themes it.  (e.g., $output .= theme('location', $location)).

  location_distance_between(): A function that, given a pair of lat/lon pairs, returns the distance between them.


"[TO BE SPECIFIED]"   => Function spec has not been completed and may possibly be eliminated from spec.
"[TO BE IMPLEMENTED]" => Function spec exists but is to be implemented in a future release.
"[TO BE DEPRECATED]"  => This function will soon be removed from the API.
----------------------------------------------



IMPORTANT NOTES:
----------------
Formats
---
In the following API, a 'location' is merely an associative array with the following keys:
  'street'      => A string for the street portion of an location
  'additional'  => A string for the additional street portion of an location
  'province'    => An upper-case, standard postal abbreviation of a state/province/territory
  'postal_code' => A string or integer for the postal code
  'country'     => The lower-case of the ISO 3166 two-letter alpha code (e.g., 'us' for U.S., 'ca' for Canada).

For locations that are passed to location_form() for the $prefilled_values parameter, the same format applies
except that the 'province' field is the concatenation of the country code, '-', and the province abbreviation.
For example, 'CA' is the value for California for all purposes, but when passing this in a location for prefilled
values, it should be 'us-CA'.  There are two functions to help convert back and forth between these formats:
location_form2api() and location_api2form().  These are described further below.

Delegation
---
With the exception of location_form() and location_proximity_form(), the calls to functions listed here are, in the end,
dispatched to country-specific location libraries which are implemented in country-specific '.inc' files.  For example,
location_latlon_rough(), when given a U.S. location, really returns a result that is determined by call to
"location_latlon_rough_us()" which is implemented in the file "location.us.inc".

Current Implementation
---
Currently, the only country supported is the United States.  For the future, however, there will be documentation for how to
implement a country-specific include file that can be plugged into the system to support these calls for new countries.  This
scheme will revolve around method signatures for a handful of simple-to-write functions.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
function location_get_postalcode_data($location = array());                                            +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Takes a location and uses the combination of postal code and country to return an array that gives the
city, province, and lat/lon dat for that postal code.

@param $location
  An associative array $location where
    'street'       => the street portion of the location
    'additional' => additional street portion of the location
    'province'     => the province, state, or territory
    'country'      => lower-cased two-letter ISO code (REQUIRED)
    'postal_code'  => international postal code (REQUIRED)

@return
  NULL if data cannot be found.
  Otherwise, an associative array where
    'lat' => is a floating point of the latitude coordinate of this location
    'lon' => is a floating point of the longitude coordinate of this location
    'city' => is a string for the city this postalcode is in (or the most recognized city at the given postal)
    'province' => the province of the given postal code.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
function location_latlon_rough($location = array());                                                   +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Takes an location and returns a "rough" latitude/longitude pair based on the postal code
data available for the given country.

@param $location
  An associative array $location where
    'street'       => the street portion of the location
    'additional' => additional street portion of the location
    'province'     => the province, state, or territory
    'country'      => lower-cased two-letter ISO code (REQUIRED)
    'postal_code'  => international postal code (REQUIRED)

@return
  NULL if data cannont be found.
  Otherwise, an associative array where
    'lat' => is a floating point of the latitude coordinate of this location
    'lon' => is a floating point of the longitude coordinate of this location





++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
function location_latlon_exact($location = array());                                                     +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Currently, this is not a priority until there is an implementable use for exact longitude,
latitude coordinates for an location.  The idea is that this call will eventually retrieve
information through a web-service.  Whereas location_latlon_rough() returns an approximate
lat/lon pair based strictly on the postal code where this lat/lon pair is pulled from a
database table, this function is intended to send the entire location to a web-service and
to retrieve exact lat/lon coordinates.

@param $location
  An array where
    -> the key values are 'street', 'additional', 'province', 'country', 'postal_code'
    -> the values are:
        'street'         => the string representing the street location (REQUIRED)
        'additional'     => the string representing the additional street location portion in the location form
        'city'           => the city name (REQUIRED)
        'province'       => the province code defined in the country-specific include file
        'country'        => the lower-case of the two-letter ISO code (REQUIRED)
        'postal_code'    => the postal-code (REQUIRED)

@return
  NULL if the delegated-to function that does the actual look-up does not exist.
  If the appropriate function exists, then this function returns an associative array where
     'lon' => A floating point number for the longitude coordinate of the parameter location
     'lat' => A floating point number for the latitude coordinate of the parameter location






++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
function location_map_link($location = array(), $link_text = 'See map');                                 +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Get deep-links to a mapping services such as Yahoo! Maps or MapQuest (actual providers depend on configuration
of location module) given a location.  The call is delegated based on the 'country' value in the $location parameter.

@param $location
  An associative array where
     'street'       => A string representing the street location
     'additional'   => A string for any additional portion of the street location
     'city'         => A string for the city name
     'province'     => The standard postal abbreviation for the province
     'country'      => The two-letter ISO code for the country of the location (REQUIRED)
     'postal_code'  => The international postal code for the location

@return
  NULL if there are not mapping providers configured for the country or if no links could be generated.
  A string of the form "See map: Yahoo! Maps, MapQuest" where Yahoo! Maps and Mapquest are links to the
  given location and can be replaced with other options (e.g., Google) available in the location module settings.
  The idea is to encode the appropriate parameters as HTTP GET variables to the URL.





++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
function location_driving_directions_link($locationA = array(), $locationB = array(), $link_text = 'Get directions');
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Takes two locationes and tries to return a deep-link to driving directions.

Parameters:
@param $locationA
  An associative array that represents an location where
     'street'       => the street portions of the location
     'additional'   => additional street portion of the location
     'city'         => the city name
     'province'     => the province, state, or territory
     'country'      => lower-cased two-letter ISO code (REQUIRED)
     'postal_code'  => the postal code

@param $locationB
  An associative array that represents an location in the same way that
  parameter $locationA does.

@param $link_text
  The text of the HTML link that is to be generated.

@return
  A deep-link to driving directions on Yahoo! or some other mapping service, if enough fields are filled in the parameters.
  A deep-link to a form for driving directions with information pre-filled if not enough, but some fields are filled in the parameters.
  The empty string if no information is provided (or if so little information is provided that there is no function to which to delegate
  the call.

  We dispatch the call to a country-specific function.  The country-specific function, in this case,
  will be the one reflected by the country parameter of the first function.  We require that
  both locationes supplied have a country field at the minimum.

  The country-specific functions will ultimately decide, with the parameters given, whether to
  to link to a form for driving directions is provided, where this form will be
  pre-populated with whatever values were available or whether to link directly to the driving
  directions themselves if enough fields are filled for each location.


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
function location_proximity_form($location_form = '', $label = '', $description = '', $prefilled_values = array(), $form_name = 'location');
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
This function generates a form for doing proximity searches within a certain distance
of a specified point.

Depending on the context within which this function is called, the search-point can either
be user-supplied via the location form that is passed (if one is available) or done within
a search-point extracted from a contact table or some other location source specified by
the programmer calling this function.

@param $location_form
  An optional location form, preferably generated by location_form().  If the script processing this
  form also needs a user-supplied location, this parameter is used to specify a form for collecting the
  search-point about which this search is being done.  If the caller does not supply a form, it is
  assumed that the caller already has a search point in mind and that this will be made clear in
  the $description parameter.

@param $label
  The label you want to apply to the form group that is returned (passed as $legend param to form_group()).

@param $description
  A text description of what is being searched for (e.g., 'Find all upcoming events near you.')

@param $prefilled_values
  An associative array for prefilled values for the proximity search parameters, where
    'distance' => is the prefilled int value to be selected for the distance scalar
    'distance_unit' => is 'km' or 'mile'

@param $form_name
  An additional parameter to help prevent HTML input name collisions.  If the caller is using this
  function to generate more than 1 location proximity form on a page, then the generated name for
  each HTML input's "name" attribute will be $form_name.  Allowing the caller to pass $form_name allows
  the caller the flexibility of using more than one location proximity search form on one page.

@return
  An HTML form (generated by Drupal form functions) that lets users specify proximity search parameters that include distance,
  the unit of distance, and a search-point if the optional $location_form parameter is passed.  If one is not passed,
  the caller of this function will be assumed to already have one.






++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
function theme_location($location = array());                                                            +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Generates HTML for the passed location.

@param $location
  An associative array where
     'street'       => A string representing the street location
     'additional'   => A string for any additional portion of the street location
     'city'         => A string for the city name
     'province'     => The standard postal abbreviation for the province
     'country'      => The two-letter ISO code for the country of the location (REQUIRED)
     'postal_code'  => The international postal code for the location

@return
  An HTML string with special tags for locationes.





++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
function location_distance_between($latlonA = array(), $latlonB = array(), $distance_unit = 'km');      +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Given two points in lat/lon form, returns the distance between them.

@param $latlonA
  An associative array where
     'lon' => is a floating point of the longitude coordinate for the point given by latlonA
     'lat' => is a floating point of the latitude coordinate for the point given by latlonB

@param $latlonB
     Another point formatted like $latlonB

@param $distance_unit
     A string that is either 'km' or 'mile'.
     If neither 'km' or 'mile' is passed, the parameter is forced to 'km'

@return
   NULL if sense can't be made of the parameters.
   An associative array where
     'scalar' => Is the distance between the two lat/lon parameter points
     'distance_unit' => Is the unit of distance being represented by 'scalar'.
                        This will be 'km' unless 'mile' is passed for the $distance_unit param