AI-generated Key Takeaways

outlined_flag

• Google Maps Platform Web Services provide geographic data via HTTP interfaces for use within map applications, requiring authentication and HTTPS for security.

• Construct valid URLs by adhering to URI specifications and encoding special or reserved characters using percent encoding.

• Optimize API usage by implementing error handling, exponential backoff for retries, and distributing requests to avoid overloading servers.

• Process API responses by parsing the JSON or XML formats, utilizing XPath for navigating and extracting data from XML documents.

• XPath enables selection of nodes and text within XML through specific expressions, supporting navigation, filtering, and text extraction functionalities for efficient data processing.

The Google Maps Platform web services are a collection of HTTP interfaces to Googleservices providing geographic data for your maps applications.

This guide describes some common practices useful for setting up your web service requests and processing service responses. Refer to thedeveloper’s guidefor full documentation of the Geocoding API.

What is a web service?

Google Maps Platform web services are an interface for requesting Maps API data fromexternal services and using the data within your Maps applications. These services aredesigned to be used in conjunction with a map, as per theLicense Restrictionsin the Google Maps Platform Terms of Service.

The Maps APIs web services use HTTP(S) requests to specific URLs, passing URL parameters and/orJSON-format POST data as arguments to the services. Generally, these services return data in theresponse body as either JSON or XML for parsingand/or processing by your application.

A typical Geocoding API request is generally of thefollowing form:

https://maps.googleapis.com/maps/api/geocode/output?parameters

whereoutput indicates the response format (usuallyjson orxml).

Note: All Geocoding API applications require authentication.Get more information onauthentication credentials.

SSL/TLS Access

HTTPS is required for all Google Maps Platform requests that use API keys or contain userdata. Requests made over HTTP that contain sensitive data may be rejected.

Building a valid URL

You may think that a "valid" URL is self-evident, butthat's not quite the case. A URL entered within an address bar in abrowser, for example, may contain special characters (e.g."上海+中國"); the browser needs to internally translatethose characters into a different encoding before transmission.By the same token, any code that generates or accepts UTF-8 inputmight treat URLs with UTF-8 characters as "valid", but would also needto translate those characters before sending them out to a web server.This process is calledURL-encoding orpercent-encoding.

We need to translate special characters becauseall URLs need to conform to the syntax specified by theUniformResource Identifier (URI) specification. In effect, this means that URLsmust contain only a special subset of ASCII characters: the familiaralphanumeric symbols, and some reserved characters for use as controlcharacters within URLs. This table summarizes these characters:

When building a valid URL, you must ensure that it contains only those characters shown in the table. Conforming a URL to use this set of characters generally leads to two issues, one of omission and one of substitution:

• Characters that you wish to handle exist outside of the above set. For example, characters in foreign languages such as上海+中國 need to be encoded using the above characters. By popular convention, spaces (which are not allowed within URLs) are often represented using the plus'+' character as well.
• Characters exist within the above set as reserved characters, but need to be used literally. For example,? is used within URLs to indicate the beginning of the query string; if you wish to use the string "? and the Mysterions," you'd need to encode the'?' character.

All characters to be URL-encoded are encodedusing a'%' character and a two-character hexvalue corresponding to their UTF-8 character. For example,上海+中國 in UTF-8 would be URL-encoded as%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. Thestring? and the Mysterians would be URL-encoded as%3F+and+the+Mysterians or%3F%20and%20the%20Mysterians.

Common characters that need encoding

Some common characters that must be encoded are:

Converting a URL that you receive from user input is sometimestricky. For example, a user may enter an address as "5th&Main St."Generally, you should construct your URL from its parts, treatingany user input as literal characters.

Additionally, URLs are limited to 16384 characters for all Google Maps Platform web servicesand static web APIs. For most services, this character limit will seldom be approached. However,note that certain services have several parameters that may result in long URLs.

Polite Use of Google APIs

Poorly designed API clients can place more load than necessary on both the Internet andGoogle's servers. This section contains some best practices for clients of the APIs. Followingthese best practices can help you avoid your application being blocked for inadvertent abuse ofthe APIs.

Managing errors and retries

For information onUNKNOWN_ERROR orOVER_QUERY_LIMIT response codes from the Geocoding API, read aboutmanaging errors and retries.

Exponential Backoff

In rare cases something may go wrong serving your request; you may receive a 4XX or 5XX HTTPresponse code, or the TCP connection may simply fail somewhere between your client and Google'sserver. Often it is worthwhile re-trying the request asthe followup request may succeed when the original failed. However, it is important not to simplyloop repeatedly making requests to Google's servers. This looping behavior can overload thenetwork between your client and Google causing problems for many parties.

A better approach is to retry with increasing delays between attempts. Usually thedelay is increased by a multiplicative factor with each attempt, an approach known asExponential Backoff.

For example, consider an application that wishes to make this request tothe Time Zone API:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

