تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تعرض السمة Roads API الحدّ الأقصى للسرعة المحدّد على جزء معيّن من الطريق. في حال كانت مقاطع الطرق تتضمّن حدود سرعة متغيرة، يتم عرض حد السرعة التلقائي للمقطع.
لا يمكن ضمان دقة بيانات حدود السرعة التي تعرضها السمة Roads API. إنّ بيانات الحد الأقصى للسرعة المقدَّمة ليست في الوقت الفعلي، وقد تكون
مقدَّرة أو غير دقيقة أو غير مكتملة أو قديمة. يمكنك الاطّلاع على تفاصيل التغطية
لمعرفة المناطق التي تتوفّر فيها بيانات حدود السرعة.
الطلبات
أرسِل طلبات حدود السرعة باستخدام HTTPS، بالشكل التالي:
path: قائمة تضم ما يصل إلى 100 زوج من خطوط الطول والعرض تمثّل مسارًا. يجب الفصل بين قيمتَي خط الطول وخط العرض بفواصل.
يجب الفصل بين أزواج خطوط الطول والعرض باستخدام الحرف العمودي: "|".
عند تقديم المَعلمة path، تعمل واجهة برمجة التطبيقات أولاً على محاذاة المسار مع الطريق الأكثر احتمالاً الذي سلكته المركبة (كما تفعل مع طلب snapToRoads)، ثم تحدّد الحد الأقصى للسرعة في الجزء ذي الصلة من الطريق. إذا كنت لا تريد أن تضبط واجهة برمجة التطبيقات المسار على أقرب نقطة، عليك تمرير المَعلمة placeId كما هو موضّح أدناه. يعرض المثال التالي المَعلمة path مع ثلاث مجموعات من خطوط الطول والعرض:
path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796.
placeId: معرّفات الأماكن التي تمثّل جزءًا واحدًا أو أكثر من الطريق
تأكَّد من أنّ كل رقم تعريف مكان يشير إلى جزء من طريق وليس إلى نوع مختلف من الأماكن. يمكنك إرسال ما يصل إلى 100 معرّف مكان مع كل طلب. لا تنفّذ واجهة برمجة التطبيقات عملية ربط الأماكن بالطرق على معرّفات الأماكن المقدَّمة.
تتضمّن الاستجابة حدًا للسرعة لكل معرّف مكان في الطلب.
يمكنك إرسال طلب snapToRoads أو nearestRoads
للعثور على أرقام تعريف الأماكن ذات الصلة، ثم تقديمها كمدخل لطلب
speedLimits. يوضّح المثال التالي المَعلمة
placeId مع معرّفَي مكان:
placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
استبدِل key بمفتاح واجهة برمجة التطبيقات لتطبيقك. يجب أن يحدّد تطبيقك هويته في كل مرة يرسل فيها طلبًا إلى Roads API من خلال تضمين مفتاح واجهة برمجة التطبيقات مع كل طلب.
كيفية الحصول على مفتاح
المَعلمات الاختيارية
استبدِل units بما إذا كنت تريد عرض حدود السرعة بالكيلومترات أو الأميال في الساعة. يمكن ضبط هذه السمة على KPH أو MPH. القيمة التلقائية هي KPH.
الردود
قد تتضمّن استجابة speedLimits العناصر التالية:
speedLimits: مصفوفة من البيانات الوصفية للطرق يتكوّن كل عنصر من الحقول التالية:
placeId: معرّف فريد لمكان. ستكون جميع معرّفات الأماكن التي تعرضها Roads API مرتبطة بأجزاء من الطرق.
speedLimit: الحد الأقصى للسرعة على جزء الطريق هذا
units: تعرض إما KPH أو MPH.
snappedPoints: مصفوفة من النقاط المحاذية لا تظهر هذه المصفوفة إلا إذا كان الطلب يتضمّن المَعلمة path. تتألف كل نقطة من الحقول التالية:
location: يحتوي على قيمة latitude وقيمة longitude.
originalIndex: عدد صحيح يشير إلى القيمة المقابلة في الطلب الأصلي. يجب أن تكون كل قيمة في الطلب مرتبطة بقيمة
محدّدة في الردّ. يتم فهرسة هذه القيم بدءًا من 0، لذا ستكون النقطة التي تتضمّن originalIndex بقيمة 4 هي القيمة المحاذية لخط العرض/خط الطول الخامس الذي تم تمريره إلى المَعلمة path.
placeId: معرّف فريد لمكان. ستكون جميع معرّفات الأماكن التي تعرضها Roads API مرتبطة بأجزاء من الطرق.
يمكن تمرير placeId في طلبات حدود السرعة لتحديد الحد الأقصى للسرعة على طول جزء الطريق هذا.
warning_message: سلسلة تحتوي على تحذير يظهر للمستخدم.
مثال على طلب باستخدام مسار
يحصل هذا الطلب على الحدّ الأقصى للسرعة لكل جزء من الطريق الأقرب إلى أزواج خطوط الطول والعرض المحدّدة في مسار يعبر جسر فاسكو دا غاما في لشبونة، البرتغال.
{
speedLimits:
[
{
placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE",
speedLimit: 105,
units: "KPH"
},
{
placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU",
speedLimit: 70,
units: "KPH"
},
{
placeId: "ChIJJ4vQRudkJA0RpednU70A-5M",
speedLimit: 55,
units: "KPH"
}
],
snappedPoints:
[
{
location:
{
latitude: 38.75807927603043,
longitude: -9.037417546438084
},
originalIndex: 0,
placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE"
},
{
location:
{
latitude: 38.689653701836896,
longitude: -9.177051486847693
},
originalIndex: 1,
placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU"
},
{
location:
{
latitude: 41.13993011767777,
longitude: -8.609400794783655
},
originalIndex: 2,
placeId: "ChIJJ4vQRudkJA0RpednU70A-5M"
}
],
warningMessage: "Input path is too sparse. You should provide a path where consecutive points are closer to each other. Refer to the 'path' parameter in Google Roads API documentation."
}
لاحظ رسالة التحذير بشأن تباعد النقاط في الردّ أعلاه. إذا كنت تطلب حدود السرعة لأقرب مقاطع طرق عند نقاط عشوائية، عليك استدعاء speedLimits باستخدام أرقام تعريف الأماكن التي تم استردادها من نقطة النهاية nearestRoads بدلاً من ذلك.
مثال على طلب باستخدام أرقام تعريف الأماكن
بدلاً من استخدام أزواج خطوط الطول والعرض، يمكنك تمرير معرّفات الأماكن الخاصة بأجزاء الطرق. ننصحك بالحصول على معرّفات الأماكن الخاصة بأقسام الطرق باستخدام طلبات snapToRoads أو nearestRoads. عند تمرير معرّفات الأماكن، تعرض واجهة برمجة التطبيقات الحد الأقصى للسرعة لجزء الطريق الممثّل بكل معرّف مكان. لا تطبّق واجهة برمجة التطبيقات أي عملية ربط بالطريق على أرقام تعريف الأماكن المقدَّمة.
يطلب المثال التالي حدود السرعة لبعض أجزاء الطرق التي تعبر جسر فاسكو دا غاما في لشبونة، البرتغال.
للحدّ من عدد الطلبات التي يتم إرسالها إلى خدمة "حدود السرعة"، ننصح بأخذ عيّنات من المواقع الجغرافية لمواد العرض على فترات تتراوح بين 5 و15 دقيقة (تعتمد القيمة الدقيقة على السرعة التي تتحرّك بها مادة العرض). إذا كانت مادة العرض ثابتة، يكفي الحصول على عيّنة واحدة من الموقع الجغرافي (لا حاجة إلى إجراء طلبات متعدّدة).
للحدّ من وقت الاستجابة الإجمالي، ننصحك باستدعاء خدمة "حد السرعة" مرة واحدة بعد تجميع بعض البيانات، بدلاً من استدعاء واجهة برمجة التطبيقات في كل مرة يتم فيها تلقّي الموقع الجغرافي لأحد الأجهزة الجوّالة.
لماذا لا تظهر بعض حدود السرعة أو كلها؟
السبب الأكثر شيوعًا لعدم توفّر speedLimits هو طلب الحد الأقصى للسرعة
في مكان ليس جزءًا من طريق.
يستخدم المثال أعلاه جسر "فاسكو دا غاما" لتوضيح المفاهيم؛
يدعم الجسر الطريق السريع E90 الذي يعبر فوق نهر تاجة. ويحمل الجسر
نفسه رقم تعريف المكان ChIJUzt97ZEwGQ0RM1JzQfqoDtU. يمثّل مقطع الطريق الأول
في الردّ أعلاه جزءًا من الطريق E90 ويحمل رقم تعريف المكان
ChIJX12duJAwGQ0Ra0d4Oi4jOGE. في مثال الطلب، إذا استبدلت معرّف المكان الخاص بالطريق بمعرّف المكان الخاص بالجسر، لن يظهر في الرد سوى حدّين للسرعة في مصفوفة speedLimits لأنّ معرّف المكان الخاص بالجسر لا يشير إلى جزء فردي من الطريق. علاوةً على ذلك، إذا لم تكن أي من معرّفات الأماكن مخصّصة لأجزاء من الطرق، لن يتضمّن الرد أي حدود للسرعة.
عند إرسال طلبات بشأن حدود السرعة باستخدام معرّفات الأماكن، تأكَّد من أنّ كل معرّف مكان يشير إلى جزء من طريق وليس إلى نوع مختلف من الأماكن. يمكن الحصول على أرقام تعريف الأماكن الخاصة بأجزاء الطرق الفردية بشكل أفضل باستخدام طلبات snapToRoads أو nearestRoads، ويمكن لأي منهما عرض أرقام تعريف أماكن متعددة من خلال طلب واحد.
تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Roads API returns the posted speed limit for given road segments, but the accuracy of the data is not guaranteed and may not be real-time.\u003c/p\u003e\n"],["\u003cp\u003eYou can request speed limits by providing a path of latitude/longitude pairs or place IDs of road segments, using the \u003ccode\u003epath\u003c/code\u003e or \u003ccode\u003eplaceId\u003c/code\u003e parameters respectively.\u003c/p\u003e\n"],["\u003cp\u003eThe response includes the speed limit, units (KPH or MPH), and may include snapped points if a path was provided.\u003c/p\u003e\n"],["\u003cp\u003eSpeed limit data might be missing if the requested place ID is not a road segment; use \u003ccode\u003esnapToRoads\u003c/code\u003e or \u003ccode\u003enearestRoads\u003c/code\u003e to obtain place IDs for road segments.\u003c/p\u003e\n"],["\u003cp\u003eTo optimize usage, sample asset locations at intervals and batch speed limit requests for reduced latency and API calls.\u003c/p\u003e\n"]]],["The Speed Limit service, available with an Asset Tracking license, returns posted speed limits for road segments via the Roads API. Requests, sent via HTTPS, require either a `path` (latitude/longitude pairs) or `placeId` of road segments. The API can snap paths to roads or directly use road segment place IDs. Optional parameters include `units` (KPH/MPH). Responses provide speed limit, units, and place ID. Accuracy isn't guaranteed. Optimal use includes sampling locations every 5-15 minutes, and batching requests. Ensure PlaceIds refer to road segments.\n"],null,["# Speed limits\n\n| **Notice:** The Speed Limit service is available to all customers with an [Asset\n| Tracking](https://cloud.google.com/maps-platform/asset-tracking) license. For [Google Maps Platform Premium Plan](/maps/premium) customers who transitioned to pay-as-you-go pricing, the Speed Limit feature remains active on projects with Asset Tracking capabilities (projects with a project ID in the format maps-asset-xxx).\n\nThe Roads API returns the posted speed limit for a given road\nsegment. In the case of road segments with variable speed limits, the default\nspeed limit for the segment is returned.\n\nThe accuracy of speed limit data returned by the Roads API\ncannot be guaranteed. The speed limit data provided is not real-time, and may be\nestimated, inaccurate, incomplete, or outdated. See [coverage details](/maps/coverage)\nto see the regions where speed limit data is available.\n\nRequests\n--------\n\nSend requests for speed limits using HTTPS, in the following form: \n\n```scdoc\nhttps://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY\n```\n\n\u003cbr /\u003e\n\n### Parameter usage\n\n**Required parameters**\n\n- Either a `path` or a `placeId` parameter.\n - `path` --- A list of up to 100 latitude/longitude pairs representing a path. Latitude and longitude values must be separated by commas. Latitude/longitude pairs must be separated by the pipe character: \"\\|\". When you supply the `path` parameter, the API first snaps the path to the most likely road traveled by a vehicle (as it does for the [`snapToRoads`](/maps/documentation/roads/snap) request), then determines the speed limit for the relevant road segment. If you don't want the API to snap the path, you must pass a `placeId` parameter as explained below. The following example shows the `path` parameter with three latitude/longitude pairs: `path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796`.\n - `placeId` --- The place ID(s) representing one or more road segments. Make sure each place ID refers to a road segment and not a different type of place. You can pass up to 100 place IDs with each request. The API does not perform road-snapping on the supplied place IDs. The response includes a speed limit for each place ID in the request. You can send a [`snapToRoads`](/maps/documentation/roads/snap) or [`nearestRoads`](/maps/documentation/roads/nearest) request to find the relevant place IDs then supply them as input to the `speedLimits` request. The following example shows the `placeId` parameter with two place IDs: `placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU`\n- `key` --- Your application's API key. Your application must identify itself every time it sends a request to the Roads API by including an API key with each request. Learn how to [get a key](/maps/documentation/roads/get-api-key).\n\n**Optional parameters**\n\n- `units` --- Whether to return speed limits in kilometers or miles per hour. This can be set to either `KPH` or `MPH`. Defaults to `KPH`.\n\nResponses\n---------\n\nThe following elements may be present in a `speedLimits` response:\n\n- `speedLimits` --- An array of road metadata. Each element consists of the following fields:\n - `placeId` --- A unique identifier for a place. All place IDs returned by the Roads API will correspond to road segments.\n - `speedLimit` --- The speed limit for that road segment.\n - `units` --- Returns either `KPH` or `MPH`.\n- `snappedPoints` --- an array of snapped points. This array is present only if the request contained a `path` parameter. Each point consists of the following fields:\n - `location` --- contains a `latitude` and `longitude` value.\n - `originalIndex` --- An integer that indicates the corresponding value in the original request. Each value in the request should map to a snapped value in the response. These values are indexed from `0`, so a point with an `originalIndex` of `4` will be the snapped value of the 5th latitude/longitude passed to the `path` parameter.\n - `placeId` --- A unique identifier for a place. All place IDs returned by the Roads API will correspond to road segments. The `placeId` can be passed in a speed limits request to determine the speed limit along that road segment.\n- `warning_message` --- A string containing a user-visible warning.\n\nExample request using a path\n----------------------------\n\nThis request gets the speed limit for each road segment nearest to the\nspecified latitude/longitude pairs in a path crossing the Vasco da Gama\nbridge in Lisbon, Portugal.\n\n**Request** \n\n```scdoc\nhttps://roads.googleapis.com/v1/speedLimits?path=38.75807927603043,-9.03741754643809|38.6896537,-9.1770515|41.1399289,-8.6094075&key=YOUR_API_KEY\n```\n\n**Response** \n\n```text\n{\n speedLimits:\n [\n {\n placeId: \"ChIJX12duJAwGQ0Ra0d4Oi4jOGE\",\n speedLimit: 105,\n units: \"KPH\"\n },\n {\n placeId: \"ChIJLQcticc0GQ0RoiNZJVa5GxU\",\n speedLimit: 70,\n units: \"KPH\"\n },\n {\n placeId: \"ChIJJ4vQRudkJA0RpednU70A-5M\",\n speedLimit: 55,\n units: \"KPH\"\n }\n ],\n snappedPoints:\n [\n {\n location:\n {\n latitude: 38.75807927603043,\n longitude: -9.037417546438084\n },\n originalIndex: 0,\n placeId: \"ChIJX12duJAwGQ0Ra0d4Oi4jOGE\"\n },\n {\n location:\n {\n latitude: 38.689653701836896,\n longitude: -9.177051486847693\n },\n originalIndex: 1,\n placeId: \"ChIJLQcticc0GQ0RoiNZJVa5GxU\"\n },\n {\n location:\n {\n latitude: 41.13993011767777,\n longitude: -8.609400794783655\n },\n originalIndex: 2,\n placeId: \"ChIJJ4vQRudkJA0RpednU70A-5M\"\n }\n ],\n warningMessage: \"Input path is too sparse. You should provide a path where consecutive points are closer to each other. Refer to the 'path' parameter in Google Roads API documentation.\"\n}\n```\n\nNotice the **warning message** for point sparsity in the above response. If you\nare requesting speed limits for the nearest road segments at arbitrary points,\nyou must call `speedLimits` with place IDs retrieved from the\n[`nearestRoads`](/maps/documentation/roads/nearest) endpoint instead.\n\nExample request using place IDs\n-------------------------------\n\nInstead of using latitude/longitude pairs, you can pass the place IDs of the\nroad segments. We recommend you obtain place IDs for road segments using\n`snapToRoads` or `nearestRoads` requests. When you pass place IDs, the API\nreturns the speed limit for the road segment represented by each place ID. The\nAPI does not apply any road-snapping to the place IDs supplied.\n\nThe following example requests the speed limits for some of the road segments\nthat cross the Vasco da Gama bridge in Lisbon, Portugal.\n\n**Request** \n\n```scdoc\nhttps://roads.googleapis.com/v1/speedLimits?placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU&placeId=ChIJJ4vQRudkJA0RpednU70A-5M&key=YOUR_API_KEY\n```\n\n**Response** \n\n```text\n{\n \"speedLimits\": [\n {\n placeId: \"ChIJX12duJAwGQ0Ra0d4Oi4jOGE\",\n speedLimit: 105,\n units: \"KPH\"\n },\n {\n placeId: \"ChIJLQcticc0GQ0RoiNZJVa5GxU\",\n speedLimit: 70,\n units: \"KPH\"\n },\n {\n placeId: \"ChIJJ4vQRudkJA0RpednU70A-5M\",\n speedLimit: 55,\n units: \"KPH\"\n }\n ]\n}\n```\n\nUsage recommendations\n---------------------\n\nTo minimize the volume of calls to the Speed Limit service, we recommend\nsampling the locations of your assets at 5 to 15 minute intervals (the exact\nvalue depends on the speed at which an asset is traveling). If an asset is\nstationary, a single location sample is sufficient (there is no need to make\nmultiple calls).\n\nTo minimize overall latency, we recommend calling the Speed Limit service\nonce you have accumulated some data, rather than calling the API every time the\nlocation of a mobile asset is received.\n\nWhy are some/all speed limits missing?\n--------------------------------------\n\nThe most common cause of missing `speedLimits` is requesting the speed limit\nof a place that is not a road segment.\n\nThe above example uses the Vasco da Gama bridge to illustrate concepts;\nthe bridge supports the road E90 crossing over the Rio Tejo. The bridge\nitself has a place ID of ChIJUzt97ZEwGQ0RM1JzQfqoDtU. The first road segment\nin the above response is part of the E90 road and has a place ID of\nChIJX12duJAwGQ0Ra0d4Oi4jOGE. In the example request, if you replace the road\nplace ID with the bridge's place ID, then in the response there will only be\ntwo speed limits in the `speedLimits` array because the bridge's place ID\ndoes not refer to an individual road segment. Furthermore, if none of the\nplace IDs are for road segments, then the response won't contain any\nspeed limits.\n\nWhen making speed limit requests using place IDs, make sure each place ID\nrefers to a road segment and not a different type of place. Place IDs for\nindividual road segments are best retrieved using `snapToRoads`\nor `nearestRoads` requests, either of which can return multiple place IDs from\na single call."]]
