Automatic API v3 reference

I have a test page that analyzes contents of google.maps namespace. I've had it for a long time. The trouble was that controlling the version needed some hackery with v3. Now when the version control was released, I decided to polish and share the page. Actually it is a site of three pages, one for each version. Frozen (3.0), Release (3.1) and Nightly (3.2).

API v2 is from 2005 and no namespace thinking was applied. The constructors and all the stuff that v2 offers is introduced in global scope. I never faced any troubles with that but nowadays some people like it as 'bad programming practice'. Actually it really was much trickier to write a similar test page for v2. Global scope (window) has a lot of stuff that is introduced by the browser and must be filtered.

The test page scans google.maps object by a for-in loop. No rubbish is found and no additional filtering is needed. The results contain the constructors and some objects. Those are listed on page and also on the index in the header. All the members that were found are scanned by a for-in loop again. This time looking inside prototype objects. If prototype is not found, the object itself is looped. Resulting properties are listed in a row.

The pages are coded for Firefox only. Firefox presents some unique features for this kind of work. One of them is .toSource() method of Object. It creates a string representation of source code. Firefox presents source code in nice prettyprinted format in alert() dialog box.

With Firefox, you can click any listed method on page and see its internal code. Also there are links to search the method name from documentation, API forum or Google Code Search.

The resulted listing proves that API v3 is written following good programming practices. Almost no internal variables are leaking. The internal source code of the constructors and their methods doesn't reveal much. Still it is worth exploring, you always find something that deepens your understanding about API.

The documentation practice of v3 is different to v2 in the way that there are not many undocumented methods in v3. Still you can find some. Today I saw some new methods of Marker.

You can use the pages for comparing versions. Yes, they are documented separately but still you can find something meaningful.

Circle in v3

Circle object of v3 creates a circular overlay as expected. It is more useful than I first thought.

If you want to zoom your map to show an area of say 50 km radius, that would mean some maths. Create a Circle() of 50 km radius and take its bounds by now provided getBounds(). You can use the bounds to zoom the map by fitBounds(). No calculations needed. An example.

Circle can be used as a marker as well. It is clickable and it works as an anchor for InfoWindow. Marker keeps its size when you zoom. Circle does not but Circle has a minimum size based on stroke width. That is actually nice behavior in many cases. Now there is an updated version of makeMarker(). It creates a Circle instead of Marker if you set any value to 'radius' option.

'title' option does not create a flyover tooltip. However Circle supports all the usual mouse events. So you can create a custom tooltip for the purpose.

Custom icons

Just discovered a custom icon collection project on Google Code. There are more than 900 icons this far.

It would be nice if those were provided in sprite format. Happily there are sprite-making services. SpriteMe is the most advanced of those.

.

clearOverlays() in V3

There is no clearOverlays() in API v3. Some practices have been presented. I think this is the simpliest so far.

Push all the overlays in an array when created (as usual). Following code will clear both map and the array:

  while(overlays[0]){

   overlays.pop().setMap(null);

  }

pop() method of an array removes the last element of an array, and returns that element. 'while' keeps that happening as long as there are elements in the array. When overlays[0] does not exist anymore, the mission is completed and code will proceed.

Applied in the example of the previous post.

Rectangle() and Circle() of V3

API v3.28 has new constructors

  new google.maps.Rectangle();

  new google.maps.Circle();

Dimensioning and positioning is set by bounds (Rectangle) or by center and radius (Circle). Circle radius is given in meters. Those can be set as options or by special methods setBounds(), setCenter() and setRadius().  They are documented already.

getBounds() for Circle would be a useful method that is missing.

Altogether those are very handy classes and we can forget my boundsbox.js library in most cases. Image overlaying is still a perfect task for boundsbox.

Quickly testing Rectangle().

.

Suggesting geocoder [3]

From the previous post: "Next logical step of development will be to display all the alternative addresses as a selectable list."

While developing, I found this kind of user interface very handy. You can even learn something new while typing. I like it better than classic maps.google.com.

Maybe I should give a hint to maps.google.com people:)

Play with it and comment please.


<joke>
Many geocoders recognize a placename "undefined".

Buttonless geocoder [2]

Google's geocoding service is enhanced continuously. It doesn't read your thoughts yet but it is quite forgiving with typos and missing characters.

Now you can see the geocoding result after every character you type in the new geocoder experiment. When you agree with the result in the display, click outside text field or hit Tab or Enter (not IE) and the map is updated too.

So the geocoding request is sent by 'keyup' and map is set by 'change' events of text input field. Clicking on map does not blur the text field and does not trigger 'change'. That is still waiting for a great idea.

Some people can type damn fast. Therefore the geocoding requests are limited to maximum three requests per second.

The 'hint' display shows the first address of the response set. Next logical step of development will be to display all the alternative addresses as a selectable list.