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

Yêu cầu

Yêu cầu Geocoding API có dạng như sau:

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

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

• json (nên dùng) cho biết đầu ra ở định dạng JavaScript Object Notation (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 biệt về tính năng mã hoá địa lý và mã hoá địa lý ngược, vì mỗi loại yêu cầu có các tham số khác nhau.

Tham số mã hoá địa lý (tra cứu vĩ độ/kinh độ)

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

• 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á.

• Bạn phải chỉ định address hoặc components hoặc cả hai trong một yêu cầu:

  • address – Địa chỉ đường hoặc plus code mà bạn muốn mã hoá địa lý. Hãy chỉ định địa chỉ theo định dạng mà dịch vụ bưu chính quốc gia của quốc gia liên quan sử dụng. Bạn nên tránh các thành phần khác trong địa chỉ, chẳng hạn như tên doanh nghiệp và số căn hộ, số nhà 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 (được hiển thị ở đây dưới dạng thoát URL thành %20):

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

    Định dạng mã cộng như minh hoạ ở đây (dấu cộng được thoát URL thành %2B và khoảng trắng được thoát URL thành %20):
    • mã toàn cầu 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ã kết hợp là mã địa phương có từ 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).
  • 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 dọc (|). 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à hoàn toàn hạn chế kết quả từ trình mã hoá địa lý. Xem thêm thông tin về bộ lọc thành phần bên dưới.

Hãy xem Câu hỏi thường gặp để biết thêm hướng dẫn.

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

