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

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

هناك العديد من الطرق للحصول على بيانات الموقع الجغرافي التي تم جمعها. نوضّح هنا أسلوبَين للحصول على البيانات من أجل استخدامهما مع ميزة المحاذاة إلى الطرق في 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 Client for Google Maps Services لإرسال الطلبات المقسّمة إلى صفحات ثم إعادة ضم البيانات، بما في ذلك النقاط المضافة، إلى القائمة المعروضة.

/**
 * 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 for Google Maps Services للاستعلام عن حدود السرعة من قائمة أرقام تعريف الأماكن.

/**
 * 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 for Google Maps Services لترميز مكان تمت إعادته من الانطباق أعلاه إلى طلب الطريق.

/**
 * 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.