You are here

API.txt in Location 5.3

Note: This is currently broken and outdated.
The location search api is not ready for location 3.



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_nearby_postalcodes_bylocation(): A function that searches for postal codes within a specified search-radius
                  for a specified location.

  location_nearby_postalcodes_bylatlon(): A function that searches for postal codes within a specified search-radius for
                  a specified latitude and longitude.

  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_form(): A function that generates a form for collecting locative information.  Depending on the parameters,
                  it can collect just the postal code and country or a full location or whatever fields are specified
                  in its parameters.

  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.

  location_form2api(): A function that, given an location submitted via a form generated by location_form, converts the
                      submitted location into a form to be used by the rest of the API.

  location_api2form(): A function that, given an location in the standard array format (see "IMPORTANT NOTES" below)
                      returns an location in a format that can be passed to location_form in order to render the
                      form with the appropriate prefilled values.


"[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_nearby_postalcodes_bylocation($location, $distance, $distance_unit = 'km');
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Takes an location and a distance and returns an array of all postal-codes (from all countries that are supported)
within the specified distance of the specified location.

@param $location
  An associative array where
    'street'       => the street location
    'additional'   => extra street location or building name or hall or something like that.
    'city'         => a city name
    'province'     => province code as defined by the country specific include file
    'country'      => lower-cased two-letter ISO 3166 code (REQUIRED)
    'postal_code'  => the postal_code

@param $distance
  The number portion of the distance; it is forced to an integer ceiling

@param $distance_unit
  The unit of distance being used for the distance being submitted.
  Valid arguments for $distance_unit are 'mile' and 'km'.  If something other than one of
  these unit types is submitted for this argument, it is forced to 'km'.

@return
  An array where
    -> the keys are a postive integer ranking of the search result's closeness to the parameter $postal_code
       with 1 being assigned to the nearest postal code
    -> the values are an associative array where
         'postal_code'   => A postal code that fell within the search-radius given by $distance and $distance_unit.
         'country'       => The two-letter ISO code for the home-country of this particular postal_code search result.
         'city'          => The city to which this postal code belongs.
         'province'      => The province to which this postal code belongs.
         'lon'           => The longitude coordinate of the approximate center of the area covered by 'postal_code'
         'lat'           => The latitude coordinate of the approximate center of the area covered by 'postal_code'
         'distance'      => The number of 'km's or 'mile's that are between the approximate center of the area of
                            the $postal_code parameter and that of the 'postal_code' in this subarray
         'distance_unit' => The unit of distance specified by 'scalar'






++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
function location_nearby_postalcodes_bylatlon($lon, $lat, $distance, $distance_unit = 'km');
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Takes a latitude, longitude, and a distance, and returns all postal_codes within

@param $lon
  A floating point of the longitude coordinate of the search point

@param $lat
  A floating point of the latitude coordinate of the search point

@param $distance
  The number portion of the distance; it is forced to an integer ceiling

@param $distance_unit
  The unit of distance being used for the distance being submitted.
  Valid arguments for $distance_unit are 'mile' and 'km'.  If something other than one of
  these unit types is submitted for this argument, it is forced to 'km'.

@return
  An array where
    -> the keys are a contatenation of the country's ISO code and the postal code.  For example, if
       one of the search results is for postal code "94803" in the United States, the key is then "us94803"
    -> the values are an associative array where
         'postal_code'   => A postal code that fell within the search-radius given by $distance and $distance_unit.
         'country'       => The two-letter ISO code for the home-country of this particular postal_code search result.
         'lon'           => The longitude coordinate of the approximate center of the area covered by 'postal_code'
         'lat'           => The latitude coordinate of the approximate center of the area covered by 'postal_code'
         'distance'      => The number of 'km's or 'mile's that are between the approximate center of the area of the
                            $postal_code parameter and that of the 'postal_code' in this array
         'distance_unit' => The unit of distance specified by 'distance'


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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_form($fields = array(), $prefilled_values = array(), $required_fields = array(), $description = '', $form_name = 'location', $function = NULL);
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Generates a Drupal HTML form for collecting locationes.