The following Python example shows how to make the request with exponential backoff:

importjsonimporttimeimporturllib.errorimporturllib.parseimporturllib.request# The maps_key defined below isn't a valid Google Maps API key.# You need to get your own API key.# See https://developers.google.com/maps/documentation/timezone/get-api-keyAPI_KEY="YOUR_KEY_HERE"TIMEZONE_BASE_URL="https://maps.googleapis.com/maps/api/timezone/json"deftimezone(lat,lng,timestamp):# Join the parts of the URL together into one string.params=urllib.parse.urlencode({"location":f"{lat},{lng}","timestamp":timestamp,"key":API_KEY,})url=f"{TIMEZONE_BASE_URL}?{params}"current_delay=0.1# Set the initial retry delay to 100ms.max_delay=5# Set the maximum retry delay to 5 seconds.whileTrue:try:# Get the API response.response=urllib.request.urlopen(url)excepturllib.error.URLError:pass# Fall through to the retry loop.else:# If we didn't get an IOError then parse the result.result=json.load(response)ifresult["status"]=="OK":returnresult["timeZoneId"]elifresult["status"]!="UNKNOWN_ERROR":# Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or# ZERO_RESULTS. There is no point retrying these requests.raiseException(result["error_message"])ifcurrent_delay>max_delay:raiseException("Too many retry attempts.")print("Waiting",current_delay,"seconds before retrying.")time.sleep(current_delay)current_delay*=2# Increase the delay each time we retry.if__name__=="__main__":tz=timezone(39.6034810,-119.6822510,1331161200)print(f"Timezone:{tz}")

You should also be careful that there isn't retry code higher in the application callchain that leads to repeated requests in quick succession.

Synchronized Requests

Large numbers of synchronized requests to Google's APIs can look like a DistributedDenial of Service (DDoS) attack on Google's infrastructure, and be treated accordingly. Toavoid this, you should make sure that API requests are not synchronizedbetween clients.

For example, consider an application that displays the time in the current time zone.This application will probably set an alarm in the client operating system waking it up atthe start of the minute so that the displayed time can be updated. The application shouldnot make any API calls as part of the processing associated with that alarm.

Making API calls in response to a fixed alarm is bad as it results in the API calls beingsynchronized to the start of the minute, even between different devices, rather than beingdistributed evenly over time. A poorly designed application doing this will produce a spike oftraffic at sixty times normal levels at the start of each minute.

Instead, one possible good design is to have a second alarm set to a randomly chosen time.When this second alarm fires the application calls any APIs it needs and stores theresults. When the application wants to update its display at the start of the minute, it usespreviously stored results rather than calling the API again. With this approach, API callsare spread evenly over time. Further, the API calls do not delay rendering when the display isbeing updated.

Aside from the start of the minute, other common synchronization times you should be carefulnot to target are at the start of an hour, and the start of each day at midnight.

Processing Responses

The parsing scheme you use depends on whether you are returningoutput in XML or JSON. JSON responses, being already in the form ofJavascript objects, may be processed within Javascript itselfon the client.XML responses should be processed using an XML processorand an XML query language to address elements within the XML format.We useXPath in thefollowing examples, as it is commonly supported in XML processinglibraries.

Processing XML with XPath

XML is a relatively mature structured information format used fordata interchange. Although it is not as lightweight as JSON, XMLdoes provide more language support and more robust tools. Code forprocessing XML in Java, for example, is built into thejavax.xml packages.

When processing XML responses, you should use an appropriatequery language for selecting nodes within the XML document, ratherthan assume the elements reside at absolute positions within theXML markup.XPathis a language syntax for uniquely describing nodes and elementswithin an XML document. XPath expressions allow you to identifyspecific content within the XML response document.

XPath Expressions

Some familiarity with XPath goes a long way towards developinga robust parsing scheme. This section will focus on how elementswithin an XML document are addressed with XPath, allowing you toaddress multiple elements and construct complex queries.

XPath usesexpressions to select elements within an XMLdocument, using a syntax similar to that used for directory paths.These expressions identify elements within an XML documenttree, which is a hierarchical tree similar to that of a DOM.Generally, XPath expressions are greedy, indicating that theywill match all nodes which match the supplied criteria.

We'll use the following abstract XML to illustrate ourexamples:

<WebServiceResponse> <status>OK</status> <result>  <type>sample</type>  <name>Sample XML</name>  <location>   <lat>37.4217550</lat>   <lng>-122.0846330</lng>  </location> </result> <result>  <message>The secret message</message> </result></WebServiceResponse>

Node Selection in Expressions

XPath selections selectnodes. The root nodeencompasses the entire document. You select this node usingthe special expression "/". Note that the rootnode is not the top-level node of your XML document; actually,it resides one level above this top-level element and includesit.

