Javascript GeoPicker Widget - Documentation

Let your website users easily enter geographical data into your forms. Just add a button and some javascript - that's it. Once the button is clicked, a popup with a map is shown. The user can enter his desired location into a searchform and finetune the result by dragging & dropping a marker on the map. Another button click returns the geocoded data back to your website. It's your choice whether the returned data is latitude/longitude, country, city, street address or the postal ZIP code. And it's up to you whether this information is put into one / multiple input fields or handled by your own callback function. - That's geocoding the easy way!

Easy picking of geodata
Integrates into your forms in 2 minutes
Completely free

IE 6.0+
Firefox 1.0+
Opera 9.5+
Safari 4.0+
Chrome

Demo

Geo-Coordinates:

Sourcecode

The basics

As you can see in the above example, the whole magic consists of four simple steps:

Place a link to the javascript on our server
Add an onclick handler to a button
Add ID attributes to some input field
Configure the minimum settings of the widget:
- returnFieldMap - Mapping between the input field IDs the results should be placed in and the format of the returned data
- startAddress - Location to be shown once the popup opens

Live examples

License

This service is completely free of cost. Just add it to your application, be happy and share the love. However, we do not provide any guarantee on accuracy, uptime or functionality. Since this service is based on the Google Maps API, please make sure to stick to their terms of use when using the widget.

Options

There are many ways to modify the popups language, appearance and the format in which the data is returned. Here you can find all the parameters to fit the MyGeoPosition GeoPicker Widget perfectly into your website. Click on the parameter in the example code to read more details.

returnFieldMap (options)

A mapping between the input fields the result data should be placed in and the format the returned data should have. The first value of each mapping is the unique attribute 'id' of an HTML input field. The second value defines the format of the returned geodata. You may only need the latitude and longitude or also the returned city or ZIP code. It is up to you which data you want to have. Just put one or multiple of the following placeholders into the string and they will be replaced with result data: <LAT>, <LNG>, <LAT_MIN>, <LNG_MIN>, <ADDRESS>, <COUNTRY>, <COUNTRY_LONG>, <STATE>, <STATE_LONG>, <DISTRICT>, <DISTRICT_LONG>, <CITY>, <CITY_LONG>, <SUBURB>, <SUBURB_LONG>, <POSTALCODE>, <POSTALCODE_LONG>, <ZIP>, <ZIP_LONG>, <STREET>, <STREET_LONG>, <STREETNUMBER>, <STREETNUMBER_LONG>, <STREETO>, <STREETNO_LONG>. Any other characters, like separators, will be returned as you define them. The "_LONG" version of a placeholder value would be something like "United States of America", while the regular version would be "USA".

AllinOne:

Latitude/Longitude:
/

...in degrees, minutes and seconds:
/

Street:

PostalCode:

City:

returnCallback (options)

Instead of letting our script put the result data somewhere, you might want to process it on your own. You are free to do that. Just provide the name of a callback function, that will retrieve a geodata object once the result arrived. The object has the following format:
{
   lat = '', // Latitude
   lng = '', // Longitude
   latMin = '', // Latitude in minutes & seconds
   lngMin = '', // Longitude in minutes & seconds
   address = '', // Full address string
   country.short = '', // Country
   country.long = '', // Country
   state.short = '', // State
   state.long = '', // State
   district.short = '', // Area
   district.long = '', // Area
   city.short = '', // City
   city.long = '', // City
   suburb.short = '', // Suburb
   suburb.long = '', // Suburb
   postalCode.short = '', // ZIP
   postalCode.long = '', // ZIP
   street.short = '' // Street
   street.long = '' // Street
   streetNumber.short = '' // Street number
   streetNumber.long = '' // Street number
}

startAddress (options)

Defines the place shown in the popup's map once it has opened. Use can use a city, street or point of interest. - Basically anything you can enter into the real Google Maps search field.

Geo-Coordinates:

startPositionLat/startPositionLng (options)

Defines the place shown in the popup's map once it has opened. Use an integer value with a dot as decimal separator. Use a positive value for eastern/northern and negative value for western/southern latitude/langitude. Only works when both startPositionLat and startPositionLng are defined.

Geo-Coordinates:

startPositionInputFieldIds (options)

In case you want to let the user enter an address anyways, why not use those values as the starting point of the opening map? This way the positioning is on a good way and only the finetuning is left. Just give your input fields unique IDs and provide these IDs in form of an array. The GeoPicker will take the user-provided values and display the address on the map. You can provide street names, ZIP codes, city or country names, as well as special points of interest. Basically anything you can also enter in the real Google Maps input field.

Street:
City:
Geo-Coordinates:

autolocate (options)

Enables the automatic location lookup when the geopicker opens. In case the user runs a modern webbrowser like Mozilla Firefox 3.5 and appropriate hardware, his current location is retrieved from the devices GPS sensor using the W3C Geolocation standard. The resulting coordinates are then displayed on the popup's map once the window has opened. This is great if you want to let the user enter his current position. Otherwise it is not recommended, since the user is asked whether he really wants to provide this data to the website. That can be quite annoying if he doesn't really need the result.

Geo-Coordinates:

locateme (options)

Disables the "Locate me" button, which is usually located on the left-hand side of the search form (IE9+, FF3.5+). By clicking the button, the user can trigger the display of his current position. In case the user runs a modern webbrowser like Mozilla Firefox 3.5 and appropriate hardware, his current location is retrieved from the devices GPS sensor using the W3C Geolocation standard.

Geo-Coordinates:

zoomLevel (options)

Zoomlevel of the map. Enter a numerical value between 1 (very close) and 20 (almost from space). Experience shows, that 13 works best for most purposes.

Geo-Coordinates:

mapType (options)

Set 'roadmap' for regular road map, 'satellite' for aerial pictures, 'hybrid' for both or 'terrain' for a terrain map.

Geo-Coordinates:

showStartupInfoWindow (options)

If enabled, the initial popup will have a infow window explaining how to use the application.

Geo-Coordinates:

showResultInfoWindow (options)

If enabled, an info window will tell the user about resulting location data.

Geo-Coordinates:

backgroundColor (options)

Background color of the popup. Enter a CSS compatible value. This can be a hexadecimal value with a leading hash (e.g. "#ffffff") or a HTML compatible color name (e.g. "black", "white", "lightgrey").

Geo-Coordinates:

windowTitle (options)

String that appears in the popup window's title bar. If you define no value, the title of your website's window is used.

Geo-Coordinates:

langCode (options)

Two-character language code. This defines the language of the interfaces buttons and messages, but also the language of the return values. Example: With language code "en" (English, default) the Bavarian capital will be returned as "Munich", with code "de" (German) as "München". If you provide no language code, the users default browser language will be detected. The following interface languages are currently supported:

Your language

If you want to support this project by adding your own language, please translate language.php and send it to us. We will be glad to add new language versions to the widget and add a backlink to your website within this documentation.

Geo-Coordinates:

langStrings (options)

In case your language is not supported and your language code returns the default english labels, you can set your own language strings.

Geo-Coordinates: