Yêu cầu và phản hồi mã hóa địa lý

Yêu cầu

Yêu cầu API Địa chỉ được mã hoá địa lý có dạng như sau:

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

trong đó outputFormat có thể là một trong các giá trị sau:

  • json (nên dùng) cho biết kết quả ở dạng Ký hiệu đối tượng JavaScript (JSON); hoặc
  • xml cho biết đầu ra ở định dạng XML

Bạn phải dùng HTTPS.

Một số tham số là bắt buộc, còn một số thì không bắt buộc. Theo tiêu chuẩn trong URL, các tham số được phân tách bằng ký tự dấu và (&).

Phần còn lại của trang này mô tả riêng việc mã hoá địa lý và mã hoá địa lý ngược, vì mỗi loại yêu cầu có các thông số khác nhau.

Thông số mã hoá địa lý (truy vấn vĩ độ/kinh độ)

Các tham số bắt buộc trong yêu cầu mã hoá địa lý:

  • address – Địa chỉ đường phố hoặc mã cộng mà bạn muốn mã hoá địa lý. Chỉ định các địa chỉ theo định dạng được dịch vụ bưu chính quốc gia của quốc gia có liên quan sử dụng. Bạn nên tránh sử dụng các thành phần địa chỉ bổ sung như tên doanh nghiệp và số căn hộ, số phòng hoặc số tầng. Các phần tử địa chỉ đường phố phải được phân tách bằng dấu cách (hiển thị ở đây dưới dạng url-escaped to %20):
    address=24%20Sussex%20Drive%20Ottawa%20ON
    Định dạng mã cộng như minh hoạ ở đây (dấu cộng được chuyển đổi URL thành %2B và dấu cách được chuyển đổi URL thành %20):
    • Mã toàn cầu là mã vùng gồm 4 ký tự và mã địa phương từ 6 ký tự trở lên (849VCWC8+R9 là 849VCWC8%2BR9).
    • Mã phức hợp là mã cục bộ có độ dài từ 6 ký tự trở lên với vị trí rõ ràng (CWC8+R9 Mountain View, CA, USA là CWC8%2BR9%20Mountain%20View%20CA%20USA).

    --OR--
    components — Bộ lọc thành phần có các phần tử được phân tách bằng dấu gạch đứng (|). Bộ lọc thành phần cũng được chấp nhận là tham số không bắt buộc nếu bạn cung cấp address. Mỗi phần tử trong bộ lọc thành phần bao gồm một cặp component:value và hạn chế hoàn toàn kết quả từ trình mã hoá địa lý. Hãy xem thêm thông tin về tính năng lọc thành phần ở bên dưới.
  • key — Khoá API cho ứng dụng của bạn. Khoá này xác định ứng dụng của bạn cho mục đích quản lý hạn mức. Tìm hiểu cách lấy khoá.

Vui lòng tham khảo Câu hỏi thường gặp để biết thêm hướng dẫn.

