modules/location/location_API.txt

$Id: location_API.txt,v 1.9 2008/01/24 09:23:14 bdragon Exp $

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
1	$Id: location_API.txt,v 1.9 2008/01/24 09:23:14 bdragon Exp $
2
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
6	For a example of this API's usage, please consult "location.module"
7
8
9	FUNCTION SPECIFICATIONS DESCRIBED IN THIS FILE:
10	----------------------------------------------
11	location_get_postalcode_data(): A function that takes a (postalcode,country) pair an returns lat/lon, city, province. This
12	function is meant to replace location_latlon_rough(); see below.
13
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
19	location_latlon_exact(): A function that returns the latitude and longitude of the given full location. Typically implemented
20	on top of a web-service. [TO BE IMPLEMENTED]
21
22	location_map_link(): A function that returns, based on the site configuration, either NULL or 1 or more deep-links to mapping
23	web sites for the parameter location array.
24
25	location_driving_directions_link(): A function that returns, given 2 locationes, a deep-link to Yahoo! Maps or some other site
26	that provides driving directions. The site chosen depends on the implementation at the country-level.
27
28	location_proximity_form(): A function that generates a form for collecting proximity search parameters.
29
30	location_valid(): A function for validating locationes. [TO BE SPECIFIED]
31
32	theme_location(): A function that takes in an location and themes it. (e.g., $output .= theme('location', $location)).
33
34	location_distance_between(): A function that, given a pair of lat/lon pairs, returns the distance between them.
35
36
37	"[TO BE SPECIFIED]" => Function spec has not been completed and may possibly be eliminated from spec.
38	"[TO BE IMPLEMENTED]" => Function spec exists but is to be implemented in a future release.
39	"[TO BE DEPRECATED]" => This function will soon be removed from the API.
40	----------------------------------------------
41
42
43
44	IMPORTANT NOTES:
45	----------------
46	Formats
47	---
48	In the following API, a 'location' is merely an associative array with the following keys:
49	'street' => A string for the street portion of an location
50	'additional' => A string for the additional street portion of an location
51	'province' => An upper-case, standard postal abbreviation of a state/province/territory
52	'postal_code' => A string or integer for the postal code
53	'country' => The lower-case of the ISO 3166 two-letter alpha code (e.g., 'us' for U.S., 'ca' for Canada).
54
55	For locations that are passed to location_form() for the $prefilled_values parameter, the same format applies
56	except that the 'province' field is the concatenation of the country code, '-', and the province abbreviation.
57	For example, 'CA' is the value for California for all purposes, but when passing this in a location for prefilled
58	values, it should be 'us-CA'. There are two functions to help convert back and forth between these formats:
59	location_form2api() and location_api2form(). These are described further below.
60
61	Delegation
62	---
63	With the exception of location_form() and location_proximity_form(), the calls to functions listed here are, in the end,
64	dispatched to country-specific location libraries which are implemented in country-specific '.inc' files. For example,
65	location_latlon_rough(), when given a U.S. location, really returns a result that is determined by call to
66	"location_latlon_rough_us()" which is implemented in the file "location.us.inc".
67
68	Current Implementation
69	---
70	Currently, the only country supported is the United States. For the future, however, there will be documentation for how to
71	implement a country-specific include file that can be plugged into the system to support these calls for new countries. This
72	scheme will revolve around method signatures for a handful of simple-to-write functions.
73
74	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
75	function location_get_postalcode_data($location = array()); +
76	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
77	Takes a location and uses the combination of postal code and country to return an array that gives the
78	city, province, and lat/lon dat for that postal code.
79
80	@param $location
81	An associative array $location where
82	'street' => the street portion of the location
83	'additional' => additional street portion of the location
84	'province' => the province, state, or territory
85	'country' => lower-cased two-letter ISO code (REQUIRED)
86	'postal_code' => international postal code (REQUIRED)
87
88	@return
89	NULL if data cannot be found.
90	Otherwise, an associative array where
91	'lat' => is a floating point of the latitude coordinate of this location
92	'lon' => is a floating point of the longitude coordinate of this location
93	'city' => is a string for the city this postalcode is in (or the most recognized city at the given postal)
94	'province' => the province of the given postal code.
95
96	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
97	function location_latlon_rough($location = array()); +
98	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
99
100	Takes an location and returns a "rough" latitude/longitude pair based on the postal code
101	data available for the given country.
102
103	@param $location
104	An associative array $location where
105	'street' => the street portion of the location
106	'additional' => additional street portion of the location
107	'province' => the province, state, or territory
108	'country' => lower-cased two-letter ISO code (REQUIRED)
109	'postal_code' => international postal code (REQUIRED)
110
111	@return
112	NULL if data cannont be found.
113	Otherwise, an associative array where
114	'lat' => is a floating point of the latitude coordinate of this location
115	'lon' => is a floating point of the longitude coordinate of this location
116
117
118
119
120
121	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
122	function location_latlon_exact($location = array()); +
123	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
124	Currently, this is not a priority until there is an implementable use for exact longitude,
125	latitude coordinates for an location. The idea is that this call will eventually retrieve
126	information through a web-service. Whereas location_latlon_rough() returns an approximate
127	lat/lon pair based strictly on the postal code where this lat/lon pair is pulled from a
128	database table, this function is intended to send the entire location to a web-service and
129	to retrieve exact lat/lon coordinates.
130
131	@param $location
132	An array where
133	-> the key values are 'street', 'additional', 'province', 'country', 'postal_code'
134	-> the values are:
135	'street' => the string representing the street location (REQUIRED)
136	'additional' => the string representing the additional street location portion in the location form
137	'city' => the city name (REQUIRED)
138	'province' => the province code defined in the country-specific include file
139	'country' => the lower-case of the two-letter ISO code (REQUIRED)
140	'postal_code' => the postal-code (REQUIRED)
141
142	@return
143	NULL if the delegated-to function that does the actual look-up does not exist.
144	If the appropriate function exists, then this function returns an associative array where
145	'lon' => A floating point number for the longitude coordinate of the parameter location
146	'lat' => A floating point number for the latitude coordinate of the parameter location
147
148
149
150
151
152
153	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
154	function location_map_link($location = array(), $link_text = 'See map'); +
155	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
156	Get deep-links to a mapping services such as Yahoo! Maps or MapQuest (actual providers depend on configuration
157	of location module) given a location. The call is delegated based on the 'country' value in the $location parameter.
158
159	@param $location
160	An associative array where
161	'street' => A string representing the street location
162	'additional' => A string for any additional portion of the street location
163	'city' => A string for the city name
164	'province' => The standard postal abbreviation for the province
165	'country' => The two-letter ISO code for the country of the location (REQUIRED)
166	'postal_code' => The international postal code for the location
167
168	@return
169	NULL if there are not mapping providers configured for the country or if no links could be generated.
170	A string of the form "See map: Yahoo! Maps, MapQuest" where Yahoo! Maps and Mapquest are links to the
171	given location and can be replaced with other options (e.g., Google) available in the location module settings.
172	The idea is to encode the appropriate parameters as HTTP GET variables to the URL.
173
174
175
176
177
178	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
179	function location_driving_directions_link($locationA = array(), $locationB = array(), $link_text = 'Get directions');
180	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
181	Takes two locationes and tries to return a deep-link to driving directions.
182
183	Parameters:
184	@param $locationA
185	An associative array that represents an location where
186	'street' => the street portions of the location
187	'additional' => additional street portion of the location
188	'city' => the city name
189	'province' => the province, state, or territory
190	'country' => lower-cased two-letter ISO code (REQUIRED)
191	'postal_code' => the postal code
192
193	@param $locationB
194	An associative array that represents an location in the same way that
195	parameter $locationA does.
196
197	@param $link_text
198	The text of the HTML link that is to be generated.
199
200	@return
201	A deep-link to driving directions on Yahoo! or some other mapping service, if enough fields are filled in the parameters.
202	A deep-link to a form for driving directions with information pre-filled if not enough, but some fields are filled in the parameters.
203	The empty string if no information is provided (or if so little information is provided that there is no function to which to delegate
204	the call.
205
206	We dispatch the call to a country-specific function. The country-specific function, in this case,
207	will be the one reflected by the country parameter of the first function. We require that
208	both locationes supplied have a country field at the minimum.
209
210	The country-specific functions will ultimately decide, with the parameters given, whether to
211	to link to a form for driving directions is provided, where this form will be
212	pre-populated with whatever values were available or whether to link directly to the driving
213	directions themselves if enough fields are filled for each location.
214
215
216	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
217	function location_proximity_form($location_form = '', $label = '', $description = '', $prefilled_values = array(), $form_name = 'location');
218	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
219	This function generates a form for doing proximity searches within a certain distance
220	of a specified point.
221
222	Depending on the context within which this function is called, the search-point can either
223	be user-supplied via the location form that is passed (if one is available) or done within
224	a search-point extracted from a contact table or some other location source specified by
225	the programmer calling this function.
226
227	@param $location_form
228	An optional location form, preferably generated by location_form(). If the script processing this
229	form also needs a user-supplied location, this parameter is used to specify a form for collecting the
230	search-point about which this search is being done. If the caller does not supply a form, it is
231	assumed that the caller already has a search point in mind and that this will be made clear in
232	the $description parameter.
233
234	@param $label
235	The label you want to apply to the form group that is returned (passed as $legend param to form_group()).
236
237	@param $description
238	A text description of what is being searched for (e.g., 'Find all upcoming events near you.')
239
240	@param $prefilled_values
241	An associative array for prefilled values for the proximity search parameters, where
242	'distance' => is the prefilled int value to be selected for the distance scalar
243	'distance_unit' => is 'km' or 'mile'
244
245	@param $form_name
246	An additional parameter to help prevent HTML input name collisions. If the caller is using this
247	function to generate more than 1 location proximity form on a page, then the generated name for
248	each HTML input's "name" attribute will be $form_name. Allowing the caller to pass $form_name allows
249	the caller the flexibility of using more than one location proximity search form on one page.
250
251	@return
252	An HTML form (generated by Drupal form functions) that lets users specify proximity search parameters that include distance,
253	the unit of distance, and a search-point if the optional $location_form parameter is passed. If one is not passed,
254	the caller of this function will be assumed to already have one.
255
256
257
258
259
260
261	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
262	function theme_location($location = array()); +
263	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
264	Generates HTML for the passed location.
265
266	@param $location
267	An associative array where
268	'street' => A string representing the street location
269	'additional' => A string for any additional portion of the street location
270	'city' => A string for the city name
271	'province' => The standard postal abbreviation for the province
272	'country' => The two-letter ISO code for the country of the location (REQUIRED)
273	'postal_code' => The international postal code for the location
274
275	@return
276	An HTML string with special tags for locationes.
277
278
279
280
281
282	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
283	function location_distance_between($latlonA = array(), $latlonB = array(), $distance_unit = 'km'); +
284	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
285	Given two points in lat/lon form, returns the distance between them.
286
287	@param $latlonA
288	An associative array where
289	'lon' => is a floating point of the longitude coordinate for the point given by latlonA
290	'lat' => is a floating point of the latitude coordinate for the point given by latlonB
291
292	@param $latlonB
293	Another point formatted like $latlonB
294
295	@param $distance_unit
296	A string that is either 'km' or 'mile'.
297	If neither 'km' or 'mile' is passed, the parameter is forced to 'km'
298
299	@return
300	NULL if sense can't be made of the parameters.
301	An associative array where
302	'scalar' => Is the distance between the two lat/lon parameter points
303	'distance_unit' => Is the unit of distance being represented by 'scalar'.
304	This will be 'km' unless 'mile' is passed for the $distance_unit param