An Introduction to the Lat49 API

This Web page provides publishers with an introduction to the lat49 API. Below you will find sections on the basics of the lat49 geo-targeted advertising system, a guide to getting started with lat49 integration, a guide to the lat49 pushpin feature, and a list of issues to watch out for. Links to the various sections are listed at right.

The full lat49 API documentation is available in html and pdf from the links at right. If you need more support with your lat49 integration, please contact us.

The Basics

Lat49 provides geo-targeted ads to publisher websites. To obtain ads from lat49, a publisher website notifies the lat49 ad server of the latitude, longitude, and zoom level of the center of the map shown on the publisher site. The lat49 server then returns the appropriate ad content to an HTML DIV provided on the publisher site. In the lat49 API Documentation, that HTML DIV is referred to as the 'adcontainer' DIV.

Position and size of the 'adcontainer' DIV
The publisher has the freedom to set the position of the 'adcontainer' DIV on the publisher Web page as desired. However, publishers should be aware that lat49 provides ads of various sizes, and that a screen area of 242 pixels wide by 133 pixels high is required to accomodate all (typical) on-map ad size variants. The typical on-map ad sizes include: Half Banner (234x60px), Button and Image Text Button (125x125px).

Some of the off-map ad sizes include Leaderboard (728x90px), Full banner (468x60px), and Medium Rectangle (300x250px); Ad containters that use ads of these size must be wide enough and tall enough to encompass them; otherwise, the ads images will be cropped.

See examples of all the lat49 ads on Ad Formats.

Requesting a specific ad size
If the ads are to appear off the map, or if the publisher wants to define the size of the ad they can request a specific ad size. This is done using the Lat49.updateMultiAdsByLatLon() function and is defined in the lat49 API documentation.

Z-index of the 'adcontainer' DIV
The publisher must set the z-index of their 'adcontainer' DIV to an appropriate value so that lat49 ads appear layered on top of other Web page content. A value of '99999' is recommended.

Expanding ads
Expanding Ads are a special lat49 feature that some lat49 advertisers use to display additional information. If available, an expanding ad is served from the lat49 ad server when a user hovers their mouse cursor over a regular lat49 ad. The expanding ad replaces the regular ad in a smooth animation, and disappears when the user moves the mouse again.

The size of the expanding ad is 300 pixels wide by 250 pixels high. Since expanding ads appear and disappear according to user mouse control, it may be acceptable for part of a publisher Web page to be occluded while the expanding ad is visible.

Expanding Ads are only associated with on-map ad sizes: Buttons Ads, Button/Text Ads, and Half Banner Ads.

A Guide to Getting Started

Below is a brief four step guide to coding with the lat49 API. You will find the complete guide and more extensive examples in the API documentation available from the links at top right. If you need more support, please contact us.

1. Put the following script tag into your html document:

2. Initialize the Lat49 API sometime after the document body loads:
3. Place an ad container somewhere on your site:
4. Request an ad when your map view changes. This can be done in one of the following ways:
4.1 Request a default on map ad. 4.2 Request a specific ad size.

Adding Pushpins (Beta)

Lat49 Pushpins are a special lat49 feature that lat49 advertisers and publishers can use to display business locations. To enable lat49 pushpins, a publisher website must request that location data be returned with ad content. In return, the ad served from the lat49 ad server is supplied with a pushpin control panel that includes two buttons labelled Map it and Clear.

Size of the 'adcontainer' DIV with pushpins
The pushpin control panel increases the screen area required for the 'adcontainer' DIV to 242 pixels wide by 156 pixels high.

Pushpin data returned from lat49 adserver
The pushpin data returned by the lat49 ad server includes four properties for each pushpin: latitude, longitude, title, address, and pushpin url. The latitude and longitude are used by the publisher to position the pushpin on their map. The title and address are used to display additional information about the pin when user hovers or clicks on the pushpin. The pushpin url is used to display the pushpin graphic.

An example implementation of pushpins
The example given below is a brief guide to pushpin implementation. Please refer to the API Documentation for a complete example.

In order to access the pushpin data, modify Step 3 from A Guide to Getting Started above to include two attributes in the 'adcontainer' DIV: onlat49pushpin, and onlat49hidepushpin:

Don't forget to write callback functions to show and hide pushpins. The simple example below shows the pushpin data that will be returned:

Issues to Look Out For

The screen space required for the 'adcontainer' DIV
Lat49 serves ads of various dimensions. The minimum screen area required to display all sizes of lat49 ads is 242 pixels wide by 133 pixels high. If pushpins are used, then the required screen area increases to 242 pixels wide by 156 pixels high in order to accomodate the pushpin control panel.

Placing the 'adcontainer' DIV on the Web page
In most cases, publishers can avoid Web page layout issues by coding the lat49 'adcontainer' DIV as an absolutely-positioned sibling DIV of their map DIV. A parent wrapper DIV is usually required for such an approach. The parent DIV must have a defined position attribute.

Positioning the contents of the 'adcontainer' DIV
The lat49 API provides a 'lat49adposition' attribute to set the position of the contents of the 'adcontainer' DIV. Valid values for 'lat49adposition' are "top-right", "top-left", "bottom-right", and "bottom-left". Note that the 'lat49adposition' attribute sets both the position of the visible lat49 ad, and the position and direction of any expanding ad animation.

Handling Server Accessibility Problems
Although unlikely, at times the lat49 ad server may be inaccessible because of service disruptions, ad blocking software, or other causes. Publishers are advised to take steps to avoid consequent errors on their websites. The section on Handling Server Accessibility Problems within the API Documentation provides more information and suggested solutions.

Lat49 ads are not visible
If Lat49 ads are not visible on your publisher website, then make sure that your site:

1. includes the Lat49.js file (http://adserver.lat49.com/lat49/lat49.php?ver=1.0),
2. supplies your publisher ID (Lat49.initAds(publisherId)),
3. specifies your ad container DIV (<div id="adcontainer"></div>),
4. and calls Lat49.updateAdByLatLon('adcontainer',lat,lon,zoomlevel) everytime the map view changes.

Other possibilities:

1. Turn on debugging mode (<div id="adcontainer" lat49debug="1">).
2. Ad blocker software may be blocking ads. Disable the blocker for testing.
3. The API Documentation provides a number of examples from accessing a single ad, to accessing multiple ads using the Google Maps API and Virtual Earth API.