 country api 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 locationxxinc 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 lowercase of the country s twoletter iso 3166 code to create a file locationbeinc that defines the necessary functions that will hook into the location system this way when a highlevel 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 locationbeinc task 2 you need postal code data for your country this postal code data needs to be able to connect the baselength postal code eg us postal codes can be 9 digits but we re only interested to the level of 5 digits and most people only know the 5digit 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 lowercase 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 drupalorg 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 postalcodetolat lon mapping is important if you want to enable locationbased 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 locationbeinc 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 locationusinc function themelocationbe 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 lowercased twoletter iso code required postalcode 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 countryspecific files to change the display of an location from the default theming done in themelocation defined in locationinc function locationprovincelistbe returns an associative array where the keys are the alluppercase 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 locationmaplinkbe location returns a deeplink to an online mapping service eg yahoo maps mapquest or some other preferrably free service given a full partial location in the format described in public api document locationapitxt 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 lowercased twoletter iso code required postalcode the international postal code for this location required return a url with encoded http get variables to a free onlinemapping service note url not html link null if there is not even enough information to generate even a semiuseful 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 locationmaplinkbeproviders returns an array of mapping services to which the generation of deeplinks is supported supported means that the function for that particular mapping service has been defined for example if the locationbeinc file for belgium has functions for taking a location and generating a deeplink to yahoo maps and google this function will return that list in an array that give additional info see locationusinc 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 locationmaplinkbeyahoo google means locationmaplinkbegoogle 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 ie the home page tos the full url of the terms of service for the mapping service function locationmaplinkbedefaultproviders 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 locationmaplinkxxproviders function return a linear array with the oneword nospaced 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 deeplinks you are encouraged to see the examples in modules location supported locationusinc if you need extra help please feel free to submit a question on the issues queue for this project at http drupalorg project issues location replies will be prompt function locationdrivingdirectionslinkbe locationa locationb returns a deeplink to an online mapping service eg 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 deeplink directly to the driving direction or will provide a deeplink to a partially prefilled 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 lowercased twoletter iso code required postalcode 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 lowercased twoletter iso code required postalcode 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 deeplink directly to the driving directions depending on how complete the locationes are function locationgetpostalcodedatabe 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 lowercased twoletter iso code required postalcode 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 postalcode 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 noncountry specific level in locationinc 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 postalcode 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 locationgetlatlonroughxx hook described next function locationlatlonroughbe 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 lowercased twoletter iso code required postalcode 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 postalcode 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 locationlatlonexactbe 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 lowercased twoletter iso code required postalcode 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 postalcode 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 webservice 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  