Note: 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.

### location.xx.inc: Adding support for an unsupported country

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.

Let's suppose we want to extend the location system to support locationes from Belgium. To this end, there are 2 tasks:

TASK #1

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".

TASK #2

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).

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.

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.

### Contents of location.be.inc

This file will need to implement a handful of functions with the parameters and return values described below.

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.

For an example implementation of the functions described below, see "supported/location.us.inc".

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

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

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

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

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

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

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

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

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