Các thông số không bắt buộc trong yêu cầu Địa chỉ được mã hoá địa lý:

  • bounds – Hộp giới hạn của khung nhìn để thiên lệch kết quả mã địa lý một cách nổi bật hơn. Tham số này chỉ ảnh hưởng, chứ không hoàn toàn hạn chế kết quả của trình dịch địa lý. (Để biết thêm thông tin, hãy xem phần Xu hướng chế độ xem bên dưới.)
  • language – Ngôn ngữ dùng để trả về kết quả.
    • Xem danh sách ngôn ngữ được hỗ trợ. Google thường xuyên cập nhật các ngôn ngữ được hỗ trợ, vì vậy, danh sách này có thể chưa đầy đủ.
    • Nếu bạn không cung cấp language, trình định vị địa lý sẽ cố gắng sử dụng ngôn ngữ ưu tiên như được chỉ định trong tiêu đề Accept-Language hoặc ngôn ngữ gốc của miền mà yêu cầu được gửi.
    • Bộ mã hoá địa lý cố gắng hết sức để cung cấp địa chỉ đường phố mà cả người dùng và người dân địa phương đều có thể đọc được. Để đạt được mục tiêu đó, công cụ này trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang tập lệnh mà người dùng có thể đọc nếu cần, qua đó quan sát ngôn ngữ ưu tiên. Tất cả các địa chỉ khác sẽ được trả về bằng ngôn ngữ ưu tiên. Tất cả thành phần địa chỉ đều được trả về bằng cùng một ngôn ngữ, được chọn từ thành phần đầu tiên.
    • Nếu một tên không được cung cấp bằng ngôn ngữ ưu tiên, thì bộ mã hoá địa lý sẽ sử dụng kết quả khớp gần nhất.
    • Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến tập hợp kết quả mà API chọn trả về và thứ tự trả về các kết quả đó. Trình dịch địa lý diễn giải các từ viết tắt theo cách khác nhau tuỳ thuộc vào ngôn ngữ, chẳng hạn như từ viết tắt cho các loại đường hoặc từ đồng nghĩa có thể hợp lệ trong một ngôn ngữ nhưng không hợp lệ trong ngôn ngữ khác. Ví dụ: utcatér là từ đồng nghĩa tương ứng với đường phố và quảng trường trong tiếng Hungary.
  • region – Mã vùng, được chỉ định dưới dạng ccTLD (miền cấp cao nhất) với giá trị hai ký tự. Tham số này sẽ chỉ ảnh hưởng, chứ không hoàn toàn hạn chế kết quả của trình dịch địa lý. (Để biết thêm thông tin, hãy xem phần Thiên vị theo khu vực bên dưới.) Tham số cũng có thể ảnh hưởng đến kết quả theo luật hiện hành.
  • components – Bộ lọc thành phần có các phần tử được phân tách bằng dấu gạch đứng (|). Bộ lọc thành phần là bắt buộc nếu yêu cầu không bao gồm address. Mỗi phần tử trong bộ lọc thành phần bao gồm một cặp component:value và hạn chế hoàn toàn các kết quả từ bộ mã hoá địa lý. Hãy xem thêm thông tin về tính năng lọc thành phần ở bên dưới.
  • extra_computations – Sử dụng tham số này để chỉ định các tính năng bổ sung sau đây trong phản hồi: Để bật nhiều tính năng trong số này cho cùng một yêu cầu API, hãy thêm tham số extra_computations vào yêu cầu cho từng tính năng, ví dụ:
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Phản hồi

Theo mặc định, các phản hồi về việc mã hoá địa lý được trả về ở định dạng do cờ output chỉ định trong yêu cầu URL hoặc ở định dạng JSON.

Trong ví dụ này, Geocoding API yêu cầu phản hồi json cho truy vấn về địa chỉ "1600 Amphitheatre Parkway, Mountain View, CA".

Yêu cầu này minh hoạ cách sử dụng cờ JSON output:

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Yêu cầu này minh hoạ cách sử dụng cờ output XML:

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Chọn các thẻ bên dưới để xem phản hồi JSON và XML mẫu.

JSON

{
    "results": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "Amphitheatre Parkway",
                    "short_name": "Amphitheatre Pkwy",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "Mountain View",
                    "short_name": "Mountain View",
                    "types": [
                        "locality",
                        "political"
                    ]
                },
                {
                    "long_name": "Santa Clara County",
                    "short_name": "Santa Clara County",
                    "types": [
                        "administrative_area_level_2",
                        "political"
                    ]
                },
                {
                    "long_name": "California",
                    "short_name": "CA",
                    "types": [
                        "administrative_area_level_1",
                        "political"
                    ]
                },
                {
                    "long_name": "United States",
                    "short_name": "US",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "long_name": "94043",
                    "short_name": "94043",
                    "types": [
                        "postal_code"
                    ]
                },
                {
                    "long_name": "1351",
                    "short_name": "1351",
                    "types": [
                        "postal_code_suffix"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4222804,
                    "lng": -122.0843428
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4237349802915,
                        "lng": -122.083183169709
                    },
                    "southwest": {
                        "lat": 37.4210370197085,
                        "lng": -122.085881130292
                    }
                }
            },
            "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
            "plus_code": {
                "compound_code": "CWC8+W7 Mountain View, CA",
                "global_code": "849VCWC8+W7"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

Xin lưu ý rằng phản hồi JSON chứa hai phần tử gốc:

  • "status" chứa siêu dữ liệu về yêu cầu. Xem phần Mã trạng thái bên dưới.
  • "results" chứa một mảng thông tin địa chỉ được mã hoá địa lý và thông tin hình học.

Thông thường, chỉ một mục trong mảng "results" được trả về cho các lượt tra cứu địa chỉ, mặc dù trình mã hoá địa lý có thể trả về một số kết quả khi các truy vấn địa chỉ không rõ ràng.

XML

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
        <address_component>
            <long_name>1600</long_name>
            <short_name>1600</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>Amphitheatre Parkway</long_name>
            <short_name>Amphitheatre Pkwy</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Mountain View</long_name>
            <short_name>Mountain View</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Santa Clara County</long_name>
            <short_name>Santa Clara County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>California</long_name>
            <short_name>CA</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>94043</long_name>
            <short_name>94043</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>37.4224428</lat>
                <lng>-122.0842467</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>37.4212648</lat>
                    <lng>-122.0856069</lng>
                </southwest>
                <northeast>
                    <lat>37.4239628</lat>
                    <lng>-122.0829089</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
        <plus_code>
            <global_code>849VCWC8+X8</global_code>
            <compound_code>CWC8+X8 Mountain View, CA</compound_code>
        </plus_code>
    </result>
</GeocodeResponse>

Xin lưu ý rằng phản hồi XML bao gồm một <GeocodeResponse> và hai phần tử cấp cao nhất:

  • <status> chứa siêu dữ liệu về yêu cầu. Xem Mã trạng thái bên dưới.
  • Không có hoặc có nhiều phần tử <result>, mỗi phần tử chứa một bộ thông tin địa chỉ được mã hoá địa lý và thông tin hình học.

Phản hồi XML dài hơn đáng kể so với phản hồi JSON. Vì lý do đó, bạn nên sử dụng json làm cờ đầu ra ưu tiên, trừ phi dịch vụ của bạn yêu cầu xml vì lý do nào đó. Ngoài ra, việc xử lý cây XML đòi hỏi bạn phải cẩn thận để tham chiếu đến các nút và phần tử thích hợp. Hãy xem phần Phân tích cú pháp XML bằng XPath để biết một số mẫu thiết kế đề xuất cho việc xử lý đầu ra.

  • Kết quả XML được gói trong phần tử gốc <GeocodeResponse>.
  • JSON biểu thị các mục có nhiều phần tử bằng các mảng số nhiều (types), còn XML biểu thị các mục này bằng nhiều phần tử số ít (<type>).
  • Các phần tử trống được biểu thị thông qua các mảng trống trong JSON, nhưng khi không có bất kỳ phần tử nào như vậy trong XML. Ví dụ: một phản hồi không tạo ra kết quả sẽ trả về một mảng results trống trong JSON, nhưng không có phần tử <result> nào trong XML.

Mã trạng thái

Trường "status" trong đối tượng phản hồi Mã hoá địa lý chứa trạng thái của yêu cầu và có thể chứa thông tin gỡ lỗi để giúp bạn theo dõi lý do mã hoá địa lý không hoạt động. Trường "status" có thể chứa các giá trị sau:

  • "OK" cho biết không có lỗi nào xảy ra; địa chỉ đã được phân tích cú pháp thành công và trả về ít nhất một mã địa lý.
  • "ZERO_RESULTS" cho biết mã địa lý đã được tạo thành công nhưng không trả về kết quả nào. Điều này có thể xảy ra nếu trình định vị địa lý được truyền một address không tồn tại.
  • OVER_DAILY_LIMIT cho biết bất kỳ điều nào sau đây:
    • Khoá API bị thiếu hoặc không hợp lệ.
    • Tài khoản của bạn chưa được bật tính năng thanh toán.
    • Bạn đã vượt quá giới hạn sử dụng tự đặt.
    • Phương thức thanh toán bạn cung cấp không còn hợp lệ (ví dụ: thẻ tín dụng đã hết hạn).

    Hãy xem phần Câu hỏi thường gặp về Maps để tìm hiểu cách khắc phục vấn đề này.

  • "OVER_QUERY_LIMIT" cho biết bạn đã vượt quá hạn mức.
  • "REQUEST_DENIED" cho biết yêu cầu của bạn đã bị từ chối.
  • "INVALID_REQUEST" thường cho biết rằng truy vấn (address, components hoặc latlng) bị thiếu.
  • "UNKNOWN_ERROR" cho biết không thể xử lý yêu cầu do lỗi máy chủ. Yêu cầu có thể thành công nếu bạn thử lại.

Thông báo lỗi

Khi trình dịch địa lý trả về một mã trạng thái khác với OK, có thể sẽ có thêm một trường error_message trong đối tượng phản hồi Dịch địa lý. Trường này chứa thông tin chi tiết hơn về lý do phát sinh một mã trạng thái nhất định.

Kết quả

Khi bộ mã hoá địa lý trả về kết quả, bộ mã hoá sẽ đặt các kết quả đó trong một mảng results (JSON). Ngay cả khi không trả về kết quả nào (chẳng hạn như nếu địa chỉ không tồn tại), trình dịch địa lý vẫn trả về một mảng results trống. (Phản hồi XML không chứa hoặc có nhiều phần tử <result>.)

Một kết quả điển hình chứa các trường sau:

  • Mảng types[] cho biết loại của kết quả được trả về. Mảng này chứa một tập hợp gồm 0 hoặc nhiều thẻ xác định loại tính năng được trả về trong kết quả. Ví dụ: mã địa lý của "Chicago" trả về "vị trí" cho biết "Chicago" là một thành phố và cũng trả về "chính trị" cho biết đó là một pháp nhân chính trị. Các thành phần có thể có một mảng loại trống khi không có loại nào được biết cho thành phần địa chỉ đó. API có thể thêm các giá trị loại mới nếu cần. Để biết thêm thông tin, hãy xem phần Loại địa chỉ và thành phần địa chỉ.
  • formatted_address là một chuỗi chứa địa chỉ mà con người có thể đọc được của vị trí này.

    Địa chỉ này thường tương đương với địa chỉ bưu chính. Xin lưu ý rằng một số quốc gia (chẳng hạn như Vương quốc Anh) không cho phép phân phối địa chỉ bưu chính thực do những quy định hạn chế về việc cấp phép.

    Địa chỉ được định dạng theo logic bao gồm một hoặc nhiều thành phần địa chỉ. Ví dụ: địa chỉ "111 8th Avenue, New York, NY" bao gồm các thành phần sau: "111" (số nhà), "8th Avenue" (tên đường), "New York" (thành phố) và "NY" (tiểu bang ở Hoa Kỳ).

    Không phân tích cú pháp địa chỉ đã định dạng theo phương thức lập trình. Thay vào đó, bạn nên sử dụng các thành phần địa chỉ riêng lẻ mà phản hồi API bao gồm ngoài trường địa chỉ được định dạng.

  • address_components[] là một mảng chứa các thành phần riêng biệt áp dụng cho địa chỉ này.

    Mỗi thành phần địa chỉ thường chứa các trường sau:

    • types[] là một mảng cho biết loại của thành phần địa chỉ. Xem danh sách các loại được hỗ trợ.
    • long_name là văn bản mô tả đầy đủ hoặc tên của thành phần địa chỉ do Bộ mã hoá địa lý trả về.
    • short_name là tên viết tắt dạng văn bản cho thành phần địa chỉ (nếu có). Ví dụ: thành phần địa chỉ của tiểu bang Alaska có thể có long_name là "Alaska" và short_name là "AK" khi sử dụng chữ viết tắt của bưu điện gồm 2 chữ cái.

    Lưu ý những thông tin sau đây về mảng address_components[]:

    • Mảng thành phần địa chỉ có thể chứa nhiều thành phần hơn formatted_address.
    • Mảng này không nhất thiết phải bao gồm tất cả các thực thể chính trị chứa địa chỉ, ngoài những thực thể có trong formatted_address. Để truy xuất tất cả các thực thể chính trị chứa một địa chỉ cụ thể, bạn nên sử dụng tính năng mã hoá địa lý đảo ngược, truyền vĩ độ/kinh độ của địa chỉ dưới dạng tham số cho yêu cầu.
    • Định dạng của phản hồi không được đảm bảo sẽ giống nhau giữa các yêu cầu. Cụ thể, số lượng address_components sẽ thay đổi tuỳ theo địa chỉ được yêu cầu và có thể thay đổi theo thời gian đối với cùng một địa chỉ. Một thành phần có thể thay đổi vị trí trong mảng. Loại thành phần có thể thay đổi. Một thành phần cụ thể có thể bị thiếu trong phản hồi sau.

    Để xử lý mảng thành phần, bạn nên phân tích cú pháp phản hồi và chọn các giá trị thích hợp thông qua biểu thức. Hãy xem hướng dẫn cách phân tích cú pháp phản hồi.

  • postcode_localities[] là một mảng biểu thị tối đa 100 địa phương có trong một mã bưu chính. Thuộc tính này chỉ xuất hiện khi kết quả là một mã bưu chính chứa nhiều địa phương.
  • geometry chứa những thông tin sau:
    • location chứa vĩ độ, giá trị kinh độ được mã hoá địa lý. Đối với các lượt tra cứu địa chỉ thông thường, trường này thường là quan trọng nhất.
    • location_type lưu trữ dữ liệu bổ sung về vị trí đã chỉ định. Các giá trị sau hiện được hỗ trợ:

      • "ROOFTOP" cho biết kết quả trả về là một mã địa lý chính xác mà chúng tôi có thông tin vị trí chính xác đến độ chính xác của địa chỉ đường phố.
      • "RANGE_INTERPOLATED" cho biết kết quả trả về phản ánh giá trị gần đúng (thường là trên một con đường) được nội suy giữa hai điểm chính xác (chẳng hạn như các giao lộ). Kết quả nội suy thường được trả về khi không có mã địa lý trên mái nhà cho một địa chỉ đường.
      • "GEOMETRIC_CENTER" cho biết kết quả trả về là tâm hình học của một kết quả, chẳng hạn như đường đa tuyến (ví dụ: đường phố) hoặc đa giác (khu vực).
      • "APPROXIMATE" cho biết rằng kết quả được trả về là gần đúng.
    • viewport chứa khung nhìn được đề xuất để hiển thị kết quả được trả về, được chỉ định dưới dạng hai giá trị vĩ độ, kinh độ xác định góc southwestnortheast của hộp giới hạn khung nhìn. Thông thường, khung nhìn được dùng để đóng khung một kết quả khi hiển thị kết quả đó cho người dùng.
    • bounds (không bắt buộc được trả về) lưu trữ hộp giới hạn có thể chứa đầy đủ kết quả được trả về. Xin lưu ý rằng các giới hạn này có thể không khớp với khung nhìn được đề xuất. (Ví dụ: San Francisco bao gồm các đảo Farallon, về mặt kỹ thuật là một phần của thành phố, nhưng có thể không được trả về trong khung nhìn.)
  • plus_code (xem Mã vị trí mởmã cộng) là một tham chiếu vị trí được mã hoá, lấy từ các toạ độ vĩ độ và kinh độ, đại diện cho một khu vực: 1/8000 độ x 1/8000 độ (khoảng 14m x 14m ở đường xích đạo) trở xuống. Bạn có thể sử dụng plus code thay cho địa chỉ đường phố ở những nơi không có địa chỉ (những nơi không đánh số nhà hoặc không đặt tên đường). API không phải lúc nào cũng trả về mã cộng.

    Khi dịch vụ trả về một mã plus, mã này sẽ được định dạng dưới dạng mã toàn cục và mã phức hợp:

    • global_code là mã vùng gồm 4 ký tự và mã cục bộ dài hơn 6 ký tự (849VCWC8+R9).
    • compound_code là mã địa phương có độ dài từ 6 ký tự trở lên, có vị trí rõ ràng (CWC8+R9, Mountain View, CA, USA). Đừng phân tích cú pháp nội dung này bằng cách lập trình.
    Nếu có, API sẽ trả về cả mã toàn cục và mã phức hợp. Tuy nhiên, nếu kết quả ở một vị trí xa (ví dụ: đại dương hoặc sa mạc), thì chỉ mã chung mới được trả về.
  • partial_match cho biết trình dịch địa lý không trả về kết quả khớp chính xác cho yêu cầu ban đầu, mặc dù có thể khớp một phần của địa chỉ được yêu cầu. Bạn nên kiểm tra yêu cầu ban đầu để xem có lỗi chính tả và/hoặc địa chỉ chưa hoàn chỉnh hay không.

    Kết quả khớp một phần thường xảy ra đối với các địa chỉ đường phố không tồn tại trong địa phương mà bạn chuyển vào trong yêu cầu. Kết quả khớp một phần cũng có thể được trả về khi một yêu cầu khớp với 2 hoặc nhiều vị trí ở cùng một khu vực. Ví dụ: "Hillpar St, Bristol, UK" sẽ trả về kết quả khớp một phần cho cả đường Henry và Henrietta. Xin lưu ý rằng nếu một yêu cầu có thành phần địa chỉ bị sai chính tả, thì dịch vụ mã hoá địa lý có thể đề xuất một địa chỉ thay thế. Nội dung đề xuất được kích hoạt theo cách này cũng sẽ được đánh dấu là một kết quả trùng khớp một phần.

  • place_id là giá trị nhận dạng duy nhất có thể dùng với các API khác của Google. Ví dụ: bạn có thể sử dụng place_id trong yêu cầu API Địa điểm để lấy thông tin chi tiết về một doanh nghiệp địa phương, chẳng hạn như số điện thoại, giờ mở cửa, bài đánh giá của người dùng và nhiều thông tin khác. Xem tổng quan về mã địa điểm.

Loại địa chỉ và loại thành phần địa chỉ

Mảng types[] trong kết quả cho biết loại địa chỉ. Ví dụ về loại địa chỉ bao gồm địa chỉ đường phố, quốc gia hoặc thực thể chính trị. Ngoài ra còn có một mảng types[] trong address_components[], cho biết loại của từng phần địa chỉ. Ví dụ: số nhà hoặc quốc gia. (Dưới đây là danh sách đầy đủ các loại.) Địa chỉ có thể có nhiều loại. Các loại này có thể được coi là "thẻ". Ví dụ: nhiều thành phố được gắn thẻ bằng loại politicallocality.

Các loại sau đây được hỗ trợ và trả về bởi trình định vị địa lý trong cả loại địa chỉ và mảng loại thành phần địa chỉ:

  • street_address cho biết địa chỉ đường phố chính xác.
  • route cho biết một tuyến đường được đặt tên (chẳng hạn như "US 101").
  • intersection biểu thị một giao lộ chính, thường là hai con đường chính.
  • political cho biết một thực thể chính trị. Thông thường, loại này cho biết một đa giác của một số cơ quan hành chính dân sự.
  • country cho biết pháp nhân chính trị quốc gia và thường là loại đơn đặt hàng cao nhất mà Bộ mã hoá địa lý trả về.
  • administrative_area_level_1 cho biết có pháp nhân dân sự cấp thứ nhất ở cấp thấp hơn cấp quốc gia. Tại Hoa Kỳ, các cấp quản lý này là tiểu bang. Không phải quốc gia nào cũng thể hiện các cấp hành chính này. Trong hầu hết các trường hợp, tên ngắnAdministrative_area_level_1 của chúng tôi sẽ gần khớp với các phân mục ISO 3166-2 và các danh sách được lưu hành rộng rãi khác; tuy nhiên, điều này không được đảm bảo vì kết quả mã hoá địa lý của chúng tôi dựa trên nhiều tín hiệu và dữ liệu vị trí.
  • administrative_area_level_2 cho biết một thực thể dân sự cấp hai thấp hơn cấp quốc gia. Tại Hoa Kỳ, các cấp hành chính này là hạt. Không phải quốc gia nào cũng thể hiện các cấp hành chính này.
  • administrative_area_level_3 cho biết một thực thể dân sự cấp ba thấp hơn cấp quốc gia. Loại này thể hiện một phân cấp dân sự nhỏ. Không phải quốc gia nào cũng có các cấp hành chính này.
  • administrative_area_level_4 cho biết có pháp nhân dân sự cấp thứ tư ở cấp thấp hơn cấp quốc gia. Loại này thể hiện một phân cấp dân sự nhỏ. Không phải quốc gia nào cũng thể hiện các cấp hành chính này.
  • administrative_area_level_5 cho biết là một pháp nhân dân sự cấp 5 ở cấp thấp hơn cấp quốc gia. Loại này cho biết một đơn vị hành chính cấp dưới. Không phải quốc gia nào cũng thể hiện các cấp hành chính này.
  • administrative_area_level_6 cho biết một pháp nhân dân sự cấp 6 thấp hơn cấp quốc gia. Loại này cho biết một đơn vị hành chính cấp dưới. Không phải quốc gia nào cũng thể hiện các cấp hành chính này.
  • administrative_area_level_7 cho biết một pháp nhân dân sự cấp 7 ở cấp thấp hơn cấp quốc gia. Loại này cho biết một đơn vị hành chính cấp thấp. Không phải quốc gia nào cũng có các cấp hành chính này.
  • colloquial_area cho biết tên thay thế thường dùng cho thực thể.
  • locality cho biết một thực thể chính trị của thành phố hoặc thị trấn được hợp nhất.
  • sublocality cho biết một pháp nhân dân sự cấp cao nhất thuộc một địa phương. Đối với một số vị trí, bạn có thể nhận được một trong các loại bổ sung: sublocality_level_1 đến sublocality_level_5. Mỗi cấp quận/huyện là một pháp nhân dân sự. Số lớn hơn cho biết khu vực địa lý nhỏ hơn.
  • neighborhood biểu thị một vùng lân cận được đặt tên.
  • premise cho biết một vị trí được đặt tên, thường là một toà nhà hoặc một tập hợp các toà nhà có tên chung.
  • subpremise cho biết một thực thể có thể định địa chỉ ở cấp dưới cơ sở, chẳng hạn như căn hộ, phòng hoặc căn hộ.
  • plus_code cho biết một tệp tham chiếu vị trí được mã hoá, bắt nguồn từ vĩ độ và kinh độ. Mã Cộng có thể được dùng để thay thế cho địa chỉ đường phố ở những vị trí không tồn tại chúng (nơi toà nhà không được đánh số hoặc đường phố không được đặt tên). Hãy xem https://plus.codes để biết thông tin chi tiết.
  • postal_code cho biết mã bưu chính dùng để gửi thư bưu chính trong quốc gia.
  • natural_feature cho biết một đặc điểm tự nhiên nổi bật.
  • airport cho biết một sân bay.
  • park biểu thị một công viên có tên.
  • point_of_interest cho biết một địa điểm yêu thích đã được đặt tên. Thông thường, những "POI" này là các thực thể địa phương nổi bật không dễ dàng phù hợp trong một danh mục khác, chẳng hạn như "Toà nhà Empire State" hoặc "Tháp Eiffel".

Danh sách loại trống cho biết không có loại nào được biết cho thành phần địa chỉ cụ thể, ví dụ: Lieu-dit ở Pháp.

Ngoài những thành phần nêu trên, thành phần địa chỉ có thể bao gồm các loại được liệt kê ở đây. Danh sách này chưa đầy đủ và có thể thay đổi.

  • floor cho biết tầng của địa chỉ toà nhà.
  • establishment thường cho biết một địa điểm chưa được phân loại.
  • landmark cho biết một địa điểm lân cận được dùng làm tệp tham chiếu để hỗ trợ điều hướng.
  • point_of_interest cho biết một địa điểm yêu thích đã được đặt tên.
  • parking cho biết bãi đỗ xe hoặc nhà đỗ xe.
  • post_box cho biết một hộp thư bưu chính cụ thể.
  • postal_town cho biết một nhóm các khu vực địa lý, chẳng hạn như localitysublocality, được dùng cho địa chỉ gửi thư ở một số quốc gia.
  • room biểu thị phòng có địa chỉ tòa nhà.
  • street_number cho biết số nhà chính xác.
  • bus_station, train_stationtransit_station cho biết vị trí của trạm xe buýt, trạm xe lửa hoặc trạm phương tiện công cộng.

Xu hướng khung nhìn

Trong yêu cầu Mã hoá địa lý, bạn có thể hướng dẫn dịch vụ Mã hoá địa lý ưu tiên kết quả trong một khung nhìn nhất định (được biểu thị dưới dạng một hộp giới hạn). Bạn thực hiện việc này trong URL yêu cầu bằng cách đặt tham số bounds.

Tham số bounds xác định toạ độ vĩ độ/kinh độ của các góc tây nam và đông bắc của hộp giới hạn này bằng cách sử dụng ký tự dấu gạch chéo (|) để phân tách các toạ độ.

Ví dụ: mã địa lý cho "Washington" thường trả về tiểu bang Washington của Hoa Kỳ:

Yêu cầu:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY

Phản hồi:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            },
            "location" : {
               "lat" : 47.7510741,
               "lng" : -120.7401385
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            }
         },
         "place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

