Trang này được dịch bởi Cloud Translation API.

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

Yêu cầu

Yêu cầu API mã hoá địa lý có dạng 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 đầu ra ở dạng Ký hiệu đối tượng JavaScript (JSON); hoặc
xml biểu thị kết quả ở định dạng XML

HTTPS là bắt buộc.

Một số tham số là bắt buộc, trong khi một số khác là 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ự ký hiệu và (&).

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

Tham số mã hóa địa lý (tra cứu 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ã địa lý. Nêu rõ các địa chỉ theo định dạng mà 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 các thành phần địa chỉ bổ sung như tên doanh nghiệp và số nhà, số phòng hoặc số tầng. 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 được thoát khỏi %20):
```
address=24%20Sussex%20Drive%20Ottawa%20ON
```
Định dạng mã cộng như minh hoạ dưới đây (dấu cộng là ký tự thoát URL thành %2B còn dấu cách là URL được thoát khỏi URL %20):
- mã chung là mã vùng gồm 4 ký tự và mã địa phương gồm 6 ký tự trở lên (849VCWC8+R9 là 849VCWC8%2BR9).
- mã phức hợp là mã địa phương gồm 6 ký tự trở lên và có vị trí rõ ràng (CWC8+R9 Mountain View, CA, Hoa Kỳ 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 một dấu gạch đứng (|). Bộ lọc thành phần cũng được chấp nhận làm 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 các kết quả từ bộ mã hoá địa lý. Xem thêm thông tin về tính năng lọc thành phần ở bên dưới.
key — Khoá API của ứng dụng. Khoá này giúp xác định ứng dụng của bạn để 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 để được hướng dẫn thêm.

Tham số không bắt buộc trong một yêu cầu mã hoá địa lý:

bounds — Hộp giới hạn của khung nhìn mà trong đó việc gán mã địa lý sẽ nổi bật hơn. Tham số này sẽ chỉ ảnh hưởng (chứ không hạn chế hoàn toàn) kết quả từ bộ mã hoá địa lý. (Để biết thêm thông tin, hãy xem phần Xu hướng khung hiển thị bên dưới.)
language – Ngôn ngữ sử dụng để trả về kết quả.
- Xem danh sách ngôn ngữ được hỗ trợ. Google thường cập nhật các ngôn ngữ được hỗ trợ, nên danh sách này có thể chưa đầy đủ.
- Nếu language không được cung cấp, bộ mã hoá đị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ữ bản địa của miền mà yêu cầu được gửi đi.
- Bộ mã hoá địa lý sẽ cố gắng hết sức để cung cấp một địa chỉ đường phố mà cả người dùng và người dân địa phương có thể đọc được. Để đạt được mục tiêu đó, phương thức này trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một tập lệnh mà người dùng có thể đọc được nếu cần, đồng thời 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ả cá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 không có tên 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ề, cũng như thứ tự mà các kết quả được trả về. Bộ mã hoá địa lý diễn giải các từ viết tắt theo cách khác nhau tuỳ theo ngôn ngữ, chẳng hạn như cách viết tắt cho các loại đường phố hoặc từ đồng nghĩa có thể hợp lệ ở một ngôn ngữ nhưng không hợp lệ trong ngôn ngữ khác. Ví dụ: utca và tér là các từ đồng nghĩa tương ứng với đường phố và hình vuông trong tiếng Hungary.
region — Mã vùng, được chỉ định dưới dạng một ccTLD (miền cấp cao nhất) có hai ký tự. Tham số này sẽ chỉ ảnh hưởng (chứ không hạn chế hoàn toàn) kết quả từ bộ mã hoá địa lý. (Để biết thêm thông tin, hãy xem phần Xu hướng khu vực bên dưới.) Tham số này cũng có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.
components – Một bộ lọc thành phần có các phần tử được phân tách bằng một 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ý. Xem thêm thông tin về tính năng lọc thành phần ở bên dưới.
extra_computations – Giá trị duy nhất được phép cho tham số này là ADDRESS_DESCRIPTORS. Hãy xem mã mô tả địa chỉ để biết thêm chi tiết.

Phản hồi

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

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

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

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

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

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&amp;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 2 phần tử gốc:

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

Nói chung, chỉ một mục nhập trong mảng "results" được trả về cho các lượt tra cứu địa chỉ, mặc dù bộ mã hoá địa lý có thể trả về nhiều 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>

Hãy 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 theo yêu cầu. Hãy xem phần 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ỉ và thông tin hình học được mã hoá địa lý.

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 cần được cẩn thận để bạn tham chiếu 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ế được đề xuất cho quá trình xử lý đầu ra.

Kết quả XML được gói trong phần tử <GeocodeResponse> gốc.
JSON biểu thị các mục có nhiều phần tử bằng các mảng số nhiều (types), trong khi XML biểu thị các mục này bằng cách sử dụng nhiều phần tử số ít (<type>).
Các phần tử trống được biểu thị qua các mảng trống trong JSON, nhưng do không có 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ả nào 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 khiến 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à ít nhất một mã địa lý được trả về.
"ZERO_RESULTS" cho biết mã địa lý đã 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 bộ mã hoá địa lý được chuyển vào một address không tồn tại.
OVER_DAILY_LIMIT cho biết bất kỳ trường hợp nào sau đây:
- Khoá API bị thiếu hoặc không hợp lệ.
- Bạn chưa bật tính năng thanh toán trên tài khoản của mình.
- Đã vượt quá giới hạn sử dụng tự đặt.
- Phương thức thanh toá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 mục 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 của mình.
"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 rằng 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 bộ mã hoá địa lý trả về một mã trạng thái khác với OK, có thể có thêm một trường error_message trong đối tượng phản hồi Mã hoá địa lý. Trường này chứa thông tin chi tiết hơn về lý do dẫn đến mã trạng thái đã cho.

Kết quả

Khi bộ mã hoá địa lý trả về kết quả, bộ mã hoá sẽ đặt các kết quả đó vào một mảng results (JSON). Ngay cả khi bộ mã hoá địa lý không trả về kết quả nào (chẳng hạn như khi địa chỉ không tồn tại), bộ mã hoá vẫn trả về một mảng results trống. (Phản hồi XML không có 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 từ 0 thẻ trở lên giúp xác định loại tính năng được trả về trong kết quả. Ví dụ: một mã địa lý "Chicago" trả về "địa phương" cho biết rằng "Chicago" là một thành phố, đồng thời 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ó kiểu nào đã 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 bài viết 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.
Thông thường, địa chỉ này tương đương với địa chỉ bưu điện. 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 các quy định hạn chế về việc cấp phép.

Địa chỉ được định dạng bao gồm một hoặc nhiều thành phần địa chỉ về mặt logic. 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" (tuyến đường), "New York" (thành phố) và "NY" (tiểu bang của Hoa Kỳ).

Không phân tích cú pháp địa chỉ đã định dạng theo cách 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ẻ (có trong phản hồi của API) cùng vớ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à nội dung mô tả văn bản đầ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 văn bản viết tắt cho thành phần địa chỉ, nếu có. Ví dụ: một thành phần địa chỉ cho tiểu bang Alaska có thể có long_name là "Alaska" và short_name là "AK" bằng cách sử dụng chữ viết tắt của bưu điện gồm 2 chữ cái.
Hãy lưu ý các thông tin thực tế sau 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 bao gồm tất cả pháp nhân chính trị có chứa địa chỉ, ngoài các pháp nhân có trong formatted_address. Để truy xuất tất cả các pháp nhân chính trị có chứa một địa chỉ cụ thể, bạn nên sử dụng mã địa lý ngược, chuyển vĩ độ/kinh độ của địa chỉ dưới dạng tham số tới yêu cầu.
- Định dạng của phản hồi không được đảm bảo giữ nguyên 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 của 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ị phù hợp thông qua biểu thức. Xem hướng dẫn để phân tích cú pháp một 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. Thông tin này chỉ xuất hiện khi kết quả là một mã bưu chính chứa nhiều khu vực.
geometry chứa những thông tin sau:
- location chứa giá trị kinh độ, vĩ độ được mã hoá địa lý. Đối với các hoạt động tra cứu địa chỉ thông thường, trường này thường là trường quan trọng nhất.
- location_type lưu trữ dữ liệu bổ sung về vị trí đã chỉ định. Những giá trị sau đây hiện được hỗ trợ:
  - "ROOFTOP" cho biết rằng 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 rằng kết quả được trả về phản ánh một giá trị gần đúng (thường trên một con đường) được nội suy giữa hai điểm chính xác (chẳng hạn như 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 phố.
  - "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ư hình nhiều đường (ví dụ: đường phố) hoặc đa giác (khu vực).
  - "APPROXIMATE" cho biết kết quả trả về chỉ là gần đúng.
- viewport chứa khung nhìn đề xuất để hiển thị kết quả được trả về, được chỉ định dưới dạng hai giá trị vĩ độ và kinh độ để xác định góc southwest và northeast của hộp giới hạn khung nhìn. Nhìn chung, khung nhìn được dùng để đóng khung hình 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ề. Lưu ý rằng những giới hạn này có thể không khớp với khung nhìn đề xuất. (Ví dụ: San Francisco bao gồm các hòn đảo Farllon. Về mặt kỹ thuật, những hòn đảo này là một phần của thành phố nhưng có lẽ không được trả về trong khung nhìn.)
plus_code (xem Mã vị trí mở và mã cộng) là một tham chiếu vị trí được mã hoá, lấy từ toạ độ vĩ độ và kinh độ, đại diện cho một khu vực: 1/8.000 độ x 1/8.000 độ (khoảng 14 m x 14 m tại đường xích đạo) hoặc nhỏ hơn. Mã Cộng có thể được dùng để thay thế cho địa chỉ đường phố ở những nơi không có địa chỉ (nơi toà nhà không được đánh số hoặc đường phố không được đặt tên). 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ã cộng, mã đó sẽ được định dạng dưới dạng mã chung và mã phức hợp:
- global_code là mã vùng gồm 4 ký tự và mã địa phương gồm 6 ký tự trở lên (849VCWC8+R9).
- compound_code là mã địa phương gồm 6 ký tự trở lên và có vị trí rõ ràng (CWC8+R9, Mountain View, CA, Hoa Kỳ). Không được phân tích cú pháp nội dung này theo chương trình.
Nếu có, API sẽ trả về cả mã chung 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ì hệ thống chỉ có thể trả về mã toàn cầu.
partial_match cho biết rằng bộ mã hoá đị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ù bộ mã hoá có thể khớp với một phần địa chỉ được yêu cầu. Bạn nên kiểm tra lỗi chính tả trong yêu cầu ban đầu và/hoặc địa chỉ chưa hoàn chỉnh.

Kết quả khớp một phần thường xảy ra nhất với địa chỉ đường phố không tồn tại ở vị trí mà bạn chuyển trong yêu cầu. Hệ thống cũng có thể trả về kết quả trùng khớp một phần khi một yêu cầu khớp với hai hoặc nhiều vị trí ở cùng một địa phương. Ví dụ: "Hillpar St, Bristol, UK" sẽ trả về kết quả khớp một phần cho cả Henry Street và Jetpack Street. Xin lưu ý rằng nếu một yêu cầu có chứa thành phần địa chỉ sai chính tả, thì dịch vụ mã hoá địa lý có thể đề xuất một địa chỉ thay thế. Các đề xuất được kích hoạt theo cách này cũng sẽ được đánh dấu là 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 để nhận 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. Hãy 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ỉ: địa chỉ đường phố, quốc gia hoặc pháp nhân chính trị. Ngoài ra, address_components[] cũng có một mảng types[] cho biết loại của từng phần của đị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 political và loại locality.

Bộ mã hoá địa lý hỗ trợ và trả về các loại sau trong cả mảng 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 cho biết một nút giao chính, thường có hai con đường chính.
political cho biết một pháp nhân chính trị. Thông thường, loại này biểu thị một đa giác của một số 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 được Bộ mã hoá địa lý trả về.
administrative_area_level_1 cho biết pháp nhân dân sự cấp thứ nhất dưới cấp quốc gia. Tại Hoa Kỳ, các cấp hành chính này được coi là tiểu bang. Không phải quốc gia nào cũng quy định các cấp hành chính này. Trong hầu hết các trường hợp, tên ngắn copyright_area_level_1 sẽ khớp gần 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ã hóa đị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 pháp nhân 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à các hạt. Không phải quốc gia nào cũng quy định các cấp hành chính này.
administrative_area_level_3 cho biết một pháp nhân dân sự cấp ba cấp thấp hơn cấp quốc gia. Loại này cho biết một phân cấp dân cư nhỏ. Không phải quốc gia nào cũng quy định các cấp hành chính này.
administrative_area_level_4 cho biết một pháp nhân dân sự cấp 4 dưới cấp quốc gia. Loại này cho biết một phân cấp dân cư nhỏ. Không phải quốc gia nào cũng quy định các cấp hành chính này.
administrative_area_level_5 cho biết pháp nhân dân sự cấp năm dưới cấp quốc gia. Loại này cho biết một phân cấp dân cư nhỏ. Không phải quốc gia nào cũng quy định các cấp hành chính này.
administrative_area_level_6 cho biết pháp nhân dân sự bậc 6 dưới cấp quốc gia. Loại này cho biết một phân cấp dân cư nhỏ. Không phải quốc gia nào cũng quy định các cấp hành chính này.
administrative_area_level_7 cho biết pháp nhân dân sự bậc 7 dưới cấp quốc gia. Loại này cho biết một phân cấp dân cư nhỏ. Không phải quốc gia nào cũng quy định 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 pháp nhân chính trị được thành lập ở thành phố hoặc thị trấn.
sublocality cho biết một pháp nhân dân sự bậc nhất ở dưới 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 thành sublocality_level_5. Mỗi cấp địa phương là một pháp nhân dân sự. Số lớn hơn nghĩa là khu vực địa lý nhỏ hơn.
neighborhood cho biế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 tập hợp các toà nhà có cùng tên
subpremise cho biết thực thể thứ nhất bên dưới một vị trí được đặt tên, thường là một toà nhà số ít trong một tập hợp các toà nhà có cùng một tên
plus_code cho biết tham chiếu vị trí đã mã hoá, lấy từ vĩ độ và kinh độ. Mã Cộng có thể được dùng để thay thế cho địa chỉ đường phố ở những nơi không tồn tại (nơi toà nhà không được đánh số hoặc đường 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ư qua đường bưu điện trong quốc gia.
natural_feature cho biết một đối tượng tự nhiên nổi bật.
airport cho biết sân bay.
park cho biết một công viên được đặt tên.
point_of_interest cho biết địa điểm yêu thích đã đặt tên. Thông thường, các "POI" này là các thực thể địa phương nổi bật và không dễ nằm vừa trong danh mục khác, chẳng hạn như "Toà nhà Empire State" hoặc "Eiffer Tower".

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

Ngoài các thành phần ở trên, các 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ỉ tòa nhà.
establishment thường là một địa điểm chưa được phân loại.
landmark cho biết địa điểm lân cận được dùng làm tệp đối chiếu để hỗ trợ chỉ đường.
point_of_interest cho biết địa điểm yêu thích đã đặt tên.
parking cho biết bãi đỗ xe hoặc bãi đỗ xe.
post_box cho biết một hộp thư cụ thể.
postal_town cho biết một nhóm các khu vực địa lý, chẳng hạn như locality và sublocality, được sử dụng cho địa chỉ gửi thư ở một số quốc gia.
room cho biết phòng trong địa chỉ toà nhà.
street_number cho biết số nhà chính xác.
bus_station, train_station và transit_station cho biết vị trí của xe buýt, tàu hoả hoặc trạm dừng phương tiện công cộng.

Xu hướng khung nhìn

Trong yêu cầu Mã hóa địa lý, bạn có thể hướng dẫn dịch vụ Mã hóa địa lý ưu tiên các kết quả trong một khung nhìn nhất định (được biểu thị dưới dạng hộp giới hạn). Bạn có thể 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 phía 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ự gạch đứng (|) để phân tách các toạ độ.

Ví dụ: một mã địa lý cho "COUNTRY" 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 hộp giới hạn xung quanh phần đông bắc của Hoa Kỳ sẽ dẫn đến việc mã địa lý 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 vùng

Trong yêu cầu Mã hóa địa lý, bạn có thể ra lệnh cho dịch vụ Mã hóa địa lý trả về kết quả sai lệch cho một khu vực cụ thể bằng cách sử dụng tham số region. Thông số này sẽ lấy một đối số ccTLD (miền cấp cao nhất theo mã quốc gia) chỉ định độ lệch 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ố trường hợp 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 Vương quốc Anh là "gb" (về mặt kỹ thuật là tên pháp nhân của "Vương quốc Anh và Bắc Ireland").

Kết quả mã hoá địa lý có thể sai lệch đối với mọi miền mà ứng dụng Google Maps chính được khởi chạy. Xin lưu ý rằng xu hướng chỉ ưu tiên kết quả cho một miền cụ thể; nếu có nhiều kết quả có liên quan hơn bên ngoài miền này, thì các kết quả đó có thể được bao gồm.

Ví dụ: một mã địa lý cho "Toledo" sẽ 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 mã hoá địa lý cho "Toledo" bằng region=es (Tây Ban Nha) sẽ trả về thành phố của 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ề kết quả địa chỉ bị giới hạn cho một khu vực cụ thể. Bạn có thể chỉ định quy định hạn chế bằng cách sử dụng bộ lọc components. Bộ lọc bao gồm danh sách các cặp component:value được phân tách bằng một dấu gạch đứng (|). Giá trị bộ lọc hỗ trợ các phương thức sửa lỗi chính tả và so khớp một phần giống như các yêu cầu Mã hoá địa lý khác. Nếu bộ mã hoá địa lý tìm thấy kết quả trùng khớp một phần với một 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_code và postal_code_prefix.
country khớp với tên quốc gia hoặc mã quốc gia gồm 2 chữ cái theo tiêu chuẩn ISO 3166-1. API này tuân theo tiêu chuẩn ISO để xác định các quốc gia và bộ lọc hoạt động hiệu quả nhất khi sử dụng mã ISO tương ứng của quốc gia đó.
Lưu ý: Nếu bạn nhận được kết quả không mong muốn với mã quốc gia, hãy xác minh rằng bạn đang sử dụng mã có chứa các quốc gia, vùng lãnh thổ phụ thuộc và khu vực địa lý đặc biệt mà bạn dự định sử dụng. Bạn có thể xem thông tin về mã trên Wikipedia: Danh sách mã quốc gia theo tiêu chuẩn ISO 3166 hoặc Nền tảng duyệt web trực tuyến ISO.

components sau đây có thể được dùng để tác động đến kết quả, nhưng sẽ không được 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 loại locality và sublocality.
administrative_area khớp với tất cả các cấp administrative_area.

Lưu ý về cách 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, thì API sẽ đánh giá các bộ lọc đó dưới dạng AND, chứ không phải OR.
Kết quả phù hợp với Google Maps và đôi khi mang lại phản hồi ZERO_RESULTS ngoài dự kiế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 chúng trong tham số address hoặc trong bộ lọc components, chứ không được chỉ định cả hai. Việc chỉ định cùng giá trị cho cả 2 giá trị có thể dẫn đến ZERO_RESULTS.

Một mã địa lý cho "High St, Hastings" với components=country:GB sẽ trả về kết quả tại 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"
}

Một yêu cầu mã địa lý cho vị trí "Santa Cruz" với components=country:ES trả về Santa Ruz 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ừ lẫn 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ý cho một địa chỉ đầy đủ, bạn 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"
}