تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
نظرة عامة على ميزة "البحث على طول المسار"
تتوفّر ميزات "البحث على طول الطريق" في واجهات Places (New) API التالية:
"البحث النصي" (جديد) فقط: البحث عن أماكن على طول مسار رحلة محدّد مسبقًا
البحث النصي (جديد) و"البحث في مكان قريب" (جديد): يتم احتساب ملخّص التوجيه من موقع جغرافي محدّد إلى كل مكان في نتائج البحث.
"البحث النصي" (جديد) فقط: احتساب ملخّص التوجيه لكل مكان
على طول مسار رحلة محدّد مسبقًا
البحث على طول مسار
يمكنك استخدام Routes API لحساب مسار الرحلة بين موقعَين جغرافيَين. يمكن لواجهة Routes API احتساب مسار لسيارة أو دراجة أو مركبة ذات عجلتين أو نظام نقل عام أو للمشي.
تتيح لك ميزة البحث النصي (جديدة) استخدام هذا المسار المحسوب لإجراء بحث على طول مسار. باستخدام هذا الخيار، يمكنك تمرير المسار المحسوب مسبقًا من Routes API إلى طلب Text Search (New). تحتوي الاستجابة بعد ذلك على الأماكن التي تتطابق مع معايير البحث وتقع أيضًا بالقرب من المسار المحدّد.
يشبه البحث على طول مسار استخدام خيارات الطلب locationRestriction أو locationBias لتحديد نتائج البحث. تعرض locationRestriction
نتائج البحث التي تقع ضمن حدود إطار العرض، بينما قد تعرض locationBias نتائج بحث خارج إطار العرض. في المقابل، يتيح لك الخياران locationBias وlocationRestriction تحديد منطقة لتفضيل نتائج البحث، كما تتيح لك ميزة "البحث على طول المسار" في "البحث النصي" أيضًا تفضيل نتائج البحث لتضمين النتائج التي تتضمّن أقل أوقات الانحراف عن المسار من نقطة بداية المسار إلى وجهته. يمكنك تحسين نتائج البحث باستخدام locationBias أو locationRestriction مع الخط المتعدد الأضلاع.
على سبيل المثال، لنفترض أنّ لديك المسار من نقطة الانطلاق، والتي يُشار إليها باسم نقطة طريق في Routes API، إلى الوجهة كما هو محسوب بواسطة Routes API:
عند البحث على طول المسار، يتم إعطاء الأولوية للأماكن القريبة من المسار والتي لا تستغرق وقتًا طويلاً للوصول إليها من نقطة الانطلاق إلى الوجهة. في هذا المثال، النقاط "أ" و"ب" و"ج" هي أماكن تم عرضها كنتيجة للبحث.
حساب ملخّص التوجيه
يمكن لخدمتَي البحث النصي (جديد) والبحث بالقرب مني (جديد)
حساب ملخّص التوجيه، أي المدة والمسافة، إلى كل
مكان في الرد استنادًا إلى الموقع الجغرافي الأصلي للتوجيه المحدّد في
الطلب. عند تحديد نقطة انطلاق التوجيه، لا يتضمّن الرد قائمة بالأماكن التي تتطابق مع البحث فحسب، بل يتضمّن أيضًا مدة السفر والمسافة من نقطة انطلاق التوجيه إلى كل مكان.
في الصورة التالية، النقاط A وB وC هي أماكن تم عرضها في ردّ البحث:
بالنسبة إلى كل مكان في النتائج، يتضمّن الردّ مدة السفر والمسافة من نقطة الانطلاق إلى المكان، إذا كان ذلك متاحًا.
يتم تلقائيًا احتساب مدة الرحلة ومسافتها باستخدام الخيار TRAFFIC_UNAWARE في واجهة Routes API. يمكنك اختياريًا ضبط إعدادات توجيه المسار المفضّلة لأخذ ظروف الزحام المباشر TRAFFIC_AWARE_OPTIMAL أو ظروف الزحام المباشر مع تقليل وقت الاستجابة TRAFFIC_AWARE في الاعتبار أثناء إجراء العمليات الحسابية.
لمحة عن المسارات وأجزائها ونقاط المرور
تتألف الرحلة من عدة مكوّنات، كما تحتسبها واجهة Routes API:
يتألف المسار من المكوّنات التالية:
نقطة الطريق: لاحتساب مسار، عليك تحديد الموقع الجغرافي لنقطة الانطلاق والوجهة كحد أدنى. يمكنك تحديد هذه المواقع الجغرافية على أنّها نقاط طريق على المسار. نقاط الطريق الوسيطة هي مواقع جغرافية تقع بين نقطة الانطلاق والوجهة، وتريد أن يمر المسار بها.
المسار: الرحلة بأكملها من نقطة الانطلاق، مرورًا بأي نقاط توقف وسيطة، إلى نقطة التوقف النهائية. يتألف مسار الرحلة من مرحلة واحدة أو أكثر.
عند تمرير مسار إلى Text Search، عليك تمرير السلسلة المتعددة الخطوط المرمّزة الخاصة بالمسار كما تعرضها Routes API. الخط المتعدد الأضلاع المشفّر هو قائمة مشفّرة بنقاط خطوط الطول والعرض تتيح لك تمثيل الخط المتعدد الأضلاع الخاص بالمسار كسلسلة.
المقطع: المسار من نقطة طريق في مسار إلى نقطة الطريق التالية في المسار يتكوّن كل جزء من خطوة واحدة أو أكثر.
يحتوي المسار على جزء منفصل للمسار من كل نقطة طريق إلى النقطة التالية.
على سبيل المثال، إذا كان المسار يتضمّن نقطة طريق واحدة للانطلاق ونقطة طريق واحدة للوجهة، سيتضمّن المسار جزءًا واحدًا.
بالنسبة إلى كل نقطة طريق إضافية تضيفها إلى المسار بعد نقطة البداية والوجهة، والتي تُعرف باسم نقطة طريق وسيطة، تضيف واجهة برمجة التطبيقات جزءًا منفصلاً.
لمزيد من المعلومات حول المسارات وطريقة احتسابها، يُرجى الاطّلاع على Routes API.
حساب ملخّص التوجيه من خلال البحث على طول المسار
يمكنك دمج عمليات حساب ملخّص التوجيه مع البحث على طول مسار.
في هذه الحالة، تعرض خدمة البحث النصي (جديد) مدة السفر والمسافة إلى كل مكان في الرد، ثم من كل مكان إلى الوجهة النهائية للمسار. يمكنك اعتبار هذه العملية الحسابية بمثابة توفير مدة السفر ومسافته في حال الانحراف عن المسار المحدّد للوصول إلى مكان ضمن نتائج البحث، ثم مواصلة الرحلة إلى الوجهة النهائية.
على سبيل المثال، إليك المسار التالي من نقطة البداية إلى الوجهة كما هو
محسوب بواسطة Routes API. مرِّر هذا المسار إلى واجهة برمجة التطبيقات Text Search (New) مع معايير البحث.
في هذا المثال، الموقع الجغرافي A هو مكان تم عرضه في نتائج البحث من خلال خدمة Text Search (الجديدة). بالنسبة إلى كل مكان في الردّ، يتضمّن البحث المدة والمسافة اللازمتَين للانحراف إلى ذلك المكان في رحلة من مرحلتَين:
يتضمّن الجزء الأول من الرحلة مدة السفر والمسافة من نقطة الانطلاق إلى المكان. في هذا المثال، من نقطة البداية إلى المكان (أ).
يتضمّن الجزء الثاني مدة السفر والمسافة من المكان إلى وجهة المسار. في هذا المثال، من A إلى الوجهة.
من المعلومات الواردة في الردّ، يمكنك بعد ذلك حساب مدة الرحلة غير المباشرة ومسافتها، حيث:
\(t_{OD}\) هي مدة الرحلة من نقطة الانطلاق إلى الوجهة،
\(s_{OD}\) هي مسافة الرحلة من نقطة الانطلاق إلى الوجهة
\(t_{OA}\) هي مدة الرحلة من نقطة الانطلاق إلى النقطة A، و \(s_{OA}\) هي مسافة الرحلة من نقطة الانطلاق إلى النقطة A
\(t_{AD}\) هي مدة الرحلة من النقطة A إلى الوجهة،
\(s_{AD}\) هي مسافة الرحلة من النقطة A إلى الوجهة
مدة التوقف هي فرق المدة بين الرحلة الأصلية (من نقطة الانطلاق إلى الوجهة) والرحلة الجديدة (من نقطة الانطلاق إلى الوجهة عبر النقطة A):
$$
t_{detour} = t_{OA} + t_{AD} - t_{OD}
$$
مسافة الانحراف هي فرق المسافة بين الرحلة الأصلية (من نقطة الانطلاق إلى الوجهة) والرحلة الجديدة (من نقطة الانطلاق إلى الوجهة عبر النقطة A):
تاريخ التعديل الأخير: 2025-09-04 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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-09-04 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Places API's Search along route feature lets you find places near a predefined route calculated using the Routes API, prioritizing places with minimal detour times.\u003c/p\u003e\n"],["\u003cp\u003eYou can calculate the routing summary (duration and distance) from a specified origin to each place in the search results using Text Search (New) and Nearby Search (New).\u003c/p\u003e\n"],["\u003cp\u003eText Search (New) allows combining search along a route with routing summary calculations, providing detour duration and distance for each place found.\u003c/p\u003e\n"],["\u003cp\u003eA route comprises waypoints (origin, destination, and optional intermediate points), legs (paths between waypoints), and steps (discrete segments within legs).\u003c/p\u003e\n"],["\u003cp\u003eWhile \u003ccode\u003elocationBias\u003c/code\u003e and \u003ccode\u003elocationRestriction\u003c/code\u003e bias search results to a region, search along route in Text Search (New) biases results to places near a route with minimal detour times.\u003c/p\u003e\n"]]],[],null,["Overview of search along route\n==============================\n\nSearch along route features are available in the following Places (New) APIs:\n\n- **Text Search (New) only:** Search for places along a predefined trip route.\n- **Text Search (New) and Nearby Search (New):** Calculate the routing summary from a specified routing origin location to each place in the search results.\n- **Text Search (New) only:** Calculate the routing summary for each place along a predefined trip route.\n\nSearch along a route\n--------------------\n\nYou use the [Routes API](/maps/documentation/routes) to calculate the trip route\nbetween two locations. The Routes API can calculate a route for a car, bicycle,\ntwo-wheel vehicle, transit system, or for walking.\n| **Note:** Transit system routes are not supported by the Places API.\n\n[Text Search (New)](/maps/documentation/places/web-service/text-search) lets you use this calculated route to perform a\n**search along a route**. With this option, you pass the precalculated route\nfrom the Routes API to the Text Search (New) request. The response then contains\nplaces that match the search criteria and are also located near the specified\nroute.\n\nSearching along a route is similar to using the `locationRestriction` or\n`locationBias` request options to bias the search results. `locationRestriction`\nreturns search results that fall within the viewport bounds, while\n`locationBias` may return search results outside of the viewport. However, while\nthe `locationBias` and `locationRestriction` options let you specify a region to\nbias the search results, the search along route feature in Text Search also lets\nyou bias the search results to include those with minimal detour times from the\nroute origin to the route destination. You can bias search results using either\n`locationBias` or `locationRestriction` in combination with the polyline.\n\nFor example, consider the route from the origin, referred to as a\n**waypoint** in the Routes API, to the destination as calculated by the Routes\nAPI:\n\nWhen you search along the route, the search is biased to return places near the\nroute with minimal detour times from the origin to the destination. In this\nexample, points A, B, and C are places returned by the search.\n\nCalculate routing summary\n-------------------------\n\n[Text Search (New)](/maps/documentation/places/web-service/text-search) and [Nearby Search (New)](/maps/documentation/places/web-service/nearby-search) can\ncalculate the **routing summary** , meaning the duration and distance, to each\nplace in the response based on the specified **routing origin location** in the\nrequest. When you specify the routing origin, the response not only contains a\nlist of places that match the search, but also the travel duration and distance\nfrom the routing origin to each place.\n\nIn the following image, points A, B, and C are places returned in the search\nresponse:\n\nFor each place in the results, the response contains the travel duration and\ndistance from the routing origin to the place, if available.\n| **Note:** This is only an estimate of the routing information. To get the actual route details, including step-by-step directions, use the [Routes\n| API](/maps/documentation/routes/compute_route_directions).\n\nBy default, the travel duration and distance is calculated using the [`TRAFFIC_UNAWARE`](/maps/documentation/routes/config_trade_offs#traffic_unaware)\noption in the Routes API. You can optionally set routing preferences to take\nlive traffic conditions [`TRAFFIC_AWARE_OPTIMAL`](/maps/documentation/routes/config_trade_offs#traffic_aware_optimal)\nor latency-reduced live traffic conditions [`TRAFFIC_AWARE`](/maps/documentation/routes/config_trade_offs#traffic_aware)\ninto consideration during calculations.\n| **Note:** `TRAFFIC_AWARE` and `TRAFFIC_OPTIMAL` only apply to the `DRIVE` and `TWO_WHEELER` travel modes. If either routing preference is specified with an unsupported travel mode, the routing summary calculation defaults to using the `TRAFFIC_UNAWARE` option. If `TWO_WHEELER` is specified in an [unsupported region](/maps/documentation/routes/coverage-two-wheeled), the API returns an empty routing summary.\n| When you set the [`TRAFFIC_AWARE`](/maps/documentation/routes/config_trade_offs#traffic_aware) routing preference, routes are calculated accounting for traffic conditions. As a result, the route and route details more accurately reflect real-world conditions. Since this increase in data quality comes at the expense of response latency, performance optimizations are applied to reduce much of the latency. When you set the [`TRAFFIC_AWARE_OPTIMAL`](/maps/documentation/routes/config_trade_offs#traffic_aware_optimal) routing preference, routes are calculated accounting for traffic conditions, but no performance optimizations are applied. In this mode, the server performs a more exhaustive search of the road network to find the optimal route.\n\n### About routes, legs, and waypoints\n\nSeveral components make up a route, as calculated by the Routes API:\n\nA route consists of the following components:\n\n- **Waypoint** : To calculate a route, you specify at a minimum the locations of the origin and destination. You define these locations as *waypoints* on the route. *Intermediate waypoints* are locations in between the origin and destination that you want the route to go through.\n- **Route** : The entire trip from the origin waypoint, through any\n intermediate waypoints, to the destination waypoint. A route consists of one\n or more **legs**.\n\n When passing a route to Text Search, you pass the [route's encoded\n polyline](/maps/documentation/routes/traffic_on_polylines) as returned by the [Routes API](/maps/documentation/routes). An encoded\n polyline is an encoded list of latitude and longitude points that lets you represent the\n route's polyline as a string.\n- **Leg** : The path from one waypoint in a route to the next waypoint in the\n route. Each leg consists of one or more discrete **steps**.\n\n A route contains a separate leg for the path from each waypoint to the next.\n For example, if the route contains a single origin waypoint and a single\n destination waypoint, then the route contains a single leg.\n\n For each additional waypoint you add to the route after the origin and\n destination, called an *intermediate* waypoint, the API adds a separate leg.\n\nFor more information on routes and calculating routes, see the [Routes\nAPI](/maps/documentation/routes).\n\nCalculate the routing summary with a search along route\n-------------------------------------------------------\n\nYou can combine **routing summary** calculations with **search along a route** .\nIn this case, [Text Search (New)](/maps/documentation/places/web-service/text-search) returns the travel duration and\ndistance to each place in the response, and then from each place to the final\ndestination of the route. Think of this calculation as providing a travel\nduration and distance if you detour from the specified route to travel to a\nplace in the search results, and then continue on to the final destination.\n\nFor example, consider the following route from the origin to the destination as\ncalculated by the Routes API. Pass this route to the Text Search (New) API along\nwith your search criteria.\n\nIn this example, location A is a place returned in the search results from\nText Search (New). For each place in the response, the search includes the duration\nand distance required to detour to that place as a **two-leg trip**:\n\n- The first leg contains the travel duration and distance from the route **origin** to the **place**. In this example, from the origin to place A.\n- The second leg contains the travel duration and distance from the **place** to the route **destination**. In this example, from A to the destination.\n\nFrom the information in the response, you can then calculate the **detour\nduration and distance**, where:\n\n- \\\\(t_{OD}\\\\) is the **trip duration** from the origin to the destination, \\\\(s_{OD}\\\\) is the **trip distance** from the origin to the destination\n- \\\\(t_{OA}\\\\) is the **trip duration** from the origin to A; \\\\(s_{OA}\\\\) is the **trip distance** from the origin to A\n- \\\\(t_{AD}\\\\) is the **trip duration** from A to the destination; \\\\(s_{AD}\\\\) is the **trip distance** from A to the destination\n\n**Detour duration** is the **duration difference** between the **original trip**\n(from the origin to the destination) and the **new trip** (from the origin to\nthe destination **through** A): \n$$ t_{detour} = t_{OA} + t_{AD} - t_{OD} $$\n\n**Detour distance** is the **distance difference** between the **original trip**\n(from the origin to the destination) and the **new trip** (from the origin to\nthe destination **through** A): \n$$ s_{detour} = s_{OA} + s_{AD} - s_{OD} $$"]]