Tuy nhiên, việc thêm đối số bounds xác định một hộp giới hạn xung quanh phần đông bắc của Hoa Kỳ sẽ khiến mã địa lý này trả về thành phố Washington, D.C.:

Yêu cầu:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY

Phản hồi:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "Washington",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "District of Columbia",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "DC",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, DC, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            },
            "location" : {
               "lat" : 38.9071923,
               "lng" : -77.03687069999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            }
         },
         "place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Xu hướng khu vực

Trong yêu cầu Mã hoá địa lý, bạn có thể hướng dẫn dịch vụ Mã hoá địa lý trả về kết quả thiên vị cho một khu vực cụ thể bằng cách sử dụng tham số region. Tham số này nhận đối số ccTLD (miền cấp cao nhất theo mã quốc gia) chỉ định độ lệch theo khu vực. Hầu hết các mã ccTLD (miền cấp cao nhất theo mã quốc gia) đều giống với mã ISO 3166-1, trừ một số ngoại lệ đáng chú ý. Ví dụ: ccTLD của Vương quốc Anh là "uk" (.co.uk) trong khi mã ISO 3166-1 của quốc gia này là "gb" (về mặt kỹ thuật là thực thể "Vương quốc Anh và Bắc Ireland").

Kết quả mã hoá địa lý có thể không chính xác đối với mọi miền mà ứng dụng Google Maps chính được ra mắt. Xin lưu ý rằng việc thiên vị chỉ ưu tiên kết quả cho một miền cụ thể; nếu có kết quả phù hợp hơn bên ngoài miền này, thì các kết quả đó có thể được đưa vào.

Ví dụ: mã địa lý cho "Toledo" trả về kết quả này, vì miền mặc định cho API mã hoá địa lý được đặt thành Hoa Kỳ. Yêu cầu:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

Phản hồi:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Yêu cầu Địa chỉ được mã hoá địa lý cho "Toledo" với region=es (Tây Ban Nha) sẽ trả về thành phố Tây Ban Nha.

Yêu cầu:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

Phản hồi:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "TO",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Castile-La Mancha",
               "short_name" : "CM",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Lọc thành phần

Trong phản hồi Mã hoá địa lý, API mã hoá địa lý có thể trả về các kết quả địa chỉ bị hạn chế cho một khu vực cụ thể. Bạn có thể chỉ định quy định hạn chế này bằng bộ lọc components. Một bộ lọc bao gồm một danh sách các cặp component:value được phân tách bằng dấu gạch đứng (|). Các giá trị bộ lọc hỗ trợ cùng một phương pháp sửa lỗi chính tả và so khớp một phần như các yêu cầu Mã hoá địa lý khác. Nếu trình mã hoá địa lý tìm thấy một phần khớp với bộ lọc thành phần, thì phản hồi sẽ chứa trường partial_match.

components có thể được lọc bao gồm:

  • postal_code khớp với postal_codepostal_code_prefix.
  • country khớp với tên quốc gia hoặc mã quốc gia ISO 3166-1 gồm hai chữ cái. API này tuân theo tiêu chuẩn ISO để xác định các quốc gia và quá trình lọc hoạt động hiệu quả nhất khi sử dụng mã ISO tương ứng của quốc gia đó.

