Hình ảnh được chỉ định bằng cách sử dụng các tham số yêu cầu. Theo tiêu chuẩn trong URL, tất cả các tham số đều được phân tách bằng ký tự dấu và (&).
Các tham số được phép và giá trị có thể của các tham số đó được liệt kê bên dưới.
Thông số bắt buộc
Hãy thực hiện một trong hai thao tác sau:
location có thể là một chuỗi văn bản (chẳng hạn như Chagrin Falls, OH) hoặc một cặp toạ độ vĩ độ và kinh độ (40.457375,-80.009353) và phải được mã hoá URL. Vì vậy, hãy chuyển đổi các địa chỉ như "City Hall, New York, NY" thành "City+Hall,New+York,NY" trước khi bạn gửi yêu cầu.
Street View Static API sẽ chụp nhanh ảnh toàn cảnh gần với vị trí nhất. Khi bạn cung cấp một chuỗi văn bản địa chỉ, API có thể sử dụng một vị trí camera khác để hiển thị vị trí đã chỉ định một cách rõ ràng hơn.
Khi bạn cung cấp toạ độ vĩ độ và kinh độ, API sẽ tìm kiếm trong bán kính 50 mét để tìm bức ảnh gần vị trí nhất.
Vì hình ảnh trong Chế độ xem đường phố được làm mới định kỳ và ảnh có thể được chụp ở các vị trí hơi khác nhau mỗi lần, nên có thể location của bạn sẽ chuyển sang một ảnh toàn cảnh khác khi hình ảnh được cập nhật.
hoặc:
pano là một mã nhận dạng ảnh toàn cảnh cụ thể. Ảnh toàn cảnh có thể thay đổi mã nhận dạng theo thời gian, vì vậy, đừng duy trì mã nhận dạng này. Thay vào đó, hãy lưu địa chỉ vị trí hoặc toạ độ vĩ độ và kinh độ để bạn có thể làm mới mã nhận dạng toàn cảnh. Để biết thông tin chi tiết, hãy xem phần Làm mới mã nhận dạng toàn cảnh đã xoá.
Cũng như:
size chỉ định kích thước đầu ra của hình ảnh tính bằng pixel. Kích thước được chỉ định là {width}x{height} – ví dụ: size=600x400 trả về một hình ảnh có chiều rộng 600 pixel và chiều cao 400 pixel.
key cho phép bạn theo dõi mức sử dụng API của ứng dụng trong Google Cloud Console và đảm bảo rằng Google có thể liên hệ với bạn về ứng dụng của bạn nếu cần.
Để biết thêm thông tin, hãy xem bài viết Lấy khoá và chữ ký.
Làm mới mã nhận dạng ảnh toàn cảnh đã xoá
Nếu bạn cố gắng truy xuất một mã nhận dạng toàn cảnh và nhận được ZERO_RESULTS hoặc không có giá trị, thì mã nhận dạng toàn cảnh đó đã bị xoá và cần được làm mới.
Lưu địa chỉ vị trí hoặc toạ độ (vĩ độ và kinh độ) mà bạn đã dùng để lấy mã nhận dạng toàn cảnh để có thể làm mới khi cần.
Khi bạn phát hiện thấy mã nhận dạng toàn cảnh đã thay đổi, hãy sử dụng địa chỉ vị trí ban đầu hoặc toạ độ vĩ độ và kinh độ để tìm lại các bức ảnh toàn cảnh gần nhất với vị trí đó và nhận mã nhận dạng toàn cảnh mới.
Thông số tùy chọn
signature (nên dùng) là chữ ký số được dùng để xác minh rằng mọi trang web tạo yêu cầu bằng khoá API của bạn đều được phép làm như vậy. Những yêu cầu không có chữ ký số có thể không thành công.
Để biết thêm thông tin, hãy xem bài viết Lấy khoá và chữ ký.
heading cho biết hướng la bàn của camera. Giá trị được chấp nhận là từ 0 đến 360 (cả hai giá trị đều cho biết hướng Bắc, với 90 cho biết hướng Đông và 180 cho biết hướng Nam). Nếu bạn không chỉ định tiêu đề, một giá trị sẽ được tính toán để hướng camera về phía location đã chỉ định, từ điểm chụp bức ảnh gần nhất.
fov (mặc định là90) xác định góc nhìn ngang của hình ảnh (đơn vị là độ), với giá trị tối đa được phép là 120.
Khi xử lý một khung hiển thị có kích thước cố định, chẳng hạn như hình ảnh Chế độ xem đường phố có kích thước cố định, về cơ bản, trường nhìn sẽ thể hiện mức thu phóng, trong đó các số nhỏ hơn cho biết mức thu phóng cao hơn.
(Trái: fov=120; Phải: fov=20)
pitch (mặc định là0) chỉ định góc lên hoặc xuống của camera so với xe Chế độ xem đường phố. Thường thì (nhưng không phải lúc nào cũng vậy) đường này sẽ nằm ngang. Các giá trị dương sẽ hướng camera lên trên (với 90 độ cho biết hướng thẳng lên); các giá trị âm sẽ hướng camera xuống dưới (với -90 cho biết hướng thẳng xuống).
radius (mặc định là50) đặt bán kính (tính bằng mét) để tìm kiếm ảnh toàn cảnh, lấy vĩ độ và kinh độ đã cho làm tâm. Các giá trị hợp lệ là số nguyên không âm.
return_error_code cho biết liệu API có nên trả về mã lỗi khi không tìm thấy hình ảnh (404 NOT FOUND) hay để phản hồi một yêu cầu không hợp lệ (400 BAD REQUEST). Các giá trị hợp lệ là true và false. Nếu được đặt thành true, một thông báo lỗi sẽ được trả về thay cho hình ảnh màu xám chung. Nhờ đó, bạn không cần thực hiện một lệnh gọi riêng để kiểm tra tình trạng còn hàng của hình ảnh.
source (mặc định làdefault) giới hạn các lượt tìm kiếm trên Chế độ xem đường phố ở những nguồn được chọn. Các giá trị hợp lệ là:
default sử dụng các nguồn mặc định cho Chế độ xem đường phố; các cụm từ tìm kiếm không bị giới hạn ở các nguồn cụ thể.
outdoor giới hạn phạm vi tìm kiếm trong các bộ sưu tập ngoài trời. Bộ sưu tập trong nhà không xuất hiện trong kết quả tìm kiếm. Xin lưu ý rằng có thể không có ảnh toàn cảnh ngoài trời cho vị trí đã chỉ định. Cũng xin lưu ý rằng tìm kiếm chỉ trả về ảnh toàn cảnh khi có thể xác định được ảnh đó là trong nhà hay ngoài trời. Ví dụ: PhotoSphere không được trả về vì không xác định được liệu chúng có ở trong nhà hay ngoài trời.
Đối với những vị trí không có hình ảnh Chế độ xem đường phố, Street View Static API sẽ trả về một hình ảnh chung chung màu xám, kèm theo văn bản "Xin lỗi, chúng tôi không có hình ảnh ở đây", như trong ví dụ này:
Hình: Hình ảnh chung xuất hiện khi không có hình ảnh nào cho vị trí được chỉ định.
Chỉ hiển thị hình ảnh hợp lệ
Để tránh hiển thị hình ảnh chung và đảm bảo rằng trang web của bạn chỉ hiển thị hình ảnh hợp lệ của Street View Static API, hãy làm theo các đề xuất sau:
Đặt tham số return_error_code thành true.
Điều này khiến Street View Static API trả về lỗi 404 NOT FOUND thay vì hình ảnh màu xám chung chung, nếu không có hình ảnh nào cho vị trí được chỉ định.
[null,null,["Cập nhật lần gần đây nhất: 2025-08-29 UTC."],[[["\u003cp\u003eAccess Street View images via HTTP URL using specified parameters for location, size, and API key.\u003c/p\u003e\n"],["\u003cp\u003eYou can use either a text string location like "Chagrin Falls, OH" or latitude/longitude coordinates like "40.457375,-80.009353" to specify the location for Street View image requests.\u003c/p\u003e\n"],["\u003cp\u003eCustomize Street View image requests by adjusting parameters such as \u003ccode\u003eheading\u003c/code\u003e, \u003ccode\u003efov\u003c/code\u003e, \u003ccode\u003epitch\u003c/code\u003e, and \u003ccode\u003eradius\u003c/code\u003e to control the camera's view.\u003c/p\u003e\n"],["\u003cp\u003eIf Street View imagery is unavailable for the specified location, the API returns a generic gray image, which you can prevent by using the \u003ccode\u003ereturn_error_code\u003c/code\u003e parameter or checking image metadata beforehand.\u003c/p\u003e\n"],["\u003cp\u003eTo avoid misuse, it's recommended to use a digital signature (\u003ccode\u003esignature\u003c/code\u003e parameter) with your API key, especially for former Google Maps Platform Premium Plan customers.\u003c/p\u003e\n"]]],[],null,["# Streetview request and response\n\n**European Economic Area (EEA) developers** If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. [Learn more](/maps/comms/eea/faq).\n\nA Street View Image request is an HTTP URL in this format: \n\n```text\nhttps://maps.googleapis.com/maps/api/streetview?parameters\n```\n\nThe image is specified using request parameters. As is standard in\nURLs, all parameters are separated using the ampersand (\\&) character.\nAllowed parameters and their possible values are listed below.\n\nRequired parameters\n-------------------\n\nEither:\n\n- `location` can be either a text string (such as `Chagrin Falls, OH`) or a latitude and longitude coordinates pair (`40.457375,-80.009353`), and should be [URL-encoded](/maps/url-encoding). So convert addresses such as \"City Hall, New York, NY\" to \"City+Hall,New+York,NY\" before you send the request. The Street View Static API snaps to the panorama photograph closest to the location. When you provide an address text string, the API may use a different camera location to better display the specified location. When you provide latitude and longitude coordinates, the API searches a 50 meter radius for a photograph closest to the location. Because Street View imagery is periodically refreshed, and photographs may be taken from slightly different positions each time, it's possible that your `location` may snap to a different panorama when imagery is updated.\n\nOr:\n\n- `pano` is a specific panorama ID. Panoramas may change ID over time, so don't persist this ID. Instead, save the location address or latitude and longitude coordinates so you can refresh the panorama ID. For details, see [Refresh deleted panorama IDs](#refresh-pano).\n\nAs well as:\n\n- `size` specifies the output size of the image in pixels. Size is specified as `{width}x{height}` - for example, `size=600x400` returns an image 600 pixels wide, and 400 high.\n- `key` lets you monitor your application's API usage in the [Google Cloud console](https://console.cloud.google.com), and ensures that Google can contact you about your application if necessary. For more information, see [Get a Key and Signature](/maps/documentation/streetview/get-api-key).\n\n### Refresh deleted panorama IDs\n\nIf you attempt to retrieve a panorama ID and get either `ZERO_RESULTS` or\nno value, then the panorama ID has been deleted and needs to be refreshed.\n\n1. Save the location address or latitude and longitude coordinates you used to\n get a panorama ID so you can refresh when needed.\n\n2. When you detect that a panorama ID has changed, use the original location\n address or latitude and longitude coordinates to search again for the nearest\n panoramas to that location and get a new panorama ID.\n\n| **Note:** Because Street View imagery is periodically refreshed, and photographs may be taken from slightly different positions each time, a given panorama ID may snap to a different panorama when imagery or the panorama ID is updated.\n\nOptional parameters\n-------------------\n\n- `signature` (*recommended* ) is a digital signature used to verify that any site generating requests using your API key is authorized to do so. Requests that don't include a digital signature might fail. For more information, see [Get a Key and Signature](/maps/documentation/streetview/get-api-key).\n\n **Note:** for former Google Maps Platform Premium Plan customers, the **digital\n signature is required** . Get more information on\n [authentication parameters for\n Premium Plan customers](/maps/documentation/streetview/get-api-key#premium-auth).\n- `heading` indicates the compass heading of the camera. Accepted values are from `0` to `360` (both values indicating North, with `90` indicating East, and `180` South). If you don't specify a heading, a value is calculated that directs the camera towards the specified `location`, from the point at which the closest photograph was taken.\n- `fov` (*default is* `90`) determines the horizontal field of view of the image expressed in degrees, with a maximum allowed value of `120`. When dealing with a fixed-size viewport, as with a Street View image of a set size, field of view in essence represents zoom, with smaller numbers indicating a higher level of zoom.\n\n \u003cbr /\u003e\n\n\n \u003cbr /\u003e\n\n *(Left: `fov=120`; Right: `fov=20`)*\n\n\n- `pitch` (*default is* `0`) specifies the up or down angle of the camera relative to the Street View vehicle. This is often, but not always, flat horizontal. Positive values angle the camera up (with `90` degrees indicating straight up); negative values angle the camera down (with `-90` indicating straight down).\n- `radius` (*default is* `50`) sets a radius, specified in meters, in which to search for a panorama, centered on the given latitude and longitude. Valid values are non-negative integers.\n- `return_error_code` indicates whether the API should return an error code when no image is found (404 NOT FOUND), or in response to an invalid request (400 BAD REQUEST). Valid values are `true` and `false`. If set to `true`, an error message is returned in place of the generic gray image. This eliminates the need to make a separate call to check for image availability.\n- `source` (*default is* `default`) limits Street View searches to selected sources. Valid values are:\n - `default` uses the default sources for Street View; searches are not limited to specific sources.\n - `outdoor` limits searches to outdoor collections. Indoor collections are not included in search results. Note that outdoor panoramas may not exist for the specified location. Also note that the search only returns panoramas where it's possible to determine whether they're indoors or outdoors. For example, PhotoSpheres are not returned because it's unknown whether they are indoors or outdoors.\n\nThis is an example request. \n\n```html\nhttps://maps.googleapis.com/maps/api/streetview?size=600x300&location=46.414382,10.013988&heading=151.78&pitch=-0.76&key=YOUR_API_KEY&signature=YOUR_SIGNATURE\n```\n\nNo imagery available\n--------------------\n\nFor locations where Street View imagery is not available, the Street View Static API\nreturns a gray generic image, with the text \"Sorry, we have no imagery\nhere.\", as shown in this example:\nFigure: Generic image displayed when no imagery is available for the specified location.\n\n### Show only valid images\n\nTo avoid displaying the generic image, and ensure that your web page\ndisplays only valid Street View Static API images, follow these\nsuggestions:\n\n- Set the `return_error_code` parameter to `true`. This causes the Street View Static API to return a 404 NOT FOUND error in place of the generic gray image, if no image is available for the specified location.\n- Request [Street View image metadata](/maps/documentation/streetview/metadata) to determine if there is imagery available for the specified location prior to sending a request."]]
