
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.
<script src="http://api.mygeoposition.com/api/geopicker/api.js" type="text/javascript"></script>
<script type="text/javascript">
function lookupGeoData() {
myGeoPositionGeoPicker({
returnFieldMap : {'geoposition1' : '<LAT>,<LNG>'},
returnCallback : 'myCallbackFunction',
startAddress : 'White House, Washington',
startPositionLat : '38.8976964',
startPositionLng : '-77.0365191',
startPositionInputFieldIds : [],
autolocate : false,
locateme : 'true',
zoomLevel : '13',
mapType : 'normal',
showStartupInfoWindow : true,
showResultInfoWindow : true,
backgroundColor : '',
windowTitle : ''
langCode : '',
langButtonSearch : '',
langButtonReturn : '',
langMarkerInfo : '',
langSearchField : '',
langLookupFailed : '',
langLookupNoResults : ''
});
}
</script>
Geo-Coordinates:
<input type="text" name="geoposition1" id="geoposition1" />
<button type="button" onclick="lookupGeoData();">GeoPicker</button>
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:
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: