Coba fitur Distance Matrix generasi berikutnya dengan Routes API, yang sekarang tersedia di Preview.

Praktik Terbaik Menggunakan Layanan Web Distance Matrix API

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Layanan web Google Maps Platform adalah kumpulan antarmuka HTTP ke layanan Google yang menyediakan data geografis untuk aplikasi peta Anda.

Panduan ini menjelaskan beberapa praktik umum yang berguna untuk menyiapkan permintaan layanan web dan memproses respons layanan. Lihat panduan developer untuk dokumentasi lengkap Distance Matrix API.

Apa yang dimaksud dengan layanan web?

Layanan web Google Maps Platform adalah antarmuka untuk meminta data Maps API dari layanan eksternal dan menggunakan data dalam aplikasi Maps Anda. Layanan ini didesain untuk digunakan bersama dengan peta, sesuai dengan Pembatasan Lisensi dalam Persyaratan Layanan Google Maps Platform.

Layanan web Maps API menggunakan permintaan HTTP(S) ke URL tertentu, meneruskan parameter URL dan/atau data POST berformat JSON sebagai argumen ke layanan. Umumnya, layanan ini menampilkan data dalam permintaan HTTP(S) sebagai JSON atau XML untuk menguraikan dan/atau memprosesnya oleh aplikasi Anda.

Permintaan Distance Matrix API standar umumnya dengan bentuk berikut:

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

dengan output menunjukkan format respons (biasanya json atau xml).

Catatan: Semua aplikasi Distance Matrix API memerlukan autentikasi. Dapatkan informasi lebih lanjut tentang kredensial autentikasi.

Akses SSL/TLS

HTTPS diperlukan untuk semua permintaan Google Maps Platform yang menggunakan kunci API atau memuat data pengguna. Permintaan yang dibuat melalui HTTP yang berisi data sensitif dapat ditolak.

Membuat URL yang valid

Anda mungkin menganggap URL yang "valid" sudah jelas, tetapi kenyataannya tidak demikian. URL yang dimasukkan dalam kolom URL di browser, misalnya, dapat berisi karakter khusus (misalnya "上海+中國"); browser harus menerjemahkan karakter tersebut secara internal ke dalam encoding yang berbeda sebelum melakukan transmisi. Dengan token yang sama, setiap kode yang menghasilkan atau menerima input UTF-8 bisa memperlakukan URL berisi karakter UTF-8 sebagai "valid", tetapi juga perlu menerjemahkan karakter tersebut sebelum mengirimnya ke server web. Proses ini disebut encoding URL atau encoding persen.

Karakter khusus

Karakter khusus harus diterjemahkan karena semua URL harus sesuai dengan sintaksis yang ditentukan oleh spesifikasi Uniform Resource Identifier (URI). Akibatnya, ini berarti URL hanya boleh berisi sebagian karakter ASCII khusus: simbol alfanumerik yang sudah umum, dan beberapa karakter dengan fungsi khusus untuk digunakan sebagai karakter kontrol dalam URL. Tabel ini merangkum karakter tersebut:

Ringkasan Karakter URL yang Valid
KumpulankarakterPenggunaan URL
Alfanumerik a b c d e f g h i j k l m n p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 String teks, penggunaan skema (http), port (8080), dll.
Tanpa fungsi khusus - _ . ~ String teks
Dengan fungsi khusus ! * ' ( ) ; : @ & = + $ , / ? % # [ ] Karakter kontrol dan/atau String Teks