• bounds – Khung giới hạn của khung nhìn mà trong đó kết quả mã hoá địa lý được ưu tiên 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ừ trình mã hoá địa lý. (Để biết thêm thông tin, hãy xem phần Thiên vị khung hiển thị 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 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ữ mẹ đẻ của miền mà từ đó yêu cầu được gửi.
  • Trình mã hoá địa lý cố gắng cung cấp một đị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 đó, API này sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một kịch bản mà người dùng có thể đọc được (nếu cần), đồng thời tuân thủ ngôn ngữ ưu tiên. Tất cả các địa chỉ khác đều đượ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ì trình mã hoá địa lý sẽ sử dụng kết quả trùng 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ề. Trình mã hoá địa lý diễn giải các từ viết tắt theo những 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 phố 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ụ: utca và tér lần lượt là từ đồng nghĩa với đường và quảng trường trong tiếng Hungary.
• region – Mã khu vực, được chỉ định làm giá trị gồm 2 ký tự ccTLD ("miền cấp cao nhất"). Tham số này sẽ chỉ ảnh hưởng chứ không hoàn toàn hạn chế kết quả từ trình mã hoá đị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ố này cũng có thể ảnh hưởng đến kết quả dựa trên 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 dọc (|). Bộ lọc thành phần là bắt buộc nếu yêu cầu không có 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ý. Xem thêm thông tin về bộ 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:
  • ADDRESS_DESCRIPTORS – Xem các bộ mô tả địa chỉ để biết thêm thông tin chi tiết.
  • BUILDING_AND_ENTRANCES – Xem lối vào và đường viền 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 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

Phản hồi 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 theo mặc định.

Trong ví dụ này, Geocoding API yêu cầu một phản hồi json cho một 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.

{
    "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 khiến tính năng 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 trình mã hoá địa lý được truyền một address không tồn tại.
• OVER_DAILY_LIMIT cho biết một trong những trường hợp sau:
  • 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 cho tài khoản của mình.
  • Bạn đã vượt quá hạn mức sử dụng do chính mình đặt ra.
  • 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 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 yêu cầu không xử lý được 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 mã hoá địa lý trả về mã trạng thái khác OK, có thể có một trường error_message bổ sung 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 đằng sau mã trạng thái đã cho.

Kết quả

Khi trình mã hoá địa lý trả về kết quả, trình này sẽ đặt kết quả trong một mảng (JSON) results. Ngay cả khi trình mã hoá địa lý 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 mã hoá địa lý vẫn trả về một mảng results trống. (Phản hồi XML bao gồm từ 0 phần tử <result> trở lên.)

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

• Mảng types[] cho biết loại 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 đối tượng được trả về trong kết quả. Ví dụ: mã địa lý của "Chicago" trả về "locality" (địa phương) cho biết "Chicago" là một thành phố, đồng thời trả về "political" (chính trị) cho biết đây là một thực thể 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 khi cần. Để biết thêm thông tin, hãy xem bài viết Các loại địa chỉ và thành phần địa chỉ.
• formatted_address là một chuỗi ký tự chứa địa chỉ mà con người đọc được của vị trí này.

  Địa chỉ này thường 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 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í 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ỳ).

  Đừng phân tích cú pháp địa chỉ được đị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 type 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ả hoặc tên đầy đủ bằng văn bản của thành phần địa chỉ do Geocoder trả về.
  • short_name là tên văn bản viết tắt của thành phần địa chỉ (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 gồm 2 chữ cái của mã bưu chính.

  Xin lưu ý những thông tin 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 phải bao gồm tất cả các thực thể chính trị có 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ị có chứa một địa chỉ cụ thể, bạn nên sử dụng tính năng mã hoá địa lý ngược, truyền vĩ độ/kinh độ của địa chỉ làm tham số cho 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 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 này.

  Để 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ề 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 điểm nằm trong một mã bưu chính. Tham số này chỉ xuất hiện khi kết quả là một mã bưu chính chứa nhiều địa điểm.
• geometry chứa các thông tin sau:
  • location chứa giá trị vĩ độ, 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í được chỉ định. Hiện tại, chúng tôi hỗ trợ các giá trị sau:

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

  Khi dịch vụ trả về một plus code, mã này sẽ được định dạng dưới dạng mã toàn cầu và mã kết 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 có từ 6 ký tự trở lên và có vị trí cụ thể (CWC8+R9, Mountain View, California, Hoa Kỳ). Không phân tích cú pháp nội dung này theo cách lập trình.
  Nếu có, API sẽ trả về cả mã toàn cầu và mã kết hợp. Tuy nhiên, nếu kết quả ở một vị trí từ xa (ví dụ: đại dương hoặc sa mạc), thì chỉ mã toàn cầu mới có thể được trả về.

• partial_match cho biết trình 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ù trình mã hoá này 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ỉ không đầy đủ hay không.

  Trường hợp khớp một phần thường xảy ra đối với những địa chỉ đường không tồn tại trong khu vực mà bạn truyền vào yêu cầu. Kết quả trùng khớp một phần cũng có thể được trả về khi một yêu cầu trùng khớp với hai hoặc nhiều vị trí trong 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à Henrietta Street. Xin lưu ý rằng nếu một yêu cầu có chứa một 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ế. Các đề 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ả khớp một phần.

• place_id là một 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 Places API để 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. Xem thông tin 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 phản hồi 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 thực thể chính trị. Mảng types trong trường address_component cho biết loại của từng phần trong địa chỉ. Ví dụ: số nhà hoặc quốc gia.

Đị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 các loại political và locality.

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

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ể (ví dụ: Lieu-dit ở Pháp).

Ngoài những 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ê bên dưới.

Thiên vị 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 hiển thị 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 dọc (|) để 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 một đố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 theo khu vực

Trong yêu cầu về Địa lý mã hoá, bạn có thể hướng dẫn dịch vụ Địa lý mã hoá trả về kết quả thiên về một khu vực cụ thể bằng cách sử dụng tham số region. Tham số này nhận 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 mã ccTLD đề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 quốc gia này 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ị thiên vị đối với mọi miền mà ứng dụng Google Maps chính thức được phát hành. 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ì kết quả đó vẫn 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 Geocoding API đượ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 về 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 về Địa lý mã hoá, Geocoding API có thể trả về kết quả về địa chỉ bị hạn chế ở một khu vực cụ thể. Bạn có thể chỉ định hạn chế bằ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 dọc (|). Các 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 khác về Dịch mã địa lý. Nếu trình mã hoá địa lý tìm thấy một phần trùng khớp cho bộ lọc thành phần, thì phản hồi sẽ chứa trường partial_match.

components mà bạn có thể 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à hoạt động lọc 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 chúng tôi 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 locality và sublocality.
• administrative_area khớp với tất cả các cấp administrative_area.

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á các bộ lọc đó dưới dạng AND chứ không phải OR.
• Kết quả nhất quán với Google Maps, đôi khi đưa ra các câu trả lờ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 phần 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" bằng components=country:GB 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" có components=country:ESsẽ 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ể thực hiện 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ý một địa chỉ đầy đủ, bạn phải dùng tham số address nếu yêu cầu chứa tên và số của các 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"
}