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

Yêu cầu

Yêu cầu API mã hóa địa lý có dạng sau:

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

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

  • json (nên dùng) cho biết kết quả trong JavaScript Object Notation (JSON); hoặc
  • xml cho biết kết quả ở định dạng XML

HTTPS là yêu cầu bắt buộc đối với các yêu cầu dùng khoá API.

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

Phần còn lại của trang này sẽ mô tả riêng biệt 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.

Thông số mã hóa địa lý (tìm kiếm vĩ độ/kinh độ)

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

  • address — Địa chỉ đường phố hoặc mã cộng mà bạn muốn mã hoá địa lý. Hãy chỉ định 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 sử dụng các phần tử địa chỉ bổ sung như tên và đơn vị kinh doanh, số phòng hoặc số tầng. Các phần tử địa chỉ đường phố phải được phân tách bằng dấu cách (hiển thị ở đây là url được thoát tới %20):
    address=24%20Sussex%20Drive%20Ottawa%20ON
    Định dạng mã cộng như được hiển thị ở đây (dấu cộng là ký tự thoát URL tới %2B và dấu cách được truyền qua url tới %20):
    • mã toàn cầu là mã vùng gồm 4 ký tự và mã cục bộ dài 6 ký tự trở lên (849VCWC8+R9 là 849VCWC8%2BR9).
    • mã phức hợp là mã địa phương dài 6 ký tự trở lên 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 dấu gạch dọc (|). Bạn cũng có thể chấp nhận bộ lọc thành phần dưới dạng thông số không bắt buộc nếu cung cấp address. Mỗi phần tử trong bộ lọc thành phần bao gồm một cặp component:value và hạn chế hoàn toàn kết quả từ bộ mã hoá. Vui lòng xem thêm thông tin về việc 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 nhằm mục đích quản lý hạn mức. Tìm hiểu cách nhận khoá.

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

Các tham 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 có xu hướng mã hoá kết quả nổi bật hơn. Tham số này sẽ chỉ ảnh hưởng đến kết quả từ bộ mã hoá (chứ không bị hạn chế hoàn toàn). (Để biết thêm thông tin, hãy xem phần Xu hướng khung nhìn bên dưới.)
  • language – Ngôn ngữ dùng để trả về kết quả.
    • Hãy 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, danh sách này có thể không đầy đủ.
    • Nếu bạn không cung cấp language, bộ mã hoá sẽ cố gắng sử dụng ngôn ngữ ưu tiên như đã chỉ định trong tiêu đề Accept-Language hoặc ngôn ngữ gốc của miền mà bạn gửi yêu cầu.
    • Bộ mã hoá địa lý 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 được nếu cần, quan sát được ngôn ngữ ưu tiên. Tất 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ữ và đượ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ẽ sử dụng kết quả phù hợp 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ề. Bộ mã hoá địa lý diễn giải các chữ viết tắt khác nhau tuỳ thuộc vào ngôn ngữ, chẳng hạn như chữ viết tắt của các loại đường phố hoặc từ đồng nghĩa có thể hợp lệ bằng một ngôn ngữ nhưng không hợp lệ bằng ngôn ngữ khác. Ví dụ: utcatér là các từ đồng nghĩa với đường phố và quảng trường tương ứng bằng tiếng Hungary.
  • region — Mã vùng, được chỉ định là giá trị hai ký tự ccTLD ("miền cấp cao nhất"). Tham số này sẽ chỉ ảnh hưởng đến kết quả của bộ mã hoá địa lý, chứ không ảnh hưởng đến toàn bộ kết quả. (Để biết thêm thông tin, hãy xem phần Xu hướng khu vực bên dưới.)
  • 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 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 kết quả từ bộ mã hoá. Vui lòng xem thêm thông tin về việc lọc thành phần bên dưới.

Nội dung trả lời

Phản hồi mã hoá địa lý được trả về ở định dạng được chỉ định bởi 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ã hóa địa lý yêu cầu phản hồi json cho truy vấn về mã địa điểm "ChIJeRpOeF67j4AR9ydy_PIzPuM". Địa điểm này mã của tòa nhà tại 1600 Amphitheatre Parkway, Mountain View, CA.

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

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

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

https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