Saat membuat URL yang valid, Anda harus memastikan bahwa URL tersebut hanya berisi karakter yang ditampilkan dalam tabel Ringkasan Karakter URL yang Valid. Penyesuaian URL untuk menggunakan kumpulan karakter ini biasanya menyebabkan dua masalah, yaitu masalah penghilangan dan masalah penggantian:

  • Karakter yang ingin Anda tangani tidak termasuk dalam kumpulan karakter di atas. Misalnya, karakter dalam bahasa asing seperti 上海+中國 harus dienkode menggunakan karakter di atas. Menurut aturan umum, spasi (yang tidak diizinkan dalam URL) sering kali juga dinyatakan menggunakan karakter plus '+'.
  • Karakter termasuk dalam kumpulan karakter di atas sebagai karakter dengan fungsi khusus, tetapi harus digunakan secara literal. Misalnya, ? digunakan dalam URL untuk menunjukkan awal dari string kueri; jika Anda ingin menggunakan string "? and the Mysterians", Anda harus mengenkode karakter '?'.

Semua karakter yang akan dienkode ke URL dienkode menggunakan karakter '%' dan nilai heksadesimal dua karakter yang sesuai dengan karakter UTF-8. Misalnya, 上海+中國 di UTF-8 akan dienkode ke URL sebagai %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. String ? and the Mysterians akan dienkode ke URL sebagai %3F+and+the+Mysterians atau %3F%20and%20the%20Mysterians.

Karakter umum yang memerlukan encoding

Beberapa karakter umum yang harus dienkode adalah:

Karakter tidak aman Nilai yang dienkode
Spasi %20
" %22
< %3C
> %3E
# %23
% %25
| %7C

Mengonversi URL yang Anda terima dari input pengguna terkadang rumit. Misalnya, seorang pengguna dapat memasukkan alamat sebagai "5th&Main St." Biasanya, Anda harus membuat URL Anda dari bagian-bagiannya, memperlakukan setiap input pengguna sebagai karakter literal.

Selain itu, URL dibatasi hingga 8.192 karakter untuk semua layanan web Google Maps Platform dan Static Web API. Untuk sebagian besar layanan, batas karakter ini jarang tercapai. Namun, perhatikan bahwa layanan tertentu memiliki beberapa parameter yang bisa mengakibatkan URL menjadi panjang.

Penggunaan Moderat Google API

Klien API yang didesain dengan buruk dapat menempatkan beban yang lebih besar daripada yang diperlukan pada server Internet dan Google. Bagian ini berisi beberapa praktik terbaik untuk klien API. Mengikuti praktik terbaik ini dapat membantu Anda menghindari aplikasi diblokir karena penyalahgunaan API yang tidak disengaja.

Backoff Eksponensial

Dalam kasus yang jarang terjadi, mungkin terjadi masalah saat menayangkan permintaan Anda; Anda dapat menerima kode respons HTTP 4XX atau 5XX, atau koneksi TCP dapat mengalami kegagalan antara klien Anda dan server Google. Sering kali, sebaiknya coba lagi permintaan karena permintaan tindak lanjut dapat berhasil jika permintaan asli gagal. Namun, penting untuk tidak hanya melakukan loop berulang saat membuat permintaan ke server Google. Perilaku berulang ini dapat membebani jaringan antara klien Anda dan Google yang menyebabkan masalah bagi banyak pihak.

Pendekatan terbaik adalah mencoba ulang dengan meningkatkan waktu tunda antar percobaan. Biasanya, penundaan ditingkatkan dengan faktor perkalian pada setiap percobaan, pendekatan yang dikenal sebagai Backoff Eksponensial.

Misalnya, pertimbangkan aplikasi yang ingin membuat permintaan ini ke Time Zone API:

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

Contoh Python berikut menampilkan cara membuat permintaan dengan backoff eksponensial:

import json
import time
import urllib.error
import urllib.parse
import urllib.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-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(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.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.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)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["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.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("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}")

Anda juga harus berhati-hati bahwa tidak ada percobaan ulang kode yang lebih tinggi dalam rantai panggilan aplikasi yang menyebabkan permintaan berulang berturut-turut.

Permintaan yang Disinkronkan

Sejumlah besar permintaan yang disinkronkan ke API Google dapat terlihat seperti serangan Distributed Denial of Service (DDoS) pada infrastruktur Google, dan diperlakukan dengan sesuai. Untuk menghindarinya, Anda harus memastikan bahwa permintaan API tidak disinkronkan antar-klien.

Misalnya, pertimbangkan aplikasi yang menampilkan waktu dalam zona waktu saat ini. Aplikasi ini mungkin akan menyetel alarm dalam sistem operasi klien yang mengaktifkannya pada awal menit sehingga waktu yang ditampilkan dapat diperbarui. Aplikasi tidak boleh membuat panggilan API sebagai bagian dari pemrosesan yang terkait dengan alarm tersebut.

Melakukan panggilan API sebagai respons terhadap alarm tetap adalah buruk karena menyebabkan panggilan API disinkronkan ke awal menit, bahkan antara perangkat yang berbeda, bukan didistribusikan secara merata dari waktu ke waktu. Aplikasi yang tidak didesain dengan baik akan menghasilkan lonjakan traffic pada enam puluh kali tingkat normal di awal setiap menit.

Sebagai gantinya, satu rancangan yang mungkin baik adalah menyetel alarm kedua ke waktu terpilih yang acak. Saat alarm kedua ini aktif, aplikasi akan memanggil API yang diperlukannya dan menyimpan hasilnya. Saat aplikasi ingin memperbarui tampilannya di awal menit, aplikasi menggunakan hasil yang disimpan sebelumnya, bukan memanggil API lagi. Dengan pendekatan ini, panggilan API disebar secara merata dari waktu ke waktu. Selain itu, panggilan API tidak menunda rendering saat tampilan sedang diperbarui.

Di samping awal menit, waktu sinkronisasi umum lainnya yang harus Anda berhati-hati tidak targetkan adalah di awal jam, dan awal setiap hari pada tengah malam.

Memproses Respons

Bagian ini membahas cara mengekstrak nilai-nilai ini secara dinamis dari respons layanan web.

Layanan web Google Maps memberikan respons yang mudah dipahami, tetapi tidak terlalu mudah dipahami. Saat melakukan kueri, daripada menampilkan satu set data, Anda mungkin ingin mengekstrak beberapa nilai tertentu. Umumnya, Anda ingin mengurai respons dari layanan web dan hanya mengekstrak nilai-nilai yang Anda minati.

Skema penguraian yang Anda gunakan bergantung pada apakah Anda menampilkan output dalam XML atau JSON. Respons JSON, yang sudah berbentuk objek JavaScript, dapat diproses dalam JavaScript itu sendiri pada klien. Respons XML harus diproses menggunakan prosesor XML dan bahasa kueri XML untuk menangani elemen dalam format XML. Kami menggunakan XPath dalam contoh berikut, karena biasanya didukung dalam library pemrosesan XML.

Memproses XML dengan XPath

XML adalah format informasi terstruktur yang relatif matang yang digunakan untuk pertukaran data. Meskipun tidak seringan JSON, XML memberikan dukungan bahasa yang lebih banyak dan alat yang lebih tangguh. Kode untuk memproses XML di Java, misalnya, disertakan ke dalam paket javax.xml.

Saat memproses respons XML, Anda harus menggunakan bahasa kueri yang sesuai untuk memilih node dalam dokumen XML, bukan menganggap elemen berada di posisi absolut dalam markup XML. XPath adalah sintaksis bahasa untuk mendeskripsikan node dan elemen secara unik dalam dokumen XML. Ekspresi XPath memungkinkan Anda mengidentifikasi konten tertentu dalam dokumen respons XML.

Ekspresi XPath

Pemahaman tentang XPath sangat berguna dalam mengembangkan skema penguraian yang andal. Bagian ini akan berfokus pada penanganan elemen di dalam dokumen XML dengan XPath, yang memungkinkan Anda untuk menangani beberapa elemen dan membangun kueri yang kompleks.

XPath menggunakan ekspresi untuk memilih elemen dalam dokumen XML, menggunakan sintaksis yang mirip dengan yang digunakan untuk jalur direktori. Ekspresi ini mengidentifikasi elemen dalam hierarki dokumen XML, yang merupakan hierarki hierarkis yang mirip dengan DOM. Umumnya, ekspresi XPath bersifat serakah, yang menunjukkan bahwa ekspresi tersebut akan cocok dengan semua node yang cocok dengan kriteria yang diberikan.

Kita akan menggunakan XML abstrak berikut untuk menggambarkan contoh kami:

<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>

Pilihan Simpul dalam Ekspresi

Pilihan XPath memilih node. Node root mencakup seluruh dokumen. Anda memilih node ini menggunakan ekspresi khusus "/". Perlu diketahui bahwa node root bukan node tingkat atas dari dokumen XML Anda; sebenarnya, node tersebut berada satu tingkat di atas elemen level atas ini dan termasuknya.

Node elemen mewakili berbagai elemen dalam hierarki dokumen XML. Elemen <WebServiceResponse>, misalnya, mewakili elemen tingkat atas yang ditampilkan dalam layanan contoh kami di atas. Anda memilih masing-masing node melalui jalur absolut atau relatif, yang ditunjukkan dengan ada atau tidak adanya karakter "/" di awal.

  • Jalur absolut: ekspresi "/WebServiceResponse/result" memilih semua node <result> yang merupakan turunan node <WebServiceResponse>. (Perhatikan bahwa kedua elemen ini merupakan turunan dari node root "/".)
  • Jalur relatif dari konteks saat ini: ekspresi "result" akan cocok dengan elemen <result> apa pun dalam konteks saat ini. Umumnya, Anda tidak perlu khawatir dengan konteksnya, karena biasanya Anda memproses hasil layanan web melalui ekspresi tunggal.

Ekspresi ini dapat ditingkatkan melalui penambahan jalur karakter pengganti, yang ditunjukkan dengan garis miring ganda ("//"). Karakter pengganti ini menunjukkan bahwa nol atau beberapa elemen mungkin cocok dalam jalur intervensi. Ekspresi XPath "//formatted_address," misalnya, akan cocok dengan semua node dari nama tersebut dalam dokumen saat ini. Ekspresi //viewport//lat akan cocok dengan semua elemen <lat> yang dapat melacak <viewport> sebagai induk.

Secara default, ekspresi XPath cocok dengan semua elemen. Anda dapat membatasi ekspresi agar cocok dengan elemen tertentu dengan menyediakan predikat, yang diapit dalam tanda kurung siku ([]). Ekspresi XPath "/GeocodeResponse/result[2] selalu menampilkan hasil kedua.

Tipe Ekspresi
Node root
Ekspresi XPath: "/"
Pilihan:
    <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>
    
Jalur Absolut
Ekspresi XPath:  "/WebServiceResponse/result"
Pilihan:
    <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>
    
Jalur dengan Karakter Pengganti
Ekspresi XPath: "/WebServiceResponse//location"
Pilihan:
    <location>
     <lat>37.4217550</lat>
     <lng>-122.0846330</lng>
    </location>
    
Jalur dengan Predikat
Ekspresi XPath:  "/WebServiceResponse/result[2]/message"
Pilihan:
    <message>The secret message</message>
    
Semua turunan langsung dari result pertama
Ekspresi XPath: "/WebServiceResponse/result[1]/*"
Pilihan:
     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
    
name dari result yang teks type-nya adalah "sample."
Ekspresi XPath: "/WebServiceResponse/result[type/text()='sample']/name"
Pilihan:
    Sample XML
    

Penting untuk diperhatikan bahwa saat memilih elemen, Anda memilih node, bukan hanya teks dalam objek tersebut. Secara umum, Anda sebaiknya melakukan iterasi pada semua node yang cocok dan mengekstrak teks. Anda juga dapat langsung mencocokkan node teks; lihat Node Teks di bawah.

Perhatikan bahwa XPath juga mendukung node atribut; namun, semua layanan web Google Maps menyalurkan elemen tanpa atribut, sehingga pencocokan atribut tidak diperlukan.

