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

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

هناك العديد من الطرق للحصول على بيانات الموقع الجغرافي التي تم جمعها. هنا نصف اثنين أساليب الحصول على البيانات لاستخدامها مع ميزة محاذاة إلى الطرق في 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 لخدمات "خرائط 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 Maps Platform API. يستخدم هذا المثال برنامج 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;
}

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

العنوان المرمَّز جغرافيًا يظهر على محدّد موقع

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

الاعتبارات

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

تنزيل

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