مفاهیم پیشرفته

جذب کاربر

روش‌های زیادی برای به‌دست آوردن داده‌های مکان جمع‌آوری‌شده وجود دارد. در اینجا دو روش برای به‌دست آوردن داده‌هایی که با ویژگی چسبیدن به جاده‌ها در Roads API استفاده می‌شود توضیح می‌دهیم.

GPX

GPX قالبی باز مبتنی بر XML برای هم‌رسانی مسیرها، ردپاها، و نقطه‌مسیرهای ثبت‌شده توسط دستگاه‌های GPS است. این مثال از تجزیه‌کننده XmlPull استفاده می‌کند، یک تجزیه‌کننده XML سبک‌وزن که برای هر دو محیط سرور جاوا و تلفن همراه دردسترس است.

/**
 * 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 نگاهی بیندازید.

پردازش مسیرهای طولانی

ازآنجایی‌که ویژگی چسبیدن به جاده‌ها مکان را براساس مسیر کامل استنباط می‌کند، نه براساس نقاط جداگانه، هنگام پردازش مسیرهای طولانی (یعنی مسیرهای فراتر از حد ۱۰۰ نقطه در هر درخواست) باید دقت کنید.

برای اینکه درخواست‌های جداگانه را به‌عنوان یک مسیر طولانی درنظر بگیرید، باید کمی هم‌پوشانی داشته باشند، به‌طوری‌که نقاط پایانی درخواست قبلی به‌عنوان نقاط ابتدایی درخواست بعدی درنظر گرفته شوند. تعداد نقطه‌هایی که باید اضافه شود به دقت داده‌های شما بستگی دارد. برای درخواست‌های با دقت پایین باید نقاط بیشتری اضافه کنید.

این مثال از 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 Maps» استفاده کنید. این مثال از 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;
}

در اینجا، نشانگر محدودیت سرعت با نشانی برگرفته از Geocoding API حاشیه‌نویسی شده است.

نشانی زمین‌کدیابی‌شده در نشانگر نشان داده می‌شود

کدگذاری نمونه

ملاحظات

کد پشتیبانی این سند به‌عنوان یک برنامه Android برای اهداف توضیحی دردسترس است. در عمل نباید کلیدهای API سمت سرور خود را در برنامه Android توزیع کنید، زیرا کلید شما نمی‌تواند دربرابر دسترسی غیرمجاز طرف سوم ایمن شود. درعوض، برای ایمن کردن کلیدهایتان باید کد مواجه با API را به‌عنوان پراکسی سمت سرور پیاده‌سازی کنید و برنامه Android خود را طوری تنظیم کنید که درخواست‌ها را بااستفاده از پراکسی ارسال کند تا مطمئن شوید درخواست‌ها مجاز هستند.

بارگیری

کد را از GitHub بارگیری کنید.