Hãy chọn các thẻ bên dưới để xem các 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"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4224428,
                    "lng": -122.0842467
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4239627802915,
                        "lng": -122.0829089197085
                    },
                    "southwest": {
                        "lat": 37.4212648197085,
                        "lng": -122.0856068802915
                    }
                }
            },
            "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
            "plus_code": {
                "compound_code": "CWC8+X8 Mountain View, CA",
                "global_code": "849VCWC8+X8"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

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

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

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

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. Vui lòng xem Mã trạng thái bên dưới.
  • Không có hoặc có nhiều phần tử <result>, mỗi phần tử có chứa một bộ thông tin địa chỉ được mã hoá địa lý và thông tin hình học.

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

  • Kết quả XML được bao bọc trong một phần tử <GeocodeResponse> gốc.
  • JSON biểu thị các mục nhập có nhiều phần tử theo các mảng số nhiều (types), trong khi XML biểu thị các mục này bằng nhiều phần tử số ít (<type>).
  • Phần tử trống được biểu thị thông qua các mảng trống trong JSON, nhưng không có bất kỳ phần tử nào như vậy trong XML. Ví dụ: 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 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 chưa xảy ra lỗi nào; đị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ã hoá đị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ỳ nội dung nào sau đây:
    • Khoá API bị thiếu hoặc không hợp lệ.
    • Tài khoản của bạn chưa được bật tính năng thanh toán.
    • Đã 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 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 rằng yêu cầu của bạn bị từ chối.
  • "INVALID_REQUEST" thường cho biết truy vấn (address, components hoặc latlng) bị thiếu.
  • "UNKNOWN_ERROR" cho biết không thể xử lý yêu cầu do lỗi máy chủ. Yêu cầu này 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ông phải OK, thì 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 đằng sau mã trạng thái nhất định.

Kết quả

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

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 các thẻ từ 0 trở lên xác định loại tính năng được trả về trong kết quả. Ví dụ: một mã địa lý được mã hoá của "Chicago" trả về "địa phương" cho biết rằng "Chicago" là một thành phố, và cũng trả về "chính trị" cho biết đây là một pháp nhân chính trị. Các thành phần có thể có một mảng loại trống khi không có loại đã biết cho thành phần địa chỉ đó. API có thể thêm các giá trị loại mới nếu cần. Để biết thêm thông tin, hãy xem phần Loại địa chỉ và thành phần địa chỉ.
  • formatted_address là một chuỗi chứa địa chỉ mà con người có thể đọc được.

    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 sự do các hạn chế 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ỉ theo logic. Ví dụ: địa chỉ "111 8th Avenue, New York, NY" bao gồm các thành phần sau: "111" (số đường phố), "8th Avenue" (tuyến đường), "New York" (thành phố) và "NY" (tiểu bang Hoa Kỳ).

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

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

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

    • types[] là một mảng cho biết loại thành phần địa chỉ. Hãy xem danh sách các loại được hỗ trợ.
    • long_name là phần mô tả bằng văn bản đầy đủ hoặc tên của thành phần địa chỉ do Trình mã hoá địa lý 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à một short_name là "AK" sử dụng chữ viết tắt gồm 2 chữ cái.

    Hãy lưu ý những dữ kiện sau về mảng address_components[]:

    • Dãy thành phần địa chỉ có thể chứa nhiều thành phần hơn formatted_address.
    • Mảng không nhất thiết phải bao gồm tất 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ả thực thể chính trị có chứa địa chỉ cụ thể, bạn nên sử dụng quy trình mã hoá địa lý đảo ngược, chuyển vĩ độ/kinh độ của địa chỉ dưới dạng thông số cho yêu cầu.
    • Định dạng của phản hồi không được đảm bảo sẽ vẫn giữ nguyên giữa các yêu cầu. Cụ thể, số lượng address_components sẽ khác nhau tùy 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. Thành phần cụ thể có thể bị thiếu trong phản hồi sau.

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

  • postcode_localities[] là một mảng biểu thị tất cả các đị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 có chứa nhiều địa phương.
  • geometry chứa các thông tin sau:
    • location chứa vĩ độ, kinh độ được mã hóa địa lý. Đối với những lượt 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. Hiện tại, chúng tôi hỗ trợ những giá trị sau:

      • "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 theo độ chính xác của địa chỉ đường phố.
      • "RANGE_INTERPOLATED" cho biết rằng kết quả trả về phản ánh một giá trị gần đúng (thường là trên một con đường) 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 mã hoá địa lý trên mái nhà không có sẵn cho đị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 (vùng).
      • "APPROXIMATE" cho biết rằng kết quả trả về là giá trị gần đúng.
    • viewport chứa khung nhìn đề xuất để hiển thị kết quả trả về, được chỉ định dưới dạng hai giá trị vĩ độ,kinh độ xác định góc southwestnortheast của hộp giới hạn khung nhìn. Nhìn chung, khung nhìn được dùng để đóng khung kết quả khi hiển thị kết quả cho người dùng.
    • bounds (không bắt buộc được trả về) lưu trữ hộp giới hạn. Hộp này có thể chứa đầy đủ kết quả trả về. Lưu ý rằng các 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 đảo thuộc quần đảo, 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 Bạn có thể sử dụng mã cộng để thay thế đị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 không được đặt tên). API không phải lúc nào cũng trả về mã cộng.

    Khi trả về một mã cộng, dịch vụ có định dạng là mã chung và mã phức hợp:

    • global_code là mã vùng gồm 4 ký tự và mã cục bộ dài 6 ký tự trở lên (849VCWC8+R9).
    • compound_code là một mã địa phương dài 6 ký tự trở lên có vị trí rõ ràng (CWC8+R9, Mountain View, CA, Hoa Kỳ). Khô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 sẽ trả về cả mã chung và mã phức hợp. Tuy nhiên, nếu kết quả nằm ở một vị trí từ xa (ví dụ: đại dương hoặc sa mạc), thì chỉ có thể trả về mã toàn cầu.
  • partial_match cho biết bộ mã hoá dữ liệu đã 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ể so 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 nhất đối với các địa chỉ đường phố không tồn tại trong phạm vi địa phương bạn chuyển trong yêu cầu. Kết quả khớp một phần cũng có thể được trả về khi yêu cầu khớp với hai hoặc nhiều vị trí trong cùng một địa phương. Ví dụ: "Hillpar St, Bristol, Vương quốc Anh" sẽ trả về kết quả khớp một phần cho cả Phố Henry và Phố Henrietta. Hãy lưu ý rằng nếu một yêu cầu bao gồm 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à 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à các thông tin khác. Xem bài viết 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ỉ: đị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 trong địa chỉ. Ví dụ như số nhà hoặc quốc gia. (Dưới đây là danh sách các loại đầy đủ.) Đị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ẻ loại political và loại locality.