@param $fields
  An array of values where each value is one of 'street', 'city', 'province', 'postal_code', or 'country'.
  The presence of values in this array determines which fields will be served in the location form generated
  by a call to this function.  If this array is empty, all fields are generated.

@param $prefilled_values
  An associative array where
    -> Each key is one of the location fields: 'street', 'additional', 'city', 'province', 'postal_code', 'country'
    -> Each value is a prefilled value for the given field.                                       ..... ))

@param $required_fields
  An array of values that are required.  Each string can be one of 'street', 'city', 'postal_code', 'province', or 'country'.
  The presence of values in this array determines which fields will be marked as 'required'.  Validation (i.e., making sure
  a required value is actually filled in is the responsibility of the caller)

@param $description
  A text description of specifically what location is being collected by the form to be served.

@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 form on a page, then the generated name for each HTML input's
  "name" attribute will go by the value supplied for $form_name.  This parameter is defaulted to 'location'
  For example, if $form_name == 'xyz' and there is a 'street' field in the form to be served,
  the "name" attribute for the HTML <input> will be "edit[xyz][street]"

@param $function
  A string that tells location_form() which location API function will be using the location submitted via the
  generated form.  For example, if $function == 'latlon_rough', then the returned location_form (if it includes
  a country field) will only generate a list of countries in the HTML select for which function location_latlon_rough()
  is supported.  To figure out which countries these are, we check to see which of the configured countries have existing
  functions to support the call.  In this case, we would check to see if there existed a function called "location_latlon_rough_us()"
  before listing the United States in the HTML SELECT for the generated location form.  $function is defaulted to NULL.
  If $function is NULL, the HTML SELECT that is generated will list all countries.

@return
  An location form based on the parameters specified.  If the $fields array is empty, then the
  function returns a form in which all possible fields are served as optional form items.


