يتم تحديد الصورة باستخدام مَعلمات الطلب. وكما هو معتاد في عناوين URL، يتم فصل جميع المَعلمات باستخدام رمز العطف (&).
في ما يلي قائمة بالمعلمات المسموح بها وقيمها المحتملة.
المعلمات المطلوبة
يمكنك إجراء ذلك بإحدى طريقتين:
يمكن أن تكون قيمة location سلسلة نصية (مثل Chagrin Falls, OH) أو زوجًا من إحداثيات خط العرض وخط الطول (40.457375,-80.009353)، ويجب أن تكون مشفّرة باستخدام ترميز URL. لذا، عليك تحويل العناوين مثل "City Hall, New York, NY" إلى "City+Hall,New+York,NY" قبل إرسال الطلب.
تلتصق خدمة Street View Static API بصورة البانوراما الأقرب إلى الموقع الجغرافي. عند تقديم سلسلة نصية للعنوان، قد تستخدم واجهة برمجة التطبيقات موقعًا جغرافيًا مختلفًا للكاميرا من أجل عرض الموقع الجغرافي المحدّد بشكل أفضل.
عند تقديم إحداثيات خطوط الطول والعرض، تبحث واجهة برمجة التطبيقات ضمن دائرة نصف قطرها 50 مترًا عن صورة فوتوغرافية أقرب إلى الموقع الجغرافي.
بما أنّ صور "التجوّل الافتراضي" يتم تجديدها بشكل دوري، وقد يتم التقاط الصور من مواضع مختلفة قليلاً في كل مرة، من المحتمل أن يتم نقل location إلى صورة بانورامية مختلفة عند تعديل الصور.
أو:
pano هو معرّف بانوراما معيّن. قد يتغيّر معرّف الصور البانورامية بمرور الوقت، لذا لا تحتفظ بهذا المعرّف. بدلاً من ذلك، احفظ عنوان الموقع الجغرافي أو إحداثيات خط العرض وخط الطول لتتمكّن من إعادة تحميل معرّف الصورة البانورامية. لمعرفة التفاصيل، يُرجى الاطّلاع على إعادة تحميل أرقام تعريف الصور البانورامية المحذوفة.
بالإضافة إلى:
تحدّد size حجم الصورة الناتج بالبكسل. يتم تحديد الحجم على النحو التالي:
{width}x{height} - على سبيل المثال، size=600x400
تعرض صورة بعرض 600 بكسل وارتفاع 400 بكسل.
تتيح لك key مراقبة استخدام واجهة برمجة التطبيقات في تطبيقك من خلال وحدة تحكّم Google Cloud، كما تضمن إمكانية تواصل Google معك بشأن تطبيقك عند الضرورة.
لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على مفتاح وتوقيع.
إعادة تحميل أرقام تعريف الصور البانورامية المحذوفة
إذا حاولت استرداد معرّف بانوراما وظهر لك ZERO_RESULTS أو لم تظهر لك أي قيمة، يعني ذلك أنّه تم حذف معرّف البانوراما ويجب إعادة تحميله.
احفظ عنوان الموقع الجغرافي أو إحداثيات خط العرض وخط الطول التي استخدمتها للحصول على رقم تعريف بانوراما حتى تتمكّن من إعادة تحميلها عند الحاجة.
عندما تلاحظ أنّ معرّف البانوراما قد تغيّر، استخدِم عنوان الموقع الجغرافي الأصلي أو إحداثيات خطوط الطول والعرض للبحث مجددًا عن أقرب صور بانورامية إلى ذلك الموقع الجغرافي والحصول على معرّف بانوراما جديد.
المعلمات الاختيارية
signature (يُنصح به) هو توقيع رقمي يُستخدم
للتحقّق من أنّ أي موقع إلكتروني ينشئ طلبات باستخدام مفتاح واجهة برمجة التطبيقات الخاص بك لديه الإذن
بإجراء ذلك، وقد يتعذّر تنفيذ الطلبات التي لا تتضمّن توقيعًا رقميًا.
لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على مفتاح وتوقيع.
ملاحظة: بالنسبة إلى عملاء "خطة Premium" السابقة في Google Maps Platform، يجب تقديم توقيع رقمي. يمكنك الاطّلاع على مزيد من المعلومات حول مَعلمات المصادقة لعملاء خطة Premium.
تشير heading إلى اتجاه البوصلة للكاميرا. القيم المقبولة هي من 0 إلى 360
(تشير كلتا القيمتَين إلى الشمال، وتشير 90 إلى الشرق،
و180 إلى الجنوب). في حال عدم تحديد عنوان، يتم احتساب قيمة توجّه الكاميرا نحو location المحدّد، من النقطة التي تم التقاط أقرب صورة عندها.
تحدّد السمة fov (القيمة التلقائية هي90) المجال الأفقي لرؤية الصورة معبّرًا عنه بالدرجات،
ويبلغ الحد الأقصى المسموح به 120.
عند التعامل مع إطار عرض ثابت الحجم، كما هو الحال مع صورة "التجوّل الافتراضي" ذات الحجم المحدّد، يمثّل مجال الرؤية في الأساس مستوى التكبير، حيث تشير الأرقام الأصغر إلى مستوى تكبير أعلى.
(اليسار: fov=120، اليمين: fov=20)
تحدّد pitch (القيمة التلقائية هي0) زاوية ميل الكاميرا للأعلى أو للأسفل بالنسبة إلى مركبة "التجوّل الافتراضي". يكون هذا الخط أفقيًا في أغلب الأحيان، ولكن ليس دائمًا. تشير القيم الموجبة إلى زاوية الكاميرا للأعلى (مع الإشارة إلى 90 درجة للأعلى مباشرةً)، وتشير القيم السالبة إلى زاوية الكاميرا للأسفل (مع الإشارة إلى -90 درجة للأسفل مباشرةً).
تحدّد السمة radius (القيمة التلقائية هي50) نصف قطر، محدّدًا بالأمتار، يتم البحث فيه عن صورة بانورامية، مع توسيطها على خط العرض وخط الطول المحدّدَين. القيم الصالحة هي أعداد صحيحة غير سالبة.
يشير return_error_code إلى ما إذا كان يجب أن تعرض واجهة برمجة التطبيقات رمز خطأ عند عدم العثور على صورة (404 NOT FOUND)، أو استجابةً لطلب غير صالح (400 BAD REQUEST). القيم الصالحة هي true وfalse. إذا تم ضبطها على true، سيتم عرض رسالة خطأ بدلاً من الصورة الرمادية العامة. ويؤدي ذلك إلى إلغاء الحاجة إلى إجراء طلب منفصل للتحقّق من توفّر الصورة.
source (الإعداد التلقائي هوdefault)
يقتصر على عمليات البحث في "التجوّل الافتراضي" من المصادر المحدّدة. القيم الصالحة هي:
تستخدم default المصادر التلقائية لصور "التجوّل الافتراضي"، ولا تقتصر عمليات البحث على مصادر معيّنة.
يقتصر البحث في outdoor على المجموعات الخارجية. لا يتم تضمين المجموعات الداخلية في نتائج البحث. يُرجى العِلم أنّه قد لا تتوفّر صور بانورامية خارجية للموقع الجغرافي المحدّد. يُرجى العِلم أيضًا أنّ البحث لا يعرض سوى الصور البانورامية التي يمكن تحديد ما إذا كانت في مكان داخلي أو خارجي. على سبيل المثال،
لا يتم عرض صور Photo Sphere لأنّه من غير المعروف ما إذا كانت في أماكن مغلقة أو مفتوحة.
بالنسبة إلى المواقع الجغرافية التي لا تتوفّر فيها صور "التجوّل الافتراضي"، تعرض Street View Static API صورة عامة رمادية اللون مع النص "عذرًا، ليس لدينا صور لهذا المكان"، كما هو موضّح في المثال التالي:
الشكل: صورة عامة يتم عرضها عندما لا تتوفّر صور للموقع الجغرافي المحدّد.
عرض الصور الصالحة فقط
لتجنُّب عرض الصورة العامة والتأكّد من أنّ صفحة الويب تعرض فقط صورًا صالحة من Street View Static API، اتّبِع الاقتراحات التالية:
اضبط المَعلمة return_error_code على true.
يؤدي ذلك إلى أن تعرض Street View Static API الخطأ 404 NOT FOUND بدلاً من الصورة الرمادية العامة، وذلك في حال عدم توفّر صورة للموقع الجغرافي المحدّد.
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\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."]]