Những loại sau đây được bộ mã hoá dữ liệu hỗ trợ và trả về trong cả mảng loại địa chỉ và 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 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 đường chính.
  • political cho biết một thực thể chính trị. Thông thường, loại này cho biết một đa giác của một khu vực 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 đơn đặt hàng cao nhất do Geocoder trả về.
  • administrative_area_level_1 cho biết một thực thể dân sự có thứ tự dưới cấp quốc gia. Ở Hoa Kỳ, các cấp quản trị này là tiểu bang. Không phải quốc gia nào cũng có mức độ hành chính như vậy. Trong hầu hết các trường hợp, tên ngắn admin_area_level_1 sẽ khớp hoàn toàn với 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 đả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 một pháp nhân dân sự cấp hai dưới cấp quốc gia. Ở 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 có mức độ hành chính như vậy.
  • administrative_area_level_3 cho biết một pháp nhân dân sự cấp ba dưới cấp quốc gia. Loại này cho biết một bộ phận dân sự nhỏ. Không phải quốc gia nào cũng có những cấp hành chính này.
  • administrative_area_level_4 cho biết một thực thể dân sự bậc 4 dưới cấp quốc gia. Loại này cho biết một bộ phận dân sự nhỏ. Không phải quốc gia nào cũng có những cấp hành chính này.
  • administrative_area_level_5 cho biết một thực thể dân sự bậc 5 dưới cấp quốc gia. Loại này cho biết một bộ phận dân sự nhỏ. Không phải quốc gia nào cũng có những cấp hành chính này.
  • administrative_area_level_6 cho biết một thực thể dân sự cấp 6 dưới cấp quốc gia. Loại này cho biết một bộ phận dân sự nhỏ. Không phải quốc gia nào cũng có những cấp hành chính này.
  • administrative_area_level_7 cho biết một thực thể dân sự bậc bảy dưới cấp quốc gia. Loại này cho biết một bộ phận dân sự nhỏ. Không phải quốc gia nào cũng có những 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ấp thành phố hoặc thị trấn.
  • sublocality cho biết một pháp nhân dân sự có thứ tự bên dưới một địa phương. Đối với một số vị trí, có thể bạn sẽ dùng một trong các loại bổ sung: sublocality_level_1 đến sublocality_level_5. Mỗi cấp dân cư là một pháp nhân dân sự. Số lớn hơn biểu thị một khu vực địa lý nhỏ hơn.
  • neighborhood cho biết vùng lân cận đã đặt tên
  • premise cho biết vị trí đã đặt tên, thường là một toà nhà hoặc bộ sưu tập các toà nhà có tên thật
  • subpremise cho biết một thực thể có thứ tự bên dưới một vị trí được đặt tên, thường là một toà nhà duy nhất trong một tập hợp các toà nhà có tên phổ biến.
  • plus_code cho biết một tệp tham chiếu vị trí đã mã hoá, bắt nguồn từ vĩ độ và kinh độ. Bạn có thể sử dụng mã cộng để thay thế địa chỉ đường phố ở những nơi không có mã (các toà nhà không được đánh số hoặc không được đặt tên). Hãy xem https://plus.codes để biết chi tiết.
  • postal_code cho biết mã bưu chính dùng để gửi thư trong nước ở quốc gia đó.
  • natural_feature cho biết một đối tượng địa lý tự nhiên nổi bật.
  • airport biểu thị mộ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 không dễ dàng phù hợp với một danh mục khác, chẳng hạn như "Xây dựng trạng thái Empire" hoặc "Tháp Eiffel".

