From 5fcb8e6ccac224e6d1028634fb77346bc41d1ca2 Mon Sep 17 00:00:00 2001
From: Jeff Poulton <poulton@gmail.com>
Date: Fri, 1 Jul 2011 14:34:22 -0600
Subject: [PATCH] Add example on retrieving coordinates from mongodb model.

---
 README.rdoc | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/README.rdoc b/README.rdoc
index 13015c07..60536dfa 100644
--- a/README.rdoc
+++ b/README.rdoc
@@ -77,6 +77,8 @@ Reverse geocoding is similar:
   reverse_geocoded_by :coordinates
   after_validation :reverse_geocode  # auto-fetch address
 
+<i>Note:</i> Be sure to read <i>Latitude/Longitude Order</i> in the <i>Notes on MongoDB</i> section below for an explanation on how to properly retrieve latitude/longitude coordinates from your model.
+
 === MongoMapper
 
 MongoMapper is very similar to Mongoid, just be sure to include <tt>Geocoder::Model::Mongoid</tt>.
@@ -424,6 +426,17 @@ Mongo document classes (Mongoid and MongoMapper) have a built-in +near+ scope, b
 
 Coordinates are generally printed and spoken as latitude, then logitude ([lat,lon]). Geocoder respects this convention and always expects method arguments to be given in [lat,lon] order. However, MongoDB requires that coordinates be stored in [lon,lat] order as per the GeoJSON spec (http://geojson.org/geojson-spec.html#positions), so internally they are stored "backwards." However, this does not affect order of arguments to methods when using Mongoid or MongoMapper.
 
+To access an object's coordinates in the conventional order, use the to_coordinates instance method provided by Geocoder.
+
+For example, if an object's latitude/longitude are stored in an attribute named _coordinates_,
+
+    # directly accessing the attribute will result in "backwards" coordinates
+    my_location.coordinates
+    => [-122.3951096, 37.7941013] # [lon, lat] (you don't want to pass this to Google Maps!)
+
+    # instead, use Geocoder's helper method to retrieve the coordinates in the conventional order
+    > my_location.to_coordinates
+    => [37.7941013, -122.3951096] # [lat, lon]
 
 == Distance Queries in SQLite
 
-- 
GitLab