Pemilihan Teks dalam Ekspresi

Teks dalam dokumen XML ditentukan dalam ekspresi XPath melalui operator node teks. Operator ini "text()" menunjukkan ekstraksi teks dari node yang ditunjukkan. Misalnya, ekspresi XPath "//formatted_address/text()" akan menampilkan semua teks dalam elemen <formatted_address>.

Tipe Ekspresi
Semua simpul teks (termasuk spasi)
Ekspresi XPath:  "//text()"
Pilihan:
    sample
    Sample XML

    37.4217550
    -122.0846330
    The secret message
    
Pemilihan Teks
Ekspresi XPath: "/WebServiceRequest/result[2]/message/text()"
Pilihan:
    The secret message
    
Pilihan Sesuai Konteks
Ekspresi XPath: "/WebServiceRequest/result[type/text() = 'sample']/name/text()"
Pilihan:
    Sample XML
    

Atau, Anda dapat mengevaluasi ekspresi dan mengembalikan serangkaian node, kemudian melakukan iterasi pada "kumpulan node tersebut," mengekstrak teks dari setiap node. Kami menggunakan pendekatan ini dalam contoh di bawah.

Untuk informasi selengkapnya tentang XPath, lihat Spesifikasi XPath W3C.

Mengevaluasi XPath di Java

Java memiliki dukungan luas untuk menguraikan XML dan menggunakan ekspresi XPath dalam paket javax.xml.xpath.*. Oleh karena itu, kode contoh di bagian ini menggunakan Java untuk mengilustrasikan cara menangani XML dan mengurai data dari respons layanan XML.

Untuk menggunakan XPath dalam kode Java Anda, pertama-tama Anda harus membuat instance XPathFactory dan memanggil newXPath() di factory tersebut untuk membuat objek XPath . Objek ini kemudian dapat memproses ekspresi XML dan XPath yang diteruskan menggunakan metode evaluate().

Saat mengevaluasi ekspresi XPath, pastikan Anda melakukan iterasi pada setiap "kumpulan node" yang dapat ditampilkan. Karena hasil ini ditampilkan sebagai node DOM dalam kode Java, Anda harus mengambil beberapa nilai tersebut dalam objek NodeList dan mengulangi objek tersebut untuk mengekstrak teks atau nilai dari node tersebut.

Kode berikut menggambarkan cara membuat objek XPath, menetapkannya sebagai XML dan ekspresi XPath, serta mengevaluasi ekspresi untuk mencetak konten yang relevan.

import org.xml.sax.InputSource;
import org.w3c.dom.*;
import javax.xml.xpath.*;
import java.io.*;

public class SimpleParser {

  public static void main(String[] args) throws IOException {

	XPathFactory factory = XPathFactory.newInstance();

    XPath xpath = factory.newXPath();

    try {
      System.out.print("Web Service Parser 1.0\n");

      // In practice, you'd retrieve your XML via an HTTP request.
      // Here we simply access an existing file.
      File xmlFile = new File("XML_FILE");

      // The xpath evaluator requires the XML be in the format of an InputSource
	  InputSource inputXml = new InputSource(new FileInputStream(xmlFile));

      // Because the evaluator may return multiple entries, we specify that the expression
      // return a NODESET and place the result in a NodeList.
      NodeList nodes = (NodeList) xpath.evaluate("XPATH_EXPRESSION", inputXml, XPathConstants.NODESET);

      // We can then iterate over the NodeList and extract the content via getTextContent().
      // NOTE: this will only return text for element nodes at the returned context.
      for (int i = 0, n = nodes.getLength(); i < n; i++) {
        String nodeString = nodes.item(i).getTextContent();
        System.out.print(nodeString);
        System.out.print("\n");
      }
    } catch (XPathExpressionException ex) {
	  System.out.print("XPath Error");
    } catch (FileNotFoundException ex) {
      System.out.print("File Error");
    }
  }
}