Location is an important aspect of the Media Factory platform and this section covers everything you need to know regarding geo-tagged content in your contest, community or other application.

While many of the concepts can be applied to using our API on your site, this document only applies to our implementation of maps in our applications.

Our products use the jQuery ui map plugin for rendering maps, and more documentation about this plugin can be found here.

The features that are currently location-aware are:

  • Media
  • Users
  • Events
  • Groups

There are two ways Media Factory accepts longitude and latitude values. It can either be supplied through the POST variables geo_longitude and geo_latitude when using the Upload endpoint, or it can be embedded in JPEG images as EXIF data. For all videos, and most images, you need to use the POST variables.

To initialize a map, we need to call the fm.maps.init function, which accepts the following arguments:


centerSTRINGCenter the map at this location (Latitude and longitude). Example: "52,-97"
zoomINTThe default zoom level of the map. While this can vary from 1 to 18, a zoom level of 3 is considered ideal for displaying most of North America.
mediaBOOLEANSet this variable to true to display media on the map, or false if you don't want to load any media on the map.
imageResizeUrlSTRINGWhen working in the live Media Factory environment, this should always be set to ''. For the staging Media Factory environment, set this to ''.
callbackFunction NameAllows you to specify what the map is for - It can have values fm.maps.dropMarker (Allow user to drop a marker on the map) or fm.maps.mediaUpdater (Display media on the map)

Dropping a pin

If you want to add the option for users to be able to drop a marker on a map to locate their media, you will have to follow the steps below:

Add the following snippet of code to your template. This will ensure we have a div to render the map.

<div class="formBox clearfix">

<!-- Search address text field -->
<input type="text" id="searchAddressField" class="fmTextInput left" style="width:330px;"/>

<!-- Locate Button -->
<span class="fmButtonSm"><input type="button" onclick="fm.maps.searchAddress( $('#searchAddressField').val());" value="Locate" /></span>


<!-- Map will rendered in this div -->
<div id="map" class="left" style="width:330px;height:300px;"></div>

Now add the following code toward the end of your template. This will ensure that the map is rendered in the "map" div as mentioned above.

<!-- Initialize maps on our page -->
<script type="text/javascript">

/* fm.maps.init(center,zoom,media,image resize url,callback) */
var map = fm.maps.init("52,-97",2,false,'',fm.maps.dropMarker);

<!-- Include all necessary jQuery libraries -->
<script type="text/javascript" src=""></script>
<script type="text/javascript" src="/static/contest/v3/js/"></script>
<script type="text/javascript" src="/static/contest/v3/js/map_v3.0.0.js"></script>

This should render a searchable map as shown below. Every time the user places a pin on the map, the values for hidden input fields geo_latitude and geo_longitude are updated. This data is sent along with all the other data a user submits.

Latitude (geo_latitude):

Longitude (geo_longitude):

Displaying media on a map

To display location based media on a map, we need to make a small modification in the initialization code above. Set the variable media to true and the callback function to fm.maps.mediaUpdater

/* fm.maps.init(center,zoom,media,image resize url,callback) */
var map = fm.maps.init("52,-97",3,true,'',fm.maps.mediaUpdater);

Filtering Media

We can filter media on the map by geographical boundaries, groups, events, collections and most of the filters mentioned in the media.getFiles method. To specify such filters, you will have to download and save a copy of the map_v3.0.0.js in your project's assets folder and change the source links in your code to point to it.

You can find the map_v3.0.0.js for contest here and community here. In the mediaUpdater function, you will have to add any filters you wish to the array paramsMedia as shown below:

var paramsMedia = {
  'method': 'media.getFiles',
  'vhost': selectedVHost,
  'limit': 500,
  'filters': {
    'geoBoundaries': [,,,],
    'channel': channel,
    'groupid': groupID,
    'eventid': eventID,
    'includeChildren': 1,
    'moderationStatus': moderation
  'fields': ['title', 'geo_latitude', 'geo_longitude', 'thumbUrl', 'filetype', 'hits', 'id']

Working with the data

This data is exposed in our API's, such as for example with the getFiles method. It is possible to filter by a specific areas through a rectangle. You'll need to specify this by supplying the top-left and bottom-right points. This filter is called geoBoundaries.

To avoid making many superfluous calls to the API, we have some recommendations:

  • Make sure you cache data in the browser. When a user zooms in and zooms back out it should not be needed to make this call twice.
  • We recommend only displaying a limited amount of items in any view. Somewhere between 30 and 100 is a good range.
  • We also recommend sorting the data you receive by some popularity statistic, such as views, hits or comments. When you are showing a limited amount of items per view, you might as well show the 'best' content.
  • The most important advice: When a user interacts with the map, by going to a different location or zooming, it will be very likely the user will move/zoom multiple times until the 'final destination' is reached. If you make an API call for each of these interactions, you could end up with lots of requests. Therefore we recommend adding a 3 second delay when the user changes the location/zoom level. Make sure that when the user moves the map, you cancel the previous 3 second timeout.


Be the first to comment on Geo-location.

Add a Comment

  • captcha