The Yahoo Maps API is powerful, but largely undocumented.

I'm guessing all the docs / marketing materials were written by developers and project managers, with little product management considered -- because its damn near impossible to do the simplest things.

My needs weren't intense , I merely wanted to do this:

• Include a map on a web page that plots an address

One would be amazed at how assbackwards the Yahoo and Google APIs are. Doing something simple like that is a complete PITA. Neither offer the ability to do that "out-of-the-box".

At the end of this posting is a sample of code that will do this.

Before I get into that, I'll talk about my learnings from fighting with APIs and a lack of documentation for over 3 hours.

The main issue I had was with the difference between an address and a geopoint. Yahoo will let you instantiate a map from an address, however placing markers must be done with a geopoint. The yahoo library is asynchronous -- so when you render the map, it has no idea what the geopoint is... so you'll need to leverage into their callback chain hooks to later derive the geopoint for the address , or mapcenter. Of course, none of this behavior is documented. Nor are any of the class methods documented in full.

I eventually came up with two possibilities:

• generate a map from an address, in a callback query the center geopoint & label it
• generate a geopoint from an address, in a callback draw the map and label it

I ended up going with the latter. here is the code

<div id="ymap"></div>
<script type='text/javascript' src='http://api.maps.yahoo.com/ajaxymap?v=3.8&appid=#####API_KEY######'></script>
<script type="text/javascript">
    var map= undefined;
    var mapAddress= "#####ADDRESS#####";
    function ymapStart(){
        map = new YMap(document.getElementById('ymap'));  
        map.addTypeControl();  
        map.addZoomLong();  
        map.addZoomShort();
        map.addZoomScale();
        map.addPanControl();  
        map.setMapType(YAHOO_MAP_HYB);  


        // you need to capture the EventsList.onEndGeoCode callback that will be triggered by the map.geoCodeAddress function
        // it would be nice if someone documented that
        // the 3rd paramter, a function, will be called with a YEvent object.
        // that is also undocumented
        YEvent.Capture( 
            map , 
            EventsList.onEndGeoCode ,
            ymapDraw
        );
        go= map.geoCodeAddress(mapAddress);
    }   
    function ymapDraw( eventObject ) {

        // 
        // eventObject is a YEvent object
        // on a onEndGeoCode it returns:
        //  ThisMap - YMap
        //  Address - string
        //  GeoPoint - YGeoPoint
        //  success - bool
        // I have no clue what it returns on other calls
        // all of this was entirely undocumented 

        if ( eventObject.success ) {
            var mymap= eventObject.ThisMap ;
            mymap.drawZoomAndCenter( eventObject.GeoPoint, 3);  
            var marker= new YMarker( eventObject.GeoPoint );
                marker.addLabel(mapAddress);
                marker.addAutoExpand(mapAddress);
            mymap.addOverlay(marker);
        } else {
            // failsafe
            mymap.drawZoomAndCenter( mapAddress , 3);  
        }
    }
    ymapStart();
</script>