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

الحصول على البيانات

هناك العديد من الطرق للحصول على بيانات الموقع الجغرافي التي تم جمعها. في ما يلي وصفان لطريقتَي الحصول على البيانات لاستخدامها مع ميزة الانطباق على الطرق في 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 الأوّلية التي تم تحميلها على خريطة.

بيانات GPX الأولية على خريطة

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

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

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

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

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

يستخدم هذا المثال Java Client لخدمات "خرائط 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 Client لخدمات "خرائط 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 Client لخدمات "خرائط 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;
}

في ما يلي علامة حدّ السرعة التي تمّت إضافة تعليق توضيحي لها بالعنوان من Geocoding API.

عنوان مُشفَّر جغرافيًا معروض على علامة

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

الاعتبارات

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

تنزيل

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