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 kết quả ở định dạng XML

HTTPS là bắt buộc.

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ự và (&).

Phần còn lại của trang này mô tả riêng về 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 plus code mà bạn muốn mã hoá địa lý. Chỉ định các địa chỉ theo định dạng sử dụng bởi dịch vụ bưu chính quốc gia của quốc gia có liên quan. Thông tin khác các yếu tố địa chỉ như tên doanh nghiệp và số phòng, số phòng hoặc số tầng nên tránh. Các phần tử địa chỉ đường phố phải được phân tách bằng dấu cách (được hiển thị dưới dạng mã thoát url cho %20):

  address=24%20Sussex%20Drive%20Ottawa%20ON

  Định dạng mã cộng như hiển thị dưới đây (dấu cộng được thoát url cho %2B và dấu cách là ký tự thoát url cho %20):
  • mã toàn cầu là mã vùng gồm 4 ký tự và có 6 ký tự trở lên mã địa phương (849VCWC8+R9 là 849VCWC8%2BR9).
  • mã kết hợp là một mã cục bộ gồm 6 ký tự trở lên với vị trí rõ ràng (CWC8+R9 Mountain View, CA, Hoa Kỳ là CWC8%2BR9%20Mountain%20View%20CA%20USA).
  
  --HOẶC--
  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 chéo (|). Bộ lọc thành phần cũng được chấp nhận dưới dạng 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 component:value ghép nối và hạn chế hoàn toàn kết quả từ bộ mã hoá địa lý. Xem thêm thông tin về lọc thành phần ở bên dưới.
• key – Khoá API của ứng dụng. 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 phần Câu hỏi thường gặp về hướng dẫn bổ sung.

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

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

  extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Phản hồi

Phản hồi mã hoá địa lý được trả về ở định dạng được biểu thị bằng cờ output 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 một json nội dung phản hồi cho thắc mắc về địa chỉ "1600 Amphitheatre Parkway, Mountain View, Canada".

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ờ XML output:

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.

{
    "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"
}

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

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ý hiện 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à vào lúc ít nhất một mã địa lý được trả về.
• "ZERO_RESULTS" cho biết mã địa lý đã được mã hoá 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ệ.
  • 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 mức 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).

  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).
• "UNKNOWN_ERROR" cho biết rằng yêu cầu không thể được xử lý do lỗi máy chủ. Yêu cầu có thể thành công nếu bạn hãy 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ông phải là OK, có thể có Trường error_message trong đối tượng phản hồi Mã hoá địa lý. Trường này chứa nhiều thông tin chi tiết về lý do tạo ra một mã trạng thái cụ thể.

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 results (JSON) . Ngay cả khi bộ mã hoá địa lý trả về không có kết quả nào (chẳng hạn như nếu không có địa chỉ), thì bộ mã hoá vẫn sẽ trả về một mảng results trống. (Phản hồi XML không chứa hoặc có nhiều hơn <result> elements.)

Một kết quả thông thường có chứa các trường sau:

