المفاهيم المتقدّمة

جارٍ الحصول على البيانات

تتوفّر عدة طرق للحصول على بيانات الموقع الجغرافي التي تم جمعها. سنوضّح هنا طريقتَين للحصول على بيانات لاستخدامها مع ميزة محاذاة إلى الطرق في Roads API.

GPX

تنسيق GPX هو تنسيق مفتوح يستند إلى XML لمشاركة المسارات والمسارات ونقاط الطريق، ويتم التقاطها من خلال أجهزة نظام تحديد المواقع العالمي (GPS). يستخدم هذا المثال محلّل XmlPull، وهو محلّل XML خفيف الحجم متوفّر لكل من خادم Java وبيئات الأجهزة الجوّالة.

/**
 * Parses the waypoint (wpt tags) data into native objects from a GPX stream.
 */
private List<LatLng> loadGpxData(XmlPullParser parser, InputStream gpxIn)
        throws XmlPullParserException, IOException {
    // We use a List<> as we need subList for paging later
    List<LatLng> latLngs = new ArrayList<>();
    parser.setInput(gpxIn, null);
    parser.nextTag();

    while (parser.next() != XmlPullParser.END_DOCUMENT) {
        if (parser.getEventType() != XmlPullParser.START_TAG) {
            continue;
        }

        if (parser.getName().equals("wpt")) {
            // Save the discovered latitude/longitude attributes in each <wpt>.
            latLngs.add(new LatLng(
                    Double.valueOf(parser.getAttributeValue(null, "lat")),
                    Double.valueOf(parser.getAttributeValue(null, "lon"))));
        }
        // Otherwise, skip irrelevant data
    }

    return latLngs;
}

إليك بعض بيانات GPX الأولية التي تم تحميلها على خريطة.

خدمات الموقع الجغرافي من Android

تختلف أفضل طريقة لالتقاط بيانات نظام تحديد المواقع العالمي (GPS) من جهاز Android حسب حالة الاستخدام التي تستخدمها. يمكنك إلقاء نظرة على صف التدريب الخاص بنظام Android حول تلقّي تحديثات الموقع الجغرافي، بالإضافة إلى نماذج المواقع الجغرافية على Google Play على GitHub.

معالجة المسارات الطويلة

نظرًا لأن ميزة المحاذاة إلى الطرق تستنتج الموقع الجغرافي استنادًا إلى المسار الكامل، بدلاً من النقاط الفردية، ستحتاج إلى الاهتمام عند معالجة المسارات الطويلة (أي المسارات التي تتجاوز الحد الأقصى المسموح به وهو 100 نقطة لكل طلب).

للتعامل مع الطلبات الفردية كمسار طويل واحد، يجب تضمين بعض التداخل، مثل تضمين النقاط النهائية من الطلب السابق كأول نقطة من الطلب التالي. ويعتمد عدد النقاط المطلوب تضمينها على دقة بياناتك. يجب تضمين المزيد من النقاط للطلبات المنخفضة الدقة.

يستخدم هذا المثال برنامج Java لبرنامج "خرائط Google" لإرسال الطلبات المقسّمة إلى صفحات، ثم إعادة دمج البيانات، بما في ذلك النقاط المستنتَجة في القائمة التي تم عرضها.

/**
 * Snaps the points to their most likely position on roads using the Roads API.
 */
private List<SnappedPoint> snapToRoads(GeoApiContext context) throws Exception {
    List<SnappedPoint> snappedPoints = new ArrayList<>();

    int offset = 0;
    while (offset < mCapturedLocations.size()) {
        // Calculate which points to include in this request. We can't exceed the API's
        // maximum and we want to ensure some overlap so the API can infer a good location for
        // the first few points in each request.
        if (offset > 0) {
            offset -= PAGINATION_OVERLAP;   // Rewind to include some previous points.
        }
        int lowerBound = offset;
        int upperBound = Math.min(offset + PAGE_SIZE_LIMIT, mCapturedLocations.size());

        // Get the data we need for this page.
        LatLng[] page = mCapturedLocations
                .subList(lowerBound, upperBound)
                .toArray(new LatLng[upperBound - lowerBound]);

        // Perform the request. Because we have interpolate=true, we will get extra data points
        // between our originally requested path. To ensure we can concatenate these points, we
        // only start adding once we've hit the first new point (that is, skip the overlap).
        SnappedPoint[] points = RoadsApi.snapToRoads(context, true, page).await();
        boolean passedOverlap = false;
        for (SnappedPoint point : points) {
            if (offset == 0 || point.originalIndex >= PAGINATION_OVERLAP - 1) {
                passedOverlap = true;
            }
            if (passedOverlap) {
                snappedPoints.add(point);
            }
        }

        offset = upperBound;
    }

    return snappedPoints;
}