Element nodes represent the various elements within the XMLdocument tree. A<WebServiceResponse> element,for example, represents the top-level element returned in oursample service above. You select individual nodes either viaabsolute or relative paths, indicated by the presence orabsence of a leading "/" character.

• Absolute path: the "/WebServiceResponse/result" expression selects all<result> nodes that are children of the<WebServiceResponse> node. (Note that both of these elements descend from the root node "/".)
• Relative path from the current context: the expression "result" would match any<result> elements within the current context. Generally, you shouldn't have to worry about context, as you're usually processing web service results via a single expression.

Either of these expressions may be augmented through additionof a wildcard path, indicated with a double-slash ("//").This wildcard indicates that zero or more elements may match in theintervening path. The XPath expression "//formatted_address,"for example, will match all nodes of that name in the current document.The expression//viewport//lat would match all<lat> elements that can trace<viewport>as a parent.

By default, XPath expressions match all elements. You can restrictthe expression to match a certain element by providing apredicate,which is enclosed in square brackets ([]). The XPathexpression "/GeocodeResponse/result[2] always returns thesecond result, for example.

    <WebServiceResponse>     <status>OK</status>     <result>      <type>sample</type>      <name>Sample XML</name>      <location>       <lat>37.4217550</lat>       <lng>-122.0846330</lng>      </location>     </result>     <result>      <message>The secret message</message>     </result>    </WebServiceResponse>

    <result>     <type>sample</type>     <name>Sample XML</name>     <location>      <lat>37.4217550</lat>      <lng>-122.0846330</lng>     </location>    </result>    <result>     <message>The secret message</message>    </result>

    <location>     <lat>37.4217550</lat>     <lng>-122.0846330</lng>    </location>

    <message>The secret message</message>

     <type>sample</type>     <name>Sample XML</name>     <location>      <lat>37.4217550</lat>      <lng>-122.0846330</lng>     </location>

    Sample XML

It is important to note that when selecting elements, you select nodes,not just the text within those objects. Generally, youwill want to iterate over all matched nodes and extract the text. Youmay also match text nodes directly; seeText Nodes below.

Note that XPath supports attribute nodes as well; however,all Google Maps web services serve elements without attributes, somatching of attributes is not necessary.

Text Selection in Expressions

Text within an XML document is specified in XPath expressionsvia atext node operator. This operator "text()"indicates extraction of text from the indicated node. For example,the XPath expression "//formatted_address/text()" willreturn all text within<formatted_address>elements.

    sample    Sample XML    37.4217550    -122.0846330    The secret message

    The secret message

    Sample XML

Alternatively, you may evaluate an expression and return a setof nodes and then iterate over that "node set," extracting thetext from each node. We use this approach in the example below.

For more information on XPath, consult theXPath W3C Specification.

EvaluatingXPath in Java

Java has wide support for parsing XML and using XPath expressionswithin thejavax.xml.xpath.* package.For that reason, the sample code in this section uses Java toillustrate how to handle XML and parse data from XML service responses.

To use XPath in your Java code, you will first need to instantiatean instance of anXPathFactory and callnewXPath() on that factory to create anXPath object. This object can then process passed XMLand XPath expressions using theevaluate() method.

When evaluating XPath expressions, make sure that you iterateover any possible "node sets" which may be returned. Because theseresults are returned as DOM nodes in Java code, you should capturesuch multiple values within aNodeList object anditerate over that object to extract any text or values from thosenodes.

The following code illustrates how to create anXPathobject, assign it XML and an XPath expression, and evaluate theexpression to print out the relevant content.

importorg.xml.sax.InputSource;importorg.w3c.dom.*;importjavax.xml.xpath.*;importjava.io.*;publicclassSimpleParser{publicstaticvoidmain(String[]args)throwsIOException{XPathFactoryfactory=XPathFactory.newInstance();XPathxpath=factory.newXPath();try{System.out.print("Web Service Parser 1.0\n");//Inpractice,you'd retrieve your XML via an HTTP request.//Herewesimplyaccessanexistingfile.FilexmlFile=newFile("XML_FILE");//ThexpathevaluatorrequirestheXMLbeintheformatofanInputSourceInputSourceinputXml=newInputSource(newFileInputStream(xmlFile));//Becausetheevaluatormayreturnmultipleentries,wespecifythattheexpression//returnaNODESETandplacetheresultinaNodeList.NodeListnodes=(NodeList)xpath.evaluate("XPATH_EXPRESSION",inputXml,XPathConstants.NODESET);//WecantheniterateovertheNodeListandextractthecontentviagetTextContent().//NOTE:thiswillonlyreturntextforelementnodesatthereturnedcontext.for(inti=0,n=nodes.getLength();i <n;i++){StringnodeString=nodes.item(i).getTextContent();System.out.print(nodeString);System.out.print("\n");}}catch(XPathExpressionExceptionex){System.out.print("XPath Error");}catch(FileNotFoundExceptionex){System.out.print("File Error");}}}