EXAMPLES:

   -> The following call returns a form that only contains fields for a postal_code and country where
      the postal_code is required:
           ---
           $form = location_form(array('postal_code', 'country'), array(), array('postal_code', 'country'), 'Permanent location')
           ---
      The form returned by this call is generated with calls to Drupal's 'form_' functions:

           $form  = form_textfield('Postal Code', 'location][postal_code', '', 64, 64, NULL, NULL, TRUE);
      -------------------------------------------------------------------------------------------------
   -> The following call returns a form that contains fields for a street, province, and postal_code,
      but the street, city, and province fields are optional while postal_code is required:
           ---
           $form = location_form(array('street', 'city', 'province', 'postal_code'), array(), array('postal_code'));
           ---
   -> The form returned by this call is generated with the following calls to Drupal's 'form_' functions:

           $form  = form_textfield('Street', 'location][street', '', 64, 64);
           $form .= form_textfield('Additional', 'location][additional', '', 64, 64);
           // The 'Additional' field is always and only generated when 'street' is specified as one of the fields.
           // The 'Additional' field is always optional whether or not 'Street' is required.
           $form .= form_textfield('City', 'location][city', '', 64, 64);
           $form .= _location_province_select_options(); // defined below
           $form .= form_textfield('Postal Code', 'location][postal_code', '', 64, 64, NULL, NULL, TRUE);
       ------------------------------------------------------------------------------------------------
   For the following examples, assume we have the following two locationes:
      (1) $locationA = ('street' => '2010 Broadway St', 'city' => 'Redwood City', 'province' => 'CA', 'postal_code' => '94063', 'country' => 'us');
      (2) $locationB = ('street' => '2010 Broadway St', 'city' => 'Redwood City', 'province' => 'us-CA', 'postal_code' => '94063', 'country' => 'us');
    -> The following calls return the exact same form that contains fields for a street, province, postal_code, where prefilled
       values are submitted to the form.

           $form = location_form(array('street', 'city', 'province', 'postal_code', 'country'), $locationB, array('street', 'city', 'province', 'postal_code',  country'), '', 'home_location');

           $form = location_form(array('street', 'city', 'province', 'postal_code', 'country'), location_api2form($locationA), array('street', 'city', 'province', 'postal_code', 'country'), '', 'home_location');

    -> The form returned by these call is ultimately generated with the following calls to Drupal's 'form_' functions:

           $form  = textfield('Street', 'home_location][street', '2010 Broadway St.', 64, 64, NULL, NULL, TRUE);
           $form .= textfield('Additional', 'home_location][additional', 'Attn: Ankur Rishi', 64, 64, NULL, NULL, TRUE);
           $form .= textfield('City', 'home_location][city', 'Redwood City', 64, 64, NULL, NULL, TRUE);
           $form .= _location_province_select_options(TRUE, 'us-CA', 'home_location');
           $form .= textfield('Postal Code', 'home_location][postal_code', '94063', 64, 64, NULL, NULL, TRUE);
           $form .= _location_country_select_options(TRUE, 'us', 'home_location');

       Note that in both cases, the first and third argument can take the same array since all the fields are being required.






++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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





++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
function location_form2api($location = array());                                                         +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@param $location
  An associative array that has been submitted by an HTML form generated by location_form().

@return
  An associative array in which the submitted values are modified to pass to the location API
  as the $location parameter (excepting location_form()).

  This means changing the province field to remove the country code and dash.
  For example: California is served by the key 'us-CA' in the location form and this is what is passed when it is
               submitted through a form generated by location_form().

               This is changed to 'CA' in the returned array.






++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
function location_api2form($location = array());                                                         +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Inverse of location_form2api()

@param $location
  An associative array that can be passed as the $location parameter to the location API.

@return
  An associative array with the same values modified so that the array can be passed as the
  $prefilled_values parameter to location_api2form()

  Meant to take the standard location array format used by the public API (minus the form generating functions) and convert them
  into values that can be used by location_form() to fill in the prefilled values.

File

contrib/location_search/API.txt
View source
  1. Note: This is currently broken and outdated.
  2. The location search api is not ready for location 3.
  3. This file describes the public API for the CivicSpace location system as defined by
  4. in the library implemented by "location.inc" and its supporting files.
  5. For a example of this API's usage, please consult "location.module"
  6. FUNCTION SPECIFICATIONS DESCRIBED IN THIS FILE:
  7. ----------------------------------------------
  8. location_nearby_postalcodes_bylocation(): A function that searches for postal codes within a specified search-radius
  9. for a specified location.
  10. location_nearby_postalcodes_bylatlon(): A function that searches for postal codes within a specified search-radius for
  11. a specified latitude and longitude.
  12. location_get_postalcode_data(): A function that takes a (postalcode,country) pair an returns lat/lon, city, province. This
  13. function is meant to replace location_latlon_rough(); see below.
  14. location_latlon_rough(): A function that returns the latitude and longitude of the specified postal-code/country pair.
  15. This latitude and longitude will be of the approximate center of the postal-code's area. This function
  16. will soon be removed from the API as it has been replaced by the more comprehensive
  17. location_get_postalcode_data() described above. [TO BE DEPRECATED]
  18. location_latlon_exact(): A function that returns the latitude and longitude of the given full location. Typically implemented
  19. on top of a web-service. [TO BE IMPLEMENTED]
  20. location_map_link(): A function that returns, based on the site configuration, either NULL or 1 or more deep-links to mapping
  21. web sites for the parameter location array.
  22. location_driving_directions_link(): A function that returns, given 2 locationes, a deep-link to Yahoo! Maps or some other site
  23. that provides driving directions. The site chosen depends on the implementation at the country-level.
  24. location_form(): A function that generates a form for collecting locative information. Depending on the parameters,
  25. it can collect just the postal code and country or a full location or whatever fields are specified
  26. in its parameters.
  27. location_proximity_form(): A function that generates a form for collecting proximity search parameters.
  28. location_valid(): A function for validating locationes. [TO BE SPECIFIED]
  29. theme_location(): A function that takes in an location and themes it. (e.g., $output .= theme('location', $location)).
  30. location_distance_between(): A function that, given a pair of lat/lon pairs, returns the distance between them.
  31. location_form2api(): A function that, given an location submitted via a form generated by location_form, converts the
  32. submitted location into a form to be used by the rest of the API.
  33. location_api2form(): A function that, given an location in the standard array format (see "IMPORTANT NOTES" below)
  34. returns an location in a format that can be passed to location_form in order to render the
  35. form with the appropriate prefilled values.
  36. "[TO BE SPECIFIED]" => Function spec has not been completed and may possibly be eliminated from spec.
  37. "[TO BE IMPLEMENTED]" => Function spec exists but is to be implemented in a future release.
  38. "[TO BE DEPRECATED]" => This function will soon be removed from the API.
  39. ----------------------------------------------
  40. IMPORTANT NOTES:
  41. ----------------
  42. Formats
  43. ---
  44. In the following API, a 'location' is merely an associative array with the following keys:
  45. 'street' => A string for the street portion of an location
  46. 'additional' => A string for the additional street portion of an location
  47. 'province' => An upper-case, standard postal abbreviation of a state/province/territory
  48. 'postal_code' => A string or integer for the postal code
  49. 'country' => The lower-case of the ISO 3166 two-letter alpha code (e.g., 'us' for U.S., 'ca' for Canada).
  50. For locations that are passed to location_form() for the $prefilled_values parameter, the same format applies
  51. except that the 'province' field is the concatenation of the country code, '-', and the province abbreviation.
  52. For example, 'CA' is the value for California for all purposes, but when passing this in a location for prefilled
  53. values, it should be 'us-CA'. There are two functions to help convert back and forth between these formats:
  54. location_form2api() and location_api2form(). These are described further below.
  55. Delegation
  56. ---
  57. With the exception of location_form() and location_proximity_form(), the calls to functions listed here are, in the end,
  58. dispatched to country-specific location libraries which are implemented in country-specific '.inc' files. For example,
  59. location_latlon_rough(), when given a U.S. location, really returns a result that is determined by call to
  60. "location_latlon_rough_us()" which is implemented in the file "location.us.inc".
  61. Current Implementation
  62. ---
  63. Currently, the only country supported is the United States. For the future, however, there will be documentation for how to
  64. implement a country-specific include file that can be plugged into the system to support these calls for new countries. This
  65. scheme will revolve around method signatures for a handful of simple-to-write functions.
  66. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  67. function location_nearby_postalcodes_bylocation($location, $distance, $distance_unit = 'km');
  68. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  69. Takes an location and a distance and returns an array of all postal-codes (from all countries that are supported)
  70. within the specified distance of the specified location.
  71. @param $location
  72. An associative array where
  73. 'street' => the street location
  74. 'additional' => extra street location or building name or hall or something like that.
  75. 'city' => a city name
  76. 'province' => province code as defined by the country specific include file
  77. 'country' => lower-cased two-letter ISO 3166 code (REQUIRED)
  78. 'postal_code' => the postal_code
  79. @param $distance
  80. The number portion of the distance; it is forced to an integer ceiling
  81. @param $distance_unit
  82. The unit of distance being used for the distance being submitted.
  83. Valid arguments for $distance_unit are 'mile' and 'km'. If something other than one of
  84. these unit types is submitted for this argument, it is forced to 'km'.
  85. @return
  86. An array where
  87. -> the keys are a postive integer ranking of the search result's closeness to the parameter $postal_code
  88. with 1 being assigned to the nearest postal code
  89. -> the values are an associative array where
  90. 'postal_code' => A postal code that fell within the search-radius given by $distance and $distance_unit.
  91. 'country' => The two-letter ISO code for the home-country of this particular postal_code search result.
  92. 'city' => The city to which this postal code belongs.
  93. 'province' => The province to which this postal code belongs.
  94. 'lon' => The longitude coordinate of the approximate center of the area covered by 'postal_code'
  95. 'lat' => The latitude coordinate of the approximate center of the area covered by 'postal_code'
  96. 'distance' => The number of 'km's or 'mile's that are between the approximate center of the area of
  97. the $postal_code parameter and that of the 'postal_code' in this subarray
  98. 'distance_unit' => The unit of distance specified by 'scalar'
  99. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  100. function location_nearby_postalcodes_bylatlon($lon, $lat, $distance, $distance_unit = 'km');
  101. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  102. Takes a latitude, longitude, and a distance, and returns all postal_codes within
  103. @param $lon
  104. A floating point of the longitude coordinate of the search point
  105. @param $lat
  106. A floating point of the latitude coordinate of the search point
  107. @param $distance
  108. The number portion of the distance; it is forced to an integer ceiling
  109. @param $distance_unit
  110. The unit of distance being used for the distance being submitted.
  111. Valid arguments for $distance_unit are 'mile' and 'km'. If something other than one of
  112. these unit types is submitted for this argument, it is forced to 'km'.
  113. @return
  114. An array where
  115. -> the keys are a contatenation of the country's ISO code and the postal code. For example, if
  116. one of the search results is for postal code "94803" in the United States, the key is then "us94803"
  117. -> the values are an associative array where
  118. 'postal_code' => A postal code that fell within the search-radius given by $distance and $distance_unit.
  119. 'country' => The two-letter ISO code for the home-country of this particular postal_code search result.
  120. 'lon' => The longitude coordinate of the approximate center of the area covered by 'postal_code'
  121. 'lat' => The latitude coordinate of the approximate center of the area covered by 'postal_code'
  122. 'distance' => The number of 'km's or 'mile's that are between the approximate center of the area of the
  123. $postal_code parameter and that of the 'postal_code' in this array
  124. 'distance_unit' => The unit of distance specified by 'distance'
  125. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  126. function location_get_postalcode_data($location = array()); +
  127. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  128. Takes a location and uses the combination of postal code and country to return an array that gives the
  129. city, province, and lat/lon dat for that postal code.
  130. @param $location
  131. An associative array $location where
  132. 'street' => the street portion of the location
  133. 'additional' => additional street portion of the location
  134. 'province' => the province, state, or territory
  135. 'country' => lower-cased two-letter ISO code (REQUIRED)
  136. 'postal_code' => international postal code (REQUIRED)
  137. @return
  138. NULL if data cannot be found.
  139. Otherwise, an associative array where
  140. 'lat' => is a floating point of the latitude coordinate of this location
  141. 'lon' => is a floating point of the longitude coordinate of this location
  142. 'city' => is a string for the city this postalcode is in (or the most recognized city at the given postal)
  143. 'province' => the province of the given postal code.
  144. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  145. function location_latlon_rough($location = array()); +
  146. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  147. Takes an location and returns a "rough" latitude/longitude pair based on the postal code
  148. data available for the given country.
  149. @param $location
  150. An associative array $location where
  151. 'street' => the street portion of the location
  152. 'additional' => additional street portion of the location
  153. 'province' => the province, state, or territory
  154. 'country' => lower-cased two-letter ISO code (REQUIRED)
  155. 'postal_code' => international postal code (REQUIRED)
  156. @return
  157. NULL if data cannont be found.
  158. Otherwise, an associative array where
  159. 'lat' => is a floating point of the latitude coordinate of this location
  160. 'lon' => is a floating point of the longitude coordinate of this location
  161. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  162. function location_latlon_exact($location = array()); +
  163. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  164. Currently, this is not a priority until there is an implementable use for exact longitude,
  165. latitude coordinates for an location. The idea is that this call will eventually retrieve
  166. information through a web-service. Whereas location_latlon_rough() returns an approximate
  167. lat/lon pair based strictly on the postal code where this lat/lon pair is pulled from a
  168. database table, this function is intended to send the entire location to a web-service and
  169. to retrieve exact lat/lon coordinates.
  170. @param $location
  171. An array where
  172. -> the key values are 'street', 'additional', 'province', 'country', 'postal_code'
  173. -> the values are:
  174. 'street' => the string representing the street location (REQUIRED)
  175. 'additional' => the string representing the additional street location portion in the location form
  176. 'city' => the city name (REQUIRED)
  177. 'province' => the province code defined in the country-specific include file
  178. 'country' => the lower-case of the two-letter ISO code (REQUIRED)
  179. 'postal_code' => the postal-code (REQUIRED)
  180. @return
  181. NULL if the delegated-to function that does the actual look-up does not exist.
  182. If the appropriate function exists, then this function returns an associative array where
  183. 'lon' => A floating point number for the longitude coordinate of the parameter location
  184. 'lat' => A floating point number for the latitude coordinate of the parameter location
  185. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  186. function location_map_link($location = array(), $link_text = 'See map'); +
  187. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  188. Get deep-links to a mapping services such as Yahoo! Maps or MapQuest (actual providers depend on configuration
  189. of location module) given a location. The call is delegated based on the 'country' value in the $location parameter.
  190. @param $location
  191. An associative array where
  192. 'street' => A string representing the street location
  193. 'additional' => A string for any additional portion of the street location
  194. 'city' => A string for the city name
  195. 'province' => The standard postal abbreviation for the province
  196. 'country' => The two-letter ISO code for the country of the location (REQUIRED)
  197. 'postal_code' => The international postal code for the location
  198. @return
  199. NULL if there are not mapping providers configured for the country or if no links could be generated.
  200. A string of the form "See map: Yahoo! Maps, MapQuest" where Yahoo! Maps and Mapquest are links to the
  201. given location and can be replaced with other options (e.g., Google) available in the location module settings.
  202. The idea is to encode the appropriate parameters as HTTP GET variables to the URL.
  203. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  204. function location_driving_directions_link($locationA = array(), $locationB = array(), $link_text = 'Get directions');
  205. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  206. Takes two locationes and tries to return a deep-link to driving directions.
  207. Parameters:
  208. @param $locationA
  209. An associative array that represents an location where
  210. 'street' => the street portions of the location
  211. 'additional' => additional street portion of the location
  212. 'city' => the city name
  213. 'province' => the province, state, or territory
  214. 'country' => lower-cased two-letter ISO code (REQUIRED)
  215. 'postal_code' => the postal code
  216. @param $locationB
  217. An associative array that represents an location in the same way that
  218. parameter $locationA does.
  219. @param $link_text
  220. The text of the HTML link that is to be generated.
  221. @return
  222. A deep-link to driving directions on Yahoo! or some other mapping service, if enough fields are filled in the parameters.
  223. A deep-link to a form for driving directions with information pre-filled if not enough, but some fields are filled in the parameters.
  224. The empty string if no information is provided (or if so little information is provided that there is no function to which to delegate
  225. the call.
  226. We dispatch the call to a country-specific function. The country-specific function, in this case,
  227. will be the one reflected by the country parameter of the first function. We require that
  228. both locationes supplied have a country field at the minimum.
  229. The country-specific functions will ultimately decide, with the parameters given, whether to
  230. to link to a form for driving directions is provided, where this form will be
  231. pre-populated with whatever values were available or whether to link directly to the driving
  232. directions themselves if enough fields are filled for each location.
  233. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  234. function location_form($fields = array(), $prefilled_values = array(), $required_fields = array(), $description = '', $form_name = 'location', $function = NULL);
  235. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  236. Generates a Drupal HTML form for collecting locationes.
  237. @param $fields
  238. An array of values where each value is one of 'street', 'city', 'province', 'postal_code', or 'country'.
  239. The presence of values in this array determines which fields will be served in the location form generated
  240. by a call to this function. If this array is empty, all fields are generated.
  241. @param $prefilled_values
  242. An associative array where
  243. -> Each key is one of the location fields: 'street', 'additional', 'city', 'province', 'postal_code', 'country'
  244. -> Each value is a prefilled value for the given field. ..... ))
  245. @param $required_fields
  246. An array of values that are required. Each string can be one of 'street', 'city', 'postal_code', 'province', or 'country'.
  247. The presence of values in this array determines which fields will be marked as 'required'. Validation (i.e., making sure
  248. a required value is actually filled in is the responsibility of the caller)
  249. @param $description
  250. A text description of specifically what location is being collected by the form to be served.
  251. @param $form_name
  252. An additional parameter to help prevent HTML input name collisions. If the caller is using this
  253. function to generate more than 1 location form on a page, then the generated name for each HTML input's
  254. "name" attribute will go by the value supplied for $form_name. This parameter is defaulted to 'location'
  255. For example, if $form_name == 'xyz' and there is a 'street' field in the form to be served,
  256. the "name" attribute for the HTML will be "edit[xyz][street]"
  257. @param $function
  258. A string that tells location_form() which location API function will be using the location submitted via the
  259. generated form. For example, if $function == 'latlon_rough', then the returned location_form (if it includes
  260. a country field) will only generate a list of countries in the HTML select for which function location_latlon_rough()
  261. is supported. To figure out which countries these are, we check to see which of the configured countries have existing
  262. functions to support the call. In this case, we would check to see if there existed a function called "location_latlon_rough_us()"
  263. before listing the United States in the HTML SELECT for the generated location form. $function is defaulted to NULL.
  264. If $function is NULL, the HTML SELECT that is generated will list all countries.
  265. @return
  266. An location form based on the parameters specified. If the $fields array is empty, then the
  267. function returns a form in which all possible fields are served as optional form items.
  268. EXAMPLES:
  269. -> The following call returns a form that only contains fields for a postal_code and country where
  270. the postal_code is required:
  271. ---
  272. $form = location_form(array('postal_code', 'country'), array(), array('postal_code', 'country'), 'Permanent location')
  273. ---
  274. The form returned by this call is generated with calls to Drupal's 'form_' functions:
  275. $form = form_textfield('Postal Code', 'location][postal_code', '', 64, 64, NULL, NULL, TRUE);
  276. -------------------------------------------------------------------------------------------------
  277. -> The following call returns a form that contains fields for a street, province, and postal_code,
  278. but the street, city, and province fields are optional while postal_code is required:
  279. ---
  280. $form = location_form(array('street', 'city', 'province', 'postal_code'), array(), array('postal_code'));
  281. ---
  282. -> The form returned by this call is generated with the following calls to Drupal's 'form_' functions:
  283. $form = form_textfield('Street', 'location][street', '', 64, 64);
  284. $form .= form_textfield('Additional', 'location][additional', '', 64, 64);
  285. // The 'Additional' field is always and only generated when 'street' is specified as one of the fields.
  286. // The 'Additional' field is always optional whether or not 'Street' is required.
  287. $form .= form_textfield('City', 'location][city', '', 64, 64);
  288. $form .= _location_province_select_options(); // defined below
  289. $form .= form_textfield('Postal Code', 'location][postal_code', '', 64, 64, NULL, NULL, TRUE);
  290. ------------------------------------------------------------------------------------------------
  291. For the following examples, assume we have the following two locationes:
  292. (1) $locationA = ('street' => '2010 Broadway St', 'city' => 'Redwood City', 'province' => 'CA', 'postal_code' => '94063', 'country' => 'us');
  293. (2) $locationB = ('street' => '2010 Broadway St', 'city' => 'Redwood City', 'province' => 'us-CA', 'postal_code' => '94063', 'country' => 'us');
  294. -> The following calls return the exact same form that contains fields for a street, province, postal_code, where prefilled
  295. values are submitted to the form.
  296. $form = location_form(array('street', 'city', 'province', 'postal_code', 'country'), $locationB, array('street', 'city', 'province', 'postal_code', country'), '', 'home_location');
  297. $form = location_form(array('street', 'city', 'province', 'postal_code', 'country'), location_api2form($locationA), array('street', 'city', 'province', 'postal_code', 'country'), '', 'home_location');
  298. -> The form returned by these call is ultimately generated with the following calls to Drupal's 'form_' functions:
  299. $form = textfield('Street', 'home_location][street', '2010 Broadway St.', 64, 64, NULL, NULL, TRUE);
  300. $form .= textfield('Additional', 'home_location][additional', 'Attn: Ankur Rishi', 64, 64, NULL, NULL, TRUE);
  301. $form .= textfield('City', 'home_location][city', 'Redwood City', 64, 64, NULL, NULL, TRUE);
  302. $form .= _location_province_select_options(TRUE, 'us-CA', 'home_location');
  303. $form .= textfield('Postal Code', 'home_location][postal_code', '94063', 64, 64, NULL, NULL, TRUE);
  304. $form .= _location_country_select_options(TRUE, 'us', 'home_location');
  305. Note that in both cases, the first and third argument can take the same array since all the fields are being required.
  306. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  307. function location_proximity_form($location_form = '', $label = '', $description = '', $prefilled_values = array(), $form_name = 'location');
  308. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  309. This function generates a form for doing proximity searches within a certain distance
  310. of a specified point.
  311. Depending on the context within which this function is called, the search-point can either
  312. be user-supplied via the location form that is passed (if one is available) or done within
  313. a search-point extracted from a contact table or some other location source specified by
  314. the programmer calling this function.
  315. @param $location_form
  316. An optional location form, preferably generated by location_form(). If the script processing this
  317. form also needs a user-supplied location, this parameter is used to specify a form for collecting the
  318. search-point about which this search is being done. If the caller does not supply a form, it is
  319. assumed that the caller already has a search point in mind and that this will be made clear in
  320. the $description parameter.
  321. @param $label
  322. The label you want to apply to the form group that is returned (passed as $legend param to form_group()).
  323. @param $description
  324. A text description of what is being searched for (e.g., 'Find all upcoming events near you.')
  325. @param $prefilled_values
  326. An associative array for prefilled values for the proximity search parameters, where
  327. 'distance' => is the prefilled int value to be selected for the distance scalar
  328. 'distance_unit' => is 'km' or 'mile'
  329. @param $form_name
  330. An additional parameter to help prevent HTML input name collisions. If the caller is using this
  331. function to generate more than 1 location proximity form on a page, then the generated name for
  332. each HTML input's "name" attribute will be $form_name. Allowing the caller to pass $form_name allows
  333. the caller the flexibility of using more than one location proximity search form on one page.
  334. @return
  335. An HTML form (generated by Drupal form functions) that lets users specify proximity search parameters that include distance,
  336. the unit of distance, and a search-point if the optional $location_form parameter is passed. If one is not passed,
  337. the caller of this function will be assumed to already have one.
  338. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  339. function theme_location($location = array()); +
  340. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  341. Generates HTML for the passed location.
  342. @param $location
  343. An associative array where
  344. 'street' => A string representing the street location
  345. 'additional' => A string for any additional portion of the street location
  346. 'city' => A string for the city name
  347. 'province' => The standard postal abbreviation for the province
  348. 'country' => The two-letter ISO code for the country of the location (REQUIRED)
  349. 'postal_code' => The international postal code for the location
  350. @return
  351. An HTML string with special tags for locationes.
  352. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  353. function location_distance_between($latlonA = array(), $latlonB = array(), $distance_unit = 'km'); +
  354. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  355. Given two points in lat/lon form, returns the distance between them.
  356. @param $latlonA
  357. An associative array where
  358. 'lon' => is a floating point of the longitude coordinate for the point given by latlonA
  359. 'lat' => is a floating point of the latitude coordinate for the point given by latlonB
  360. @param $latlonB
  361. Another point formatted like $latlonB
  362. @param $distance_unit
  363. A string that is either 'km' or 'mile'.
  364. If neither 'km' or 'mile' is passed, the parameter is forced to 'km'
  365. @return
  366. NULL if sense can't be made of the parameters.
  367. An associative array where
  368. 'scalar' => Is the distance between the two lat/lon parameter points
  369. 'distance_unit' => Is the unit of distance being represented by 'scalar'.
  370. This will be 'km' unless 'mile' is passed for the $distance_unit param
  371. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  372. function location_form2api($location = array()); +
  373. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  374. @param $location
  375. An associative array that has been submitted by an HTML form generated by location_form().
  376. @return
  377. An associative array in which the submitted values are modified to pass to the location API
  378. as the $location parameter (excepting location_form()).
  379. This means changing the province field to remove the country code and dash.
  380. For example: California is served by the key 'us-CA' in the location form and this is what is passed when it is
  381. submitted through a form generated by location_form().
  382. This is changed to 'CA' in the returned array.
  383. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  384. function location_api2form($location = array()); +
  385. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  386. Inverse of location_form2api()
  387. @param $location
  388. An associative array that can be passed as the $location parameter to the location API.
  389. @return
  390. An associative array with the same values modified so that the array can be passed as the
  391. $prefilled_values parameter to location_api2form()
  392. Meant to take the standard location array format used by the public API (minus the form generating functions) and convert them
  393. into values that can be used by location_form() to fill in the prefilled values.