Bạn có thể sử dụng components sau đây để tác động đến kết quả, nhưng hệ thống sẽ không thực thi:

  • route khớp với tên dài hoặc tên ngắn của một tuyến đường.
  • locality khớp với các loại localitysublocality.
  • administrative_area khớp với tất cả các cấp administrative_area.

Lưu ý về tính năng lọc thành phần:

  • Đừng lặp lại các bộ lọc thành phần này trong các yêu cầu, nếu không API sẽ trả về Invalid_request: country, postal_code, route
  • Nếu yêu cầu chứa các bộ lọc thành phần lặp lại, API sẽ đánh giá các bộ lọc đó là AND, chứ không phải OR.
  • Kết quả giống với kết quả trên Google Maps nên đôi khi mang lại phản hồi ZERO_RESULTS không mong muốn. Việc sử dụng tính năng Tự động hoàn thành địa điểm có thể mang lại kết quả tốt hơn trong một số trường hợp sử dụng. Để tìm hiểu thêm, hãy xem câu hỏi thường gặp này.
  • Đối với mỗi thành phần địa chỉ, hãy chỉ định thành phần đó trong tham số address hoặc trong bộ lọc components, nhưng không được chỉ định cả hai. Việc chỉ định cùng một giá trị trong cả hai có thể dẫn đến ZERO_RESULTS.

