I have been building a web and mobile application which provides location functionality based on a complex integration with the Google Places API.
Fortunately their web API is well documented, and given the scale of the data on offer is well covered with integration wrappers for the various appropriate programming languages.
I utilised this PHP wrapper. By taking a look at the source code you can see how simple the API really is.
One API to rule them all
As alluded to above, both the web application and the mobile applications utilise the Google Places API. To reduce complexity however, they all integrate with Googles web API by proxy of our API. That is to say that the mobile applications call our in-house API which handles calling and returning Google Places data rather than integrating directly with the respective native APIs.
Google offer a 'nearby search' and a 'text search' API endpoint. They also offer 'autocomplete'.
In principle the 'nearby search' would be ideal, but there is the use case where a user wants to upload a photo taken previously in a location that they are now not near. Previously we had integrated a segmented search control such that users could specify if they wanted to search nearby or anywhere. This was however deemed overly complex and as such we settled on a singular 'search' utilising the 'text search' option.
Text search allows you to search for string searches like "Pizza in Leeds".
Unfortunately the text search API blows up a little when it comes to partial search terms.
I found from experimenting that searches for 'Mcdon' would return various results for branches of Mcdonalds, but searches for 'Mcdonal' would return completely different branches (even when the same location bias parameters were sent). One search returned a singular result.. for a Nandos..? :S
The issue with this is that one can safely assume that the closest McDonalds branch is of most relevance to the user. If that result is not returned, or it is not given the prominence it deserves, then again the user experience is affected.
Text search does resolve the issue of locations that are no longer nearby. A user can search for 'Macys New York' and return a specific location somewhere complete different.
In addition to these two 'search' APIs, Google provide an autocomplete API. This allows you to query a partial location name and have suggestions returned as to the location that your user is looking for (like in the Mcdonalds example above). Unfortunately the autocomplete endpoint only returns very basic data - it does not for example return the locations latitude and longitude which in my case meant I could not calculate and display how far the user was from each location.
Whilst the documentation suggests otherwise, my testing suggests that that 'radius' parameter for a 'nearby search' be specified in meters, whilst for a 'text search' it be specified in kilometres (contrary to the documentation). Well.. when the radius is set at 50 for a search from Leeds, England, I get results from Manchester, England too. Last time I checked Manchester was more than 50 metres from Leeds.
Google have annoyingly deprecated their 'types' functionality. Previously you could specify that you only wanted to return results for locations of specific types - bars, restaurants etc. They have not done this with any (in my opinion) justified or reasonable explanation.
My personal opinion is that people are not taking a lot of photos of food at an accountancy firm, and as such it seems reasonable that I should be able to specify not to return locations of type 'accounting'. Google are forcing a poorer user experience on customers of companies who utilise their APIs.
One work around (if using the nearby endpoint) is to do some post processing of the returned results. Such an API call does return the 'types' in the response array and as such (at the cost of a little additional overhead) one can show only the appropriate types of location.