265 lines
15 KiB
HTML
265 lines
15 KiB
HTML
|
|
<p><em>Note:</em> This file describes the original country API. While the API itself hasn't
|
|
changed, some things have moved in directions not forseen by this documentation.
|
|
For example, there is less emphasis today on postal data and more emphasis on
|
|
geocoding webservices. Please take this documentation with a grain of salt until
|
|
it is fully cleaned up and brought up to date.</p>
|
|
|
|
<h3>location.xx.inc: Adding support for an unsupported country</h3>
|
|
<hr />
|
|
|
|
<p>This file is a PHP programmer's description of what needs to be done in order to extend the
|
|
location system to support locationes from a new country.</p>
|
|
|
|
<p>Let's suppose we want to extend the location system to support locationes from Belgium. To this end,
|
|
there are 2 tasks:</p>
|
|
|
|
TASK #1
|
|
<p>We use the lower-case of the country's two-letter ISO 3166 code to create a file, "location.be.inc", that
|
|
defines the necessary functions that will "hook" into the location system. This way, when a high-level
|
|
function in the public location API receives a call that uses some Belgium specific function, the call
|
|
will be delegated to the appropriately named function in "location.be.inc".</p>
|
|
|
|
TASK #2
|
|
<p>You need postal code data for your country. This postal code data needs to be able to connect the
|
|
base-length postal code (e.g., U.S. postal codes can be 9 digits, but we're only interested to the
|
|
level of 5 digits and most people only know the 5-digit version) to a city, province/state, country (duh),
|
|
and a latitude/longitude pair in degrees that represents the approximate center of the postal code's area.
|
|
Ultimately, you will want to create a database dump that inserts these fields into specific columns:
|
|
'zip' (for postal codes), 'city' (for city names), 'province' for (the standard state/province/country
|
|
abbreviation), 'country' (for the lower-case of the country's two letter ISO code), 'latitude' (for the
|
|
latitude in degree value, as opposed to radian value) and 'longitude' (for the degree value of the
|
|
longitude).</p>
|
|
|
|
<p>In a lot of countries, this data costs money! You cannot simply create a dump and then publish it on
|
|
drupal.org unless the data is free to redistribute. However, if you are interested in buying this data
|
|
from some vendor and using it on your own site, you can do so but may have to acquire a new license for
|
|
each seperate business or web site for which you wish to use postal code data if, in fact, you had to
|
|
pay a fee or license for this data.</p>
|
|
|
|
<p>This postalcode-to-lat/lon mapping is important if you want to enable location-based proximity searches of
|
|
anykind for addresses in a particular country. The module will still work fine without it, but will not
|
|
be able to support searches based on postal codes.</p>
|
|
|
|
<h3>Contents of location.be.inc</h3>
|
|
<hr />
|
|
<p>This file will need to implement a handful of functions with the parameters and return values described below.</p>
|
|
|
|
<p>It is possible to not implement all of these functions since the caller usually checks to see if the function
|
|
exists before calling it, but it may limit the number of features the location system will be able to support
|
|
for your country.</p>
|
|
|
|
<p>For an example implementation of the functions described below, see "supported/location.us.inc".</p>
|
|
|
|
<pre>
|
|
-------------------------------------------------------------------------------------------------
|
|
function theme_location_be($location, $hide); |
|
|
-------------------------------------------------------------------------------------------------
|
|
@param $location
|
|
An associative array $location where
|
|
'street' => the street portion of the location
|
|
'additional' => additional street portion of the location
|
|
'city' => the city of the location
|
|
'province' => the province, state, or territory
|
|
'country' => lower-cased two-letter ISO code (REQUIRED)
|
|
'postal_code' => the international postal code for this location (REQUIRED)
|
|
@param $hide
|
|
An linear array where the values are the location fields to suppress in the themed display.
|
|
@return
|
|
A string of the themed location. The entire location should be enclosed by <dl class="location"> </dl> tags.
|
|
The different lines of the location should be enclosed by <dl> </dl> tags. The idea is to allow country-specific
|
|
files to change the display of an location from the default theming done in theme_location() defined in location.inc
|
|
</pre>
|
|
|
|
<pre>
|
|
-------------------------------------------------------------------------------------------------
|
|
function location_province_list_be(); |
|
|
-------------------------------------------------------------------------------------------------
|
|
Returns an associative array where
|
|
-> the keys are the all-uppercase standard postal abbreviation for provinces, territories, and like subdivisions.
|
|
-> the values are the fully spelled names of the abbreviated names.
|
|
|
|
Preferrably, these will be sorted by the full name.
|
|
</pre>
|
|
|
|
<pre>
|
|
-------------------------------------------------------------------------------------------------
|
|
function location_map_link_be($location); |
|
|
-------------------------------------------------------------------------------------------------
|
|
Returns a deep-link to an online mapping service (e.g., "Yahoo! Maps", "MapQuest", or some other
|
|
preferrably free service) given a full/partial location in the format described in public API
|
|
document (location_API.txt).
|
|
|
|
@param $location
|
|
An associative array $location where
|
|
'street' => the street portion of the location
|
|
'additional' => additional street portion of the location
|
|
'city' => the city of the location
|
|
'province' => the province, state, or territory
|
|
'country' => lower-cased two-letter ISO code (REQUIRED)
|
|
'postal_code' => the international postal code for this location (REQUIRED)
|
|
|
|
@return
|
|
A URL with encoded HTTP GET variables to a free online-mapping service. (Note: URL, not HTML link).
|
|
NULL if there is not even enough information to generate even a semi-useful link. "Useful" may depend
|
|
entirely on the mapping service you choose to link to. You are advised to experiment: usually, a
|
|
city/province combination is enough as is a postal code by itself, however, some services get confused
|
|
when all fields are supplied. Some mapping services will be unable to map a city/province location
|
|
while they can't do anything with a postal code while others map postal codes fine, but can't do
|
|
anything useful with a city/province pair.
|
|
</pre>
|
|
|
|
<pre>
|
|
--------------------------------------------------------------------------------------------------
|
|
function location_map_link_be_providers(); |
|
|
--------------------------------------------------------------------------------------------------
|
|
Returns an array of mapping services to which the generation of deep-links is supported. "Supported"
|
|
means that the function for that particular mapping service has been defined. For example, if the
|
|
location.be.inc file for Belgium has functions for taking a location and generating a deep-link to
|
|
Yahoo! Maps and google, this function will return that list in an array that give additional info.
|
|
|
|
See location.us.inc for an example.
|
|
|
|
@return
|
|
An associative array where
|
|
--> The keys are single words (no spaces) that identify a function in the same file for returning
|
|
a deep link. For example, 'yahoo' means location_map_link_be_yahoo(). 'google' means
|
|
location_map_link_be_google().
|
|
--> The values are themselves associative arrays with 3 expected keys:
|
|
'name' => The name of the mapping service. In the case of Yahoo, it would be 'Yahoo! Maps'
|
|
'url' => The full URL of the main page of the mapping service (i.e., the home page)
|
|
'tos' => The full URL of the Terms Of Service for the mapping service.
|
|
</pre>
|
|
|
|
<pre>
|
|
--------------------------------------------------------------------------------------------------
|
|
function location_map_link_be_default_providers(); |
|
|
--------------------------------------------------------------------------------------------------
|
|
Returns an array of 'default' mapping services. It may happen that the site administrator has not
|
|
yet made it to the settings page for selecting mapping providers. In this case, we want to tell
|
|
the location modules which one to use as defaults. To help the site admin avoid being in violation
|
|
of each mapping services's Terms of Service, we return a linear array whose values are the appropriately
|
|
selected keys in the array returned the location_map_link_xx_providers() function.
|
|
|
|
@return
|
|
A linear array with the one-word, no-spaced identifiers used to identify the mapping function. These
|
|
should only be for the mapping services with relatively lenient and permissive Terms of Service.
|
|
|
|
|
|
IMPORTANT: For more information on how to add support for deep-links, you are encouraged to see
|
|
the examples in modules/location/supported/location.us.inc. If you need extra help, please feel
|
|
free to submit a question on the issues queue for this project at: http://drupal.org/project/issues/location
|
|
Replies will be prompt.
|
|
</pre>
|
|
|
|
<pre>
|
|
--------------------------------------------------------------------------------------------------
|
|
function location_driving_directions_link_be($locationA, $locationB); |
|
|
--------------------------------------------------------------------------------------------------
|
|
Returns a deep-link to an online mapping service (e.g., "Yahoo! Maps", "MapQuest", or some other
|
|
preferrably free service) given full/partial locationes. Depending on whether or not the parameter
|
|
locationes are complete enough for the chosen service, this function will return either a deep-link
|
|
directly to the driving direction or will provide a deep-link to a partially pre-filled form for
|
|
driving directions on the site you choose to link to.
|
|
|
|
@param $locationA
|
|
An associative array $location where
|
|
'street' => the street portion of the location
|
|
'additional' => additional street portion of the location
|
|
'city' => the city of the location
|
|
'province' => the province, state, or territory
|
|
'country' => lower-cased two-letter ISO code (REQUIRED)
|
|
'postal_code' => the international postal code for this location (REQUIRED)
|
|
|
|
@param $locationB
|
|
An associative array $location where
|
|
'street' => the street portion of the location
|
|
'additional' => additional street portion of the location
|
|
'city' => the city of the location
|
|
'province' => the province, state, or territory
|
|
'country' => lower-cased two-letter ISO code (REQUIRED)
|
|
'postal_code' => the international postal code for this location (REQUIRED)
|
|
|
|
@return
|
|
A URL (not HTML link) with HTTP GET variables tacked on to the end. This URL either points to a
|
|
form for driving directions from $locationA to $locationB or a deep-link directly to the driving
|
|
directions depending on how complete the locationes are.
|
|
</pre>
|
|
|
|
<pre>
|
|
--------------------------------------------------------------------------------------------------
|
|
function location_get_postalcode_data_be($location = array()); |
|
|
--------------------------------------------------------------------------------------------------
|
|
@param $location
|
|
An associative array $location where
|
|
'street' => the street portion of the location
|
|
'additional' => additional street portion of the location
|
|
'city' => the city of the location
|
|
'province' => the province, state, or territory
|
|
'country' => lower-cased two-letter ISO code (REQUIRED)
|
|
'postal_code' => the international postal code for this location (REQUIRED)
|
|
|
|
@return
|
|
An associative array where
|
|
'lat' => A floating point for the latitude of the approximate center of the postal_code in the given $location
|
|
'lon' => A floating point for the longitude of the approximate center of the postal code in the given $location
|
|
'city' => The most appropriate city name for the given postal code in $location
|
|
'province' => The most appropriate province name for the given postal code in $location
|
|
Returns NULL if the postal code doesn't make sense.
|
|
|
|
Typically, this function will pull out the latitude/longitude of the approximate center of postal code
|
|
in the given $location parameter as well as other data. The reason this can't be implemented at the
|
|
non-country specific level in location.inc is that postal codes may be submitted in varying formats
|
|
of varying precision while postal codes for this country in the database table may all be in a particular
|
|
format. It is up to this country specific function to examine $location['postal_code'] and format it
|
|
appropriately so that it matches with a postal code in the postal codes table. This 'hook' is meant
|
|
to be a replacement for the location_get_latlon_rough_xx hook, described next.
|
|
</pre>
|
|
|
|
<pre>
|
|
--------------------------------------------------------------------------------------------------
|
|
function location_latlon_rough_be($location = array()); |
|
|
--------------------------------------------------------------------------------------------------
|
|
@param $location
|
|
An associative array $location where
|
|
'street' => the street portion of the location
|
|
'additional' => additional street portion of the location
|
|
'city' => the city of the location
|
|
'province' => the province, state, or territory
|
|
'country' => lower-cased two-letter ISO code (REQUIRED)
|
|
'postal_code' => the international postal code for this location (REQUIRED)
|
|
|
|
@return
|
|
An associative array where
|
|
'lat' => A floating point for the latitude of the approximate center of the postal_code in the given $location
|
|
'lon' => A floating point for the longitude of the approximate center of the postal code in the given $location
|
|
Returns NULL if the postal code doesn't make sense.
|
|
|
|
Typically, this function will pull out the latitude/longitude of the approximate center of postal code
|
|
in the given $location parameter.
|
|
</pre>
|
|
|
|
<pre>
|
|
--------------------------------------------------------------------------------------------------
|
|
function location_latlon_exact_be($location = array()); |
|
|
--------------------------------------------------------------------------------------------------
|
|
@param $location
|
|
An associative array $location where
|
|
'street' => the street portion of the location
|
|
'additional' => additional street portion of the location
|
|
'city' => the city of the location
|
|
'province' => the province, state, or territory
|
|
'country' => lower-cased two-letter ISO code (REQUIRED)
|
|
'postal_code' => the international postal code for this location (REQUIRED)
|
|
|
|
@return
|
|
An associative array where
|
|
'lat' => A floating point for the latitude of the approximate center of the postal_code in the given $location
|
|
'lon' => A floating point for the longitude of the approximate center of the postal code in the given $location
|
|
Returns NULL if the postal code doesn't make sense.
|
|
|
|
Typically, this function will be implemented on top of a web-service for retrieving exact lat/lon information
|
|
for a full location. This function is not a necessity, but a sample implementation would be helpful for
|
|
future users. If not, it can always be added on a supply and demand basis.
|
|
</pre>
|