Mã địa lý cho "High St, Hastings" với components=country:GB sẽ trả về kết quả ở Hastings, Anh thay vì ở Hastings-On-Hudson, Hoa Kỳ.

Yêu cầu:

https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY

Phản hồi:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "High Street",
               "short_name" : "High St",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Hastings",
               "short_name" : "Hastings",
               "types" : [ "postal_town" ]
            },
            {
               "long_name" : "East Sussex",
               "short_name" : "East Sussex",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "GB",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "TN34 3EY",
               "short_name" : "TN34 3EY",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "High St, Hastings TN34 3EY, UK",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            },
            "location" : {
               "lat" : 50.85830319999999,
               "lng" : 0.5924594
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

Yêu cầu mã địa lý cho địa phương "Santa Cruz" bằng components=country:ES sẽ trả về Santa Cruz de Tenerife ở Quần đảo Canary, Tây Ban Nha.

Yêu cầu:

https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY

Phản hồi:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canary Islands",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Tính năng lọc thành phần chỉ trả về phản hồi ZERO_RESULTS nếu bạn cung cấp các bộ lọc loại trừ nhau.

Yêu cầu:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

Phản hồi:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

Bạn có thể tạo các truy vấn hợp lệ mà không cần tham số địa chỉ bằng cách sử dụng bộ lọc components. (Khi mã hoá địa lý địa chỉ đầy đủ, cần có tham số address nếu yêu cầu chứa tên và số toà nhà.)

Yêu cầu:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

Phản hồi:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annankatu",
               "short_name" : "Annankatu",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsinki",
               "short_name" : "HKI",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00101",
               "short_name" : "00101",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annankatu, 00101 Helsinki, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}