Danh sách loại trống 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ư Liu-dit ở Pháp.

Ngoài các 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ê ở đây. Danh sách này chưa đầy đủ và có thể thay đổi.

  • floor cho biết tầng của địa chỉ toà nhà.
  • establishment thường cho biết một địa điểm chưa được phân loại.
  • landmark cho biết một địa điểm gần đó được dùng làm tệp đối chiếu để hỗ trợ việc điều hướ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 cấu trúc bãi đỗ xe.
  • post_box cho biế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ư localitysublocality, được dùng cho các địa chỉ gửi thư ở một số quốc gia.
  • room cho biết phòng của một địa chỉ toà nhà.
  • street_number cho biết số đường chính xác.
  • bus_station, train_stationtransit_station cho biết vị trí của trạm xe buýt, xe lửa hoặc 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 thể hiện dưới dạng 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 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ự ống (|) để phân tách các toạ độ.

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

Yêu cầu:

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

Phản hồi:

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

Tuy nhiên, việc thêm đối số bounds xác định hộp giới hạn xung quanh phần phía đông bắc của Hoa Kỳ dẫn đến việc mã hoá đị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ả thiên về một khu vực cụ thể bằng cách sử dụng thông số region. Tham số này sẽ lấy đối số ccTLD (miền cấp cao nhất của mã quốc gia) để chỉ định độ sai lệch khu vực. Hầu hết mã ccTLD 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 là "gb" (về mặt kỹ thuật là thực thể của "Vương quốc Anh và Bắc Ireland").

Kết quả mã hóa đị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 chính thức. Lưu ý rằng xu hướng này chỉ ưu tiên cho một miền cụ thể; nếu có kết quả phù hợp hơn ngoài miền này thì kết quả đó có thể bao gồm.

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

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

  • postal_code khớp với postal_codepostal_code_prefix.
  • country khớp với tên quốc gia hoặc mã quốc gia gồm hai chữ cái ISO 3166-1. API tuân theo tiêu chuẩn ISO cho các quốc gia xác định và tính năng lọc sẽ 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.
  • locality khớp với loại localitysublocality.
  • 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 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 đó là AND, chứ không phải OR.
  • Kết quả nhất quán với Google Maps, đôi khi dẫn đến các câu trả lời không mong muốn về ZERO_RESULTS. Việc sử dụng tính năng Tự động hoàn thành địa điểm có thể cung cấp kết quả tốt hơn trong một số trường hợp sử dụng. Để tìm hiểu thêm, hãy xem Câu hỏi thường gặp này.
  • Đối với mỗi thành phần địa chỉ, hãy chỉ định thành phần đó trong tham số address hoặc trong bộ lọc components, chứ không phải cả hai. Việc chỉ định các giá trị giống nhau trong cả hai giá trị có thể dẫn đến ZERO_RESULTS.

Một mã địa lý cho "Cao St, Hastings" có 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"
}

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

Yêu cầu:

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

Phản hồi:

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

Tính năng lọc thành phần chỉ trả về phản hồi ZERO_RESULTS nếu bạn cung cấp các bộ lọc loại trừ 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ý đầy đủ, bạn phải dùng tham số address nếu yêu cầu có 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"
}