google_maps_polyline #

Google Directions API ile iki nokta arasındaki rotayı alır ve Google kodlanmış polyline dizelerini çözer/kodlar. Saf Dart'tır: Flutter (Android, iOS, masaüstü) ve sunucu tarafında çalışır. Polyline çözme/kodlama web'de de çalışır; rota isteği için Flutter web notuna bakın.

English summary below.

Kurulum #

dependencies:
  google_maps_polyline: ^2.1.0

Rota alma #

import 'package:google_maps_polyline/google_maps_polyline.dart';

final polyline = GoogleMapsPolyline();

final result = await polyline.getRouteBetweenCoordinates(
  apiKey,
  const MyPointLatLng(41.0082, 28.9784), // İstanbul
  const MyPointLatLng(39.9334, 32.8597), // Ankara
  travelMode: MyTravelMode.driving,
  wayPoints: [
    WayPointPolyline(location: 'Bolu, Türkiye'),
    WayPointPolyline(location: '40.7,31.6', stopOver: false), // via:
  ],
  avoidTolls: true,
  detailedPolyline: true, // adım adım ayrıntılı rota
);

if (result.isSuccess) {
  // google_maps_flutter ile:
  final points = [for (final p in result.points) LatLng(p.latitude, p.longitude)];
} else {
  print('${result.status}: ${result.errorMessage}');
}

getRouteBetweenCoordinates istisna fırlatmaz. result.status Directions API'nin döndürdüğü değerdir (OK, ZERO_RESULTS, NOT_FOUND, OVER_QUERY_LIMIT, REQUEST_DENIED, INVALID_REQUEST, …); ağ hatası, zaman aşımı veya okunamayan yanıtta ResultPolyline.statusError ("error") olur. Hata mesajlarında API anahtarı maskelenir. Başlangıç veya hedef koordinatı NaN/sonsuz ise istek atılmadan hata döner.

Varsayılan olarak Google'ın sadeleştirdiği overview_polyline kullanılır; yakın zoom'da yoldan sapabilir. detailedPolyline: true verildiğinde rota, her adımın polylinesi birleştirilerek oluşturulur (daha çok nokta, yolu daha iyi izler). Yanıtta adım yoksa otomatik olarak overview_polyline'a dönülür.

İsteğe bağlı ayarlar:

GoogleMapsPolyline(
  client: myHttpClient,                 // kendi http.Client'ınız (test, proxy vb.)
  timeout: const Duration(seconds: 10), // varsayılan 15 sn
);

Polyline çözme ve kodlama #

final points = PolylineCodec.decode(r'_p~iF~ps|U_ulLnnqC_mqNvxq`@');
// [(38.5, -120.2), (40.7, -120.95), (43.252, -126.453)]

final encoded = PolylineCodec.encode(points); // '_p~iF~ps|U_ulLnnqC_mqNvxq`@'

// 6 basamak hassasiyetli dizeler (ör. OSRM polyline6):
PolylineCodec.decode(encoded6, precision: 6);

Geçersiz veya yarım kalmış dizelerde FormatException fırlatılır.

Flutter web ve CORS #

Google'ın Directions web servisi tarayıcıdan gelen isteklere CORS izni vermez. Bu yüzden Flutter web'de getRouteBetweenCoordinates her zaman ağ hatası (status == "error") döndürür. Web'de rotayı kendi sunucunuzda (ör. bu paketi kullanan bir Dart sunucusu veya Cloud Function) alın, uygulamaya kodlanmış polyline dizesini gönderin ve tarayıcıda PolylineCodec.decode ile çözün. Web'de rota çizmek için Maps JavaScript API'nin DirectionsService sınıfı da bir seçenektir.

API anahtarı güvenliği #

Directions API web servisidir; anahtarı uygulamaya gömmek, uygulamayı açan herkesin onu okuyabilmesi demektir. Anahtarı Google Cloud Console'da yalnızca Directions API ile sınırlayın ve kota koyun. Mümkünse isteği kendi sunucunuz üzerinden yapın; paket saf Dart olduğundan sunucuda da kullanılabilir.

Directions API ve Routes API #

Google, Directions API'yi Legacy (eski) olarak işaretledi ve yeni projeler için Routes API'yi öneriyor. 1 Mart 2025'ten sonra oluşturulan Google Cloud projelerinde Directions API etkinleştirilemeyebilir. Bu paket Directions API'yi kullanır; Routes API yanıtındaki polyline.encodedPolyline alanı da aynı biçimde olduğundan PolylineCodec.decode ile çözülebilir.

2.0.0'a geçiş #

• MyPointLatLng.latitude/longitude artık double? değil double (! gerekmiyor).
• Başarı kontrolü için result.status == "ok" yerine result.isSuccess kullanın (API "OK" döndürdüğünden eski karşılaştırma hiçbir zaman doğru olmuyordu).
• Tüm sınıflar package:google_maps_polyline/google_maps_polyline.dart üzerinden dışa aktarılıyor; src/... içe aktarmalarını kaldırın.
• Paket artık Flutter'a bağımlı değil.

English #

Fetches a route between two coordinates from the Google Directions API and decodes/encodes Google encoded polylines. Pure Dart — works in Flutter apps (Android, iOS, desktop) and on the server.

• GoogleMapsPolyline().getRouteBetweenCoordinates(apiKey, origin, destination, ...) returns a ResultPolyline and never throws; check result.isSuccess, result.status (the raw API status, or "error" for network, timeout and parse failures) and result.errorMessage (the API key is redacted).
• PolylineCodec.decode(encoded, precision: 5) / PolylineCodec.encode(points, precision: 5); invalid input throws FormatException.
• detailedPolyline: true builds the route from every step's polyline instead of the simplified overview_polyline, so it follows the road closely at high zoom.
• Flutter web: the Directions web service does not allow CORS, so route requests fail in the browser. Fetch the route on your own server and decode the polyline in the browser with PolylineCodec.decode.
• Pass your own http.Client and timeout to the GoogleMapsPolyline constructor if needed.
• The Directions API is a legacy Google product; new projects should consider the Routes API. Its encodedPolyline can be decoded with PolylineCodec.decode.
• Restrict your API key to the Directions API, or call it from your own backend.

See example/ for a complete Flutter app.

Lisans / License #

MIT — bkz. LICENSE.