On Dec 29, 11:15 am, Rossko <[email protected]> wrote: > Is this the Christmas Troll ?
Let me apologize in advance. I am aware I'm picking things apart in ways that may be perceived as antagonistic. My intention is not to troll -- I'm trying to offer two perspectives. First, I want to offer initial impressions from a reasonably experienced programmer coming into the API for the first time. In that context, I'm having trouble understanding important elements, and as such (and as a developer of api's in the past myself), I'm hoping to be helpful by pointing out how certain changes to the doc can improve upon this. (I've written two volumes for ORA on programming with various toolkits, and I have a good sense of when doc is effective, and when it's got some holes.) Secondly, my use of the API is one that is both unconventional for "address lookup" applications, yet still representative of the fact that there can be many such non-conventional uses. I have a strong sense that the api evolved over time to lean more and more towards the homogeneous use: postal address lookup. yet, without being aware of it, applications (and potential) are being left out. I'm trying to offer constructive advice for how the api can be expanded in ways that preserve the initial intention, the evolved goals, and still cast a wide net of potential uses. Getting that fresh perspective from the outside can be useful if you're willing to see it. All that said, I will try to be more obsequious in my tone. > > > >> getLatLng() doesn't have its own interface to the server. It simply > > > >> makes a .getLocations() call and extracts a GLatLng from the > > > >> Point.coordinates of the first Placemark. > > > > >It'd have been nice if the reference doc said that. > > Why? it's a "black box", you give it a string, it returns a single point. When programmers know the internal workings and implementation of certain aspects of the toolkit, they can make more informed decisions on which approach they wish to take, or make notes of errors they encounter (which can be used to help track down bugs), or consider streamlining architectures or coding styles to either take advantage or avoid certain features. In my particular case, had I known the getLatLng() was merely a subset of getLocations(), I would have discovered some of my own bugs much earlier, and not spun my wheels trying to demonstrate why each had been returning different results to the same query string. "Black box" and other abstractions are not hidden for the purpose of keeping the user(programmer) *from* information--it's to preserve API integrity so that underlying implementations can be modified (fixed, changed, improved, extended) without disturbing the higher-level application layer. > > Is the source available? I don't see any references to it. Do you have > > access to info that we mere mortals don't? > > Mike takes the trouble to > investigate the compressed (obfuscated) code to see what it does. Good to know. And though I personally won't be making use of it, it's a fact worth knowing. Mike's resourcefulness has been a boon to us all, and I suspect his advice would not be as thorough had he not been so resourceful. Just because I may differ with him on his opinions for how things 'should' be, doesn't mean I don't appreciate the breadth of knowledge he shares. > > ...nowhere does it > > say that the geocoder is specifically for *postal addresses*. > This is true. [...] > They probably don't think anyone is going to use non-postal addresses, > whatever they are. Consider the lead-in text on the Home Page for the google maps API: "The Google Maps API lets you embed Google Maps in your own web pages with JavaScript. The API provides a number of utilities for manipulating maps (just like on the http://maps.google.com web page) and adding content to the map through a variety of services, allowing you to create robust maps applications on your website." I humbly submit that this says nothing about postal addresses, and given its strong bias towards them, I think it's misleading. Now, I'm not trolling when I say this--Im being quite sincere: The API and the documentation need to be more cohesive on the intended audience. If it's going to be all about postal addresses, that's fine--but say so. If it's going to be more flexible than that, modify the API to allow that flexibility. You can't have both or you'll have the kind of confusion I experienced. If the intended audience is to be inclusive of those who do not necessarily wish to have postal-code lookups exclusively, then the API can offer more flexibility. I offered suggestions on how to achieve that without breaking existing code or expectations: permit syntax such as "city:name", "country:name" and so on... Or allow me to construct a data structure (of whatever form you wish) that fills in those fields. We already happen to have the JSON response structure available to us. How about that? This would not only help me solve my problem, but I suspect other users could make good use of it too. But if it *is* designed for "postal address lookup" to virtual exclusivity, then the 'home page' should say so directly: "The Geocoder API is very much designed to look up and map postal addresses, and as such, it will not perform well for applications that need to map things that are more generic in nature. In such cases, you may wish to use Geonames or others listed in ..." > > This engine has the potential > > to provide maps for all sorts of world-wide uses, where the "context" > > is based on the data, not the end-user. > > Absolutely. That's why it gives you the flexibility to program the > "context" yourself. I don't wish to belabor a point, but I've been having a very hard time getting geocoder to stop trying to whittle my input strings down to postal addresses. I want to give it a 'city, state, country' and not have it try to interpret that input as anything different -- if a state's name happens to be a road, or a city name happens to be a country -- that's not something I have the ability to work around in the current API. The syntax simply doesn't permit me to clarify this information. So, when I'm writing an automated system that feeds it a huge amount of data that cannot be humanly checked and verified, I would call that 'inflexible.' > If you don't like function closure, don't use it. It's not about liking it... Because I can't have client data (or my own input string) passed back to my own callback function, I'd have to conjure up a complex way to save that info when it's passed to the server, so that I can report back diagnostic information within the callback. IMHO, this is inflexible, and (with all due respect) it is a very simple problem to solve by the google developers: even if there's an error in the geocoding, fill in the 'address' field of the JSON object passed to the callback function so more effective error reporting can be done. This makes life easier for everyone. > Bear in mind you are using GClientGeocoder in a non-recommended > wayhttp://code.google.com/apis/maps/documentation/reference.html#GClient... > "As a general best practice, it is not recommended to use > GClientGeocoder functions in a loop." While this is true, the reason is usually because you're going to run into a 620 error. Fine--caution noted, and "caller beware." Granted, my first uses of the API didn't realize I'd run into the 620 error as I did, but that's ok. New exposure to an API often yields imperfect results. But it's important to understand the role of an API -- it's to provide *mechanism, not policy*. The policy is enforced by the limitations of the back-end service -- Google institutes its policy through the speed limits and other various methods. If I, as the programmer, choose a particular method because my internal data or automation of that data makes it more efficient or easier, that's my discretion. I'll run into the policy enforcement (as I did) and re-architect my design using a different approach. But none of this should have anything to do with whether the API should or should not support passing useful info back to the callback function. Let me repeat again that I am not trying to be confrontational here--I think these are all valid points worth discussing. Reasonable people can disagree, but there's still benefit in understanding new views. dan -- You received this message because you are subscribed to the Google Groups "Google Maps API" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/google-maps-api?hl=en.