• Mảng types[] cho biết loại của giá trị được trả về kết quả. Mảng này chứa một tập hợp không 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" giá trị trả về "địa phương" điều này cho biết rằng "Chicago" là 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ó các loại trống khi không có loại xác định nào cho thành phần địa chỉ đó. API có thể thêm các giá trị kiểu mới nếu cần. Để biết thêm thông tin, hãy xem phần Các loại địa chỉ và thành phần địa chỉ.
• formatted_address là một chuỗi chứa thông tin con người có thể đọc được địa chỉ 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. Lưu ý rằng một số quốc gia khác (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 do các quy định hạn chế về giấy phép.

  Địa chỉ được định dạng bao gồm một hoặc nhiều địa chỉ theo logic thành phần. Ví dụ: địa chỉ "111 8th Avenue, New York, NY" bao gồm các thành phần sau: "111" (số nhà), "Đại lộ số 8" (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 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 tham số 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 đị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 địa chỉ thành phần, nếu có. Ví dụ: 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 theo mã bưu chính gồm 2 chữ cái.

  Vui lòng lưu ý những thông tin sau về address_components[] mảng:

  • Mảng thành phần địa chỉ có thể chứa nhiều thành phần hơn so với formatted_address.
  • Mảng này không nhất thiết phải bao gồm tất cả các pháp nhân chính trị chứa địa chỉ, ngoài những địa chỉ được nêu 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 yêu cầu. Cụ thể, số lượng address_components sẽ khác nhau tuỳ theo địa chỉ được yêu cầu và có thể thay đổi theo thời gian đối với cùng đị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 câu trả lờ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. Xem hướng dẫn về 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 khu vực có trong 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 các thông tin sau:
  • location chứa giá trị vĩ độ, kinh độ được mã hoá địa lý. Bình thường tra cứu địa chỉ, 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í được chỉ định. Chiến lược phát hành đĩa đơn 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 rằng kết quả được trả về phản ánh phép tính gần đúng (thường trên đường) được nội suy giữa hai điểm chính xác (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 con phố của bạn.
    • "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ả trả về chỉ là kết quả 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 southwest và northeast 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 phải 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 các giới hạn này có thể không phù hợp với khung nhìn đề xuất. (Ví dụ: San Francisco có Quần đảo Farallon về mặt kỹ thuật là một phần của thành phố nhưng có lẽ không nên được trả về trong khung nhìn.)
• plus_code (xem Mở mã vị trí và mã cộng) là mã đã mã hoá tham chiếu vị trí (lấy từ vĩ độ và kinh độ) đại diện cho một diện tích: 1/8000 của độ x 1/8000 của độ (khoảng 14m x 14m tại đường xích đạo) hoặc nhỏ hơn. 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ã cộng, mã đó sẽ được định dạng thành mã toàn cục và mã kết hợp:

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

• partial_match cho biết bộ mã hoá địa lý không trả về khớp chính xác với 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 để tìm lỗi chính tả và/hoặc địa chỉ không đầy đủ.

  Kết quả khớp một phần thường xảy ra với các địa chỉ đường phố không tồn tại trong địa phương mà bạn gửi 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 hai hoặc nhiều vị trí trong cùng một tổ dân phố. 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 yêu cầu bao gồm thành phần địa chỉ sai chính tả, dịch vụ mã hoá địa lý có thể đề xuất phương án thay thế của bạn. Các đề xuất được kích hoạt theo cách này cũng sẽ được đánh dấu là một phần khớp.

• place_id là một giá trị nhận dạng duy nhất có thể được sử dụng với các API khác của Google. Ví dụ: bạn có thể sử dụng place_id trong một Yêu cầu tải 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, người dùng bài đánh giá 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ề các loại địa chỉ bao gồm địa chỉ đường phố, quốc gia hoặc một pháp nhân 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 của bạn. Ví dụ: số nhà hoặc quốc gia. (Dưới đây là toàn bộ danh sách types.) Đị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 political và Loại locality.

Các loại sau đây được bộ mã hoá địa lý hỗ trợ và trả về trong cả các mảng kiểu thành phần địa chỉ và đị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ên (chẳng hạn như "US 101").
• intersection biểu thị giao lộ chính, thường là hai các 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 thực thể chính trị quốc gia và thường là loại thứ tự cao nhất do Trình định vị địa lý trả về.
• administrative_area_level_1 cho biết một thực thể dân sự cấp một bên dưới cấp quốc gia. Tại Hoa Kỳ, những chỉ số này cấp hành chính là các tiểu bang. Không phải quốc gia nào cũng có các cấp quản lý này. Trong hầu hết các trường hợp, Administrative_area_level_1 tên ngắn sẽ phù hợp với các phân mục ISO 3166-2 và các phân mục khác danh sách lưu hành; 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 biểu thị một dân sự bậc hai pháp nhân dưới cấp quốc gia. Tại Hoa Kỳ, những chỉ số này cấp hành chính là các hạt. Không phải quốc gia nào cũng có các triển lãm này cấp hành chính.
• 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 biểu thị 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_4 biểu thị một dân sự bậc 4 pháp nhân dưới cấp quốc gia. Loại này biểu thị 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_5 biểu thị dân sự bậc 5 pháp nhân dưới cấp quốc gia. Loại này biểu thị 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_6 biểu thị một dân sự bậc 6 pháp nhân dưới 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.
• administrative_area_level_7 biểu thị một dân sự bậc 7 pháp nhân dưới cấp quốc gia. Loại này biểu thị 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.
• colloquial_area cho biết tên thay thế thường dùng cho thực thể.
• locality cho biết một thành phố hoặc thị trấn chính trị đã được hợp nhất thực thể.
• sublocality cho biết pháp nhân dân sự bậc 1 thuộc cấp dưới địa phương. Đối với một số vị trí, bạn có thể nhận được một trong những loại bổ sung: sublocality_level_1 thành 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 biểu thị khu vực địa lý.
• neighborhood biểu thị 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 thực thể đơn đặt hàng đầu tiên bên dưới một thực thể có tên một vị trí, thường là một toà nhà đơn lẻ trong một tập hợp các toà nhà có một tên thường gọi
• plus_code cho biết tham chiếu vị trí được mã hoá, dẫn xuất so với vĩ độ và kinh độ. Plus code có thể được dùng để thay thế cho địa chỉ đường phố ở nơi không tồn tại (nơi toà nhà không được đánh số hoặc đường phố không được đặt tên). Xem https://plus.codes để biết thông tin chi tiết.
• postal_code cho biết mã bưu chính dùng để xử lý địa chỉ bưu chính thư trong quốc gia.
• natural_feature biểu thị một đối tượng 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à thực thể cục bộ 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 trên, thành phần địa chỉ có thể bao gồm các loại được liệt kê tại đây. Danh sách này chưa đầy đủ và có thể thay đổi.

• floor cho biết tầng của một địa chỉ toà nhà.
• establishment thường cho biết một địa điểm đã được phân loại.
• landmark cho biết một địa điểm lân cận được dùng làm 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ư 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 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_station và transit_station cho biết vị trí của xe buýt, tàu hoặc công cộng điể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 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 làm như vậy trong URL yêu cầu bằng cách đặt tham số bounds.

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

Ví dụ: mã địa lý cho "Washington" thường trả về tiểu bang Washington ở 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ỳ cho kết quả theo 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ã hóa địa lý, bạn có thể hướng dẫn dịch vụ Mã hóa địa lý trả về kết quả bị lệch sang một khu vực cụ thể bằng cách sử dụng region . Thông số này sử dụng mã ccTLD (mã quốc gia cấp cao nhất) miền) chỉ định độ lệch khu vực. Hầu hết mã ccTLD (miền cấp cao nhất theo mã quốc gia) đều giống với Mã ISO 3166-1, với 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 là "gb" (về mặt kỹ thuật là cho thực thể "Vương quốc Anh và Bắc Ireland").

Kết quả mã hoá địa lý có thể bị sai lệch đối với mọi miền mà phần tử chính Ứng dụng Google Maps được chính thức ra mắt. Lưu ý rằng chỉ có xu hướng ư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ì chúng có thể được bao gồm.

Ví dụ: mã địa lý của "Toledo" trả về kết quả này, vì miền mặc định cho API Đị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" 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ề địa chỉ kết quả bị giới hạn ở một khu vực cụ thể. Bạn có thể chỉ định quy định hạn chế này bằng cách sử dụng bộ lọc components. 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 chéo (|). 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 Địa chỉ được mã hoá địa lý khác. Nếu bộ mã hoá địa lý tìm thấy kết quả khớp một phần cho 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 một tên quốc gia hoặc một chữ cái gồm hai chữ cái ISO 3166-1 . API tuân thủ tiêu chuẩn ISO đối với để xác định 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.

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 ngắn của một tuyến đường.
• locality khớp với các loại locality và sublocality.
• administrative_area khớp với tất cả administrative_area cấp.

Lưu ý về việc lọc thành phần:

• Đừng lặp lại các bộ lọc thành phần này trong 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á những bộ lọc đó lọc dưới dạng AND chứ không phải OR.
• Kết quả phù hợp với Google Maps, đôi khi mang lại ZERO_RESULTS phản hồi 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 thế này Câu hỏi thường gặp.
• Đối với mỗi thành phần địa chỉ, hãy chỉ định thành phần đó trong address hoặc trong bộ lọc components, nhưng không phải cả hai. Chỉ định cùng một giá trị ở 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ã hoá địa lý cho vị trí của "Santa Cruz" với components=country:ES 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ừ 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 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ý một địa chỉ đầy đủ, tham số address là bắt buộc 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"
}