في ما يلي البيانات الواردة أعلاه بعد تشغيل المحاذاة إلى طلبات الطرق. والخط الأحمر هو البيانات الأولية والخط الأزرق هو البيانات الأولية.

الاستخدام الفعّال للحصة

تتضمن الاستجابة لطلب المحاذاة إلى الطرق قائمة بأرقام تعريف الأماكن التي يتم ربطها بالنقاط التي قدمتها، ومن المحتمل أن تتضمن نقاطًا إضافية إذا ضبطت interpolate=true.

للاستفادة بشكلٍ فعّال من الحصة المسموح بها لطلب حدود السرعة، يجب عدم إجراء طلب بحث إلا عن معرّفات الأماكن الفريدة في طلبك. يستخدم هذا المثال عميل Java لخدمات "خرائط Google" للاستعلام عن حدود السرعة من قائمة أرقام تعريف الأماكن.

/**
 * Retrieves speed limits for the previously-snapped points. This method is efficient in terms
 * of quota usage as it will only query for unique places.
 *
 * Note: Speed limit data is only available for requests using an API key enabled for a
 * Google Maps APIs Premium Plan license.
 */
private Map<String, SpeedLimit> getSpeedLimits(GeoApiContext context, List<SnappedPoint> points)
        throws Exception {
    Map<String, SpeedLimit> placeSpeeds = new HashMap<>();

    // Pro tip: Save on quota by filtering to unique place IDs.
    for (SnappedPoint point : points) {
        placeSpeeds.put(point.placeId, null);
    }

    String[] uniquePlaceIds =
            placeSpeeds.keySet().toArray(new String[placeSpeeds.keySet().size()]);

    // Loop through the places, one page (API request) at a time.
    for (int i = 0; i < uniquePlaceIds.length; i += PAGE_SIZE_LIMIT) {
        String[] page = Arrays.copyOfRange(uniquePlaceIds, i,
                Math.min(i + PAGE_SIZE_LIMIT, uniquePlaceIds.length));

        // Execute!
        SpeedLimit[] placeLimits = RoadsApi.speedLimits(context, page).await();
        for (SpeedLimit sl : placeLimits) {
            placeSpeeds.put(sl.placeId, sl);
        }
    }

    return placeSpeeds;
}

في ما يلي البيانات المذكورة أعلاه مع حدود السرعة التي تم وضع علامة عليها لكل معرّف مكان فريد.

التفاعل مع واجهات برمجة التطبيقات الأخرى

ومن فوائد عرض أرقام تعريف الأماكن في ردود المحاذاة على الطرق أنه يمكنك استخدام رقم تعريف المكان في العديد من واجهات برمجة التطبيقات في "منصة خرائط Google". يستخدم هذا المثال برنامج Java متعلّق بخدمة "خرائط Google" لترميز مكان تمّ عرضه في نبذة عن طلب الطريق أعلاه.

/**
 * Geocodes a snapped point using the place ID.
 */
private GeocodingResult geocodeSnappedPoint(GeoApiContext context, SnappedPoint point) throws Exception {
    GeocodingResult[] results = GeocodingApi.newRequest(context)
            .place(point.placeId)
            .await();

    if (results.length > 0) {
        return results[0];
    }
    return null;
}

تمت إضافة تعليق توضيحي إلى علامة حد السرعة باستخدام عنوان واجهة برمجة التطبيقات لترميز المواقع الجغرافية.

نموذج التعليمات البرمجية

الاعتبارات

يتوفّر الرمز الذي يتوافق مع هذه المقالة كتطبيق واحد على Android لأغراض توضيحية. من الناحية العملية، يجب عدم توزيع مفاتيح واجهة برمجة التطبيقات من جهة الخادم في تطبيق Android لأنه لا يمكن تأمين مفتاحك من الوصول غير المصرح به من جهة خارجية. وبدلاً من ذلك، يجب أن يتم نشر الرمز المواجه لواجهة برمجة التطبيقات كخادم وكيل من جهة الخادم وأن تطلب من تطبيق Android إرسال الطلبات عبر الخادم الوكيل مع ضمان أن الطلبات مسموح بها.

تنزيل

نزِّل الرمز من GitHub.