The „Autocomplete Location“ documentation

This is documentation complements the add-on description on XF.com and the hints on the options page by providiong more (in-depth) information.

Content


Location terminology

City a populated place such as a city or a village
State synonymous with „first-level administrative division“. For example, a „state“ in the United States or a „province“ in Canada
Country an independent political entity such as the United States or Germany.

Custom user fields

The add-on creates several custom user fields in which atomic location data will be saved, if the corresponding option is enabled (see the corresponding option for more info). Note that during uninstallation none of the custom fields will be removed. This is to prevent accidental (massive) data loss. But you can of course remove the fields manually like all the other custom user fields. But keep in mind that not only the field itself will be removed but also all associated data!

If you think you do not need certain fields. you can delete any of the custom user fields. However, I strongly recommend that you very carefully think about potential drawbacks before removing any of these fields. It is of course pretty easy to recreate any of these fields at a later time. However, it isn't the field itself but the data that is saved in a field that is valuable. For example, you decide to delete the „City“ field and notice one year later that (now) it would be actually very useful to have it. So you create this field again either manually or with the add-on installer. Now each user has a „City“ user field. But the big problem is that there are no field values for all users that stated their location during the last year.

Locations in the United Kingdom

The actual first-level administrative divisions in the UK are England, Northern Ireland, Scotland and Wales. However, for the „Location“ field the „country“ becomes the first-level admin division and the first- becomes the second-level admin division. So e.g. instead of „London (England, United Kingdom“ it will show „London (Greater London, England). However, this applies only for the autocomplete list and the value that is inserted in the „Location“ field. There are no changes regarding the atomic names (if saved). Please note, that the nine regions of England are not included in the Geonames database and are therefore also not considered as first-level admin divisions.

Free and Premium Servers

Comparison table of free and premium servers

Note: These statistics are derived from my own data that was gathered between 1st January and 7th March 2016 with a frequency of 1 request per minute for each server type.


Availability
The „Availability“ represents the percentage of successful requests. A request is considered as „unsuccessful“ if it took longer than 2500 milliseconds or if the server replied with an error. Note that, 2.5 seconds may seem not very much. However, in a realtime context such as an autocomplete list where a very high responsiveness is desirable, it is actually a very long time.

Average processing time
This number is the average time needed by a Geonames server to successfully process a request. The lower the processing time, the faster the autocomplete lists updates.

Server locations
The farther your server (if ACL is in „server mode“) or your user (if ACL is in „client mode“) is away from the Geonames server, the longer it takes to send and receive requests. Note that this is independent of the processing time.

Availability
As you can see on the above comparison the free servers do not support secure sites (HTTPS). Fortunately you can still use this add-on on secure sites with free servers if you set the „Geonames caller“ to „Server“. However, in this case the autocomplete list will update somewhat slower as the Geoname requests will have to make detour(s) through your server.

Access to premium servers

If you would like to use the premium servers please have a look at the Geonames Premium Webservice page.

My recommendation

If you are going to use this add-on as an optional usability improvement, then the free servers are probably sufficient. Users will then also be able to enter a location even if the autocomplete list updates very slowly or not at all. However, if you configure the add-on so that users will have to select a location from the autocomplete list, I recommend to use the premium servers, especially if the location field is a required field on the sign-up page.

Options

Hint: If you change any option and if you have an open tab that contains the „Location“ input field, make sure to refresh/reload this tab before testing the new behaviour.

Geonames server type

This determines which kind of the Geonames webservice the add-on is supposed to use. If you choose one the the premium types, the account that is specified in the next option also has to be a Geonames premium account.

Geonames username

This is the username of the Geonames account that will be used to send/receive requests to/from the Geonamnes webservice. The add-on's default account is „awedo_aclocation“. Each free account has a daily limit of 30,000 and an hourly limit of 2,000 lookups. This should actually be sufficient. But if you want to be on the safe side you can create your own Geonames account. Please note that after creating an account you will have to enable it for the webservice on your account page: geonames screenshot

Save atomic location data in custom user fields

During the add-on installation several custom user fields are created to save location data. For example, there are fields for the state and country code of the location that is associated with a particular user. The data of these fields is used for example to build shortened location names for the user info besides a post. But this is not the only possible use case. You can of course also use these fields in any template. Note that this option requires Services_Geonmaes.

Important note regarding atomic names language

You should be very careful with changing the language setting of the atomic location names. The problem with changing the language after (a significant amount of) atomic location names were saved, is that it will be very likely result in data inconsistencies.

For example, if you set the language to „EN“ and a user chooses a location in Germany, the corresponding custom user field will contain „Germany“. Now if you decide to change the language to „DE“ (German) the country field of the next user that chooses a German location will contain „Deutschland“ (the German name for „Germany“). So now there are two users that are located in the same country but have different values in the country field (and possibly also other fields).

Now, you may think that this would be just a blemish as most of your (in this case German users) would know that „Germany“ and „Deutschland“ is the same country. And you may be actually right (for now). However, this can change in the future! The problem is that for example a future add-on that implements a „user location search“ could make use of the atomic data. And this add-on could assume that different values for any atomic location field implies different locations. So the add-on would treat „Germany“ and „Deutschland“ as two different locations which is course not the case. You would then had to manually edit all corresponding fields with the location in the right language. For a few users that would probably not be a big deal. But if there were a lot of users, this could become a very boring, time-consuming and error-prone task. So choose very wisely the language you think is the most appropriate for your atomic location names!

Location names language

This option affects only locations shown on the autocomplete list and the „Location“ input field. The user's language is the language that the user chose in their profile. In case of a unregistered user this is the same as the forum's default language. The specified language determines in which language the additional location names (state and/or country) will be shown if these are available in the corresponding language.

Here's an example with English and German language setting:

Entered name Autocompleted location in „EN“ Autocompleted location in „DE“
Munich Munich (Bavaria, Germany) Munich (Bayern, Deutschland)
München München (Bavaria, Germany) München (Bayern, Deutschland)

Problem: the „forum's default language“ option does not work.

Solution: First, check if it works if you specify the language in the option below. If so, the language probably does not have a locale. To change that, go to ACP / Appearance / Lanuage. Click on the language, select the corresponding locale and save the change.

Published:
Mar 25, 2016
Page Views:
845

Share This Page