simplegeoloc/README.md

SimpleGeoLoc simple items with geolocation, near items function

# SimpleGeoLoc

Simple geolocation functions. Add items with geolocation information, then find items near a point/distance.

## Usage

## Installation

Via npm on Node:

```
npm install simplegeoloc
```

## Usage

Reference in your program:

```js
var sgl = require('simplegeoloc');
```

Create an item store:
```js
var store = sgl.createStore();
```

Add items to store:
```js
store.add(latitude, longitude, item);
```

Examples:
```js
store.add(-34.47706, -58.50177, { city: 'Acassuso', geoname_id: 3436508 });
store.add(-34.74471, -58.40410, { city: 'Banfield', geoname_id: 3436152 });
```

Items near to a point:
```js
var items = store.near(-34.47706, -58.50177);
```
The returned value is a JavaScript array. Each element has properties `latitude`, `longitude`, `item` (with the original associated item data).

## Versions

- 0.0.1 Published, naive near implementation, visiting all items, using haversine function for distances

## To Do

- First sample
- Improve near implementation, partitioning items using an internal grid, then, visiting all the items in near cells instead of all the item list
- New input format for position (latitude, longitude as strings; degree, minutes, seconds format `12° 20.736′ N, 98° 45.924′ W`, etc)

## License

MIT

## References

- [Geotagging](http://en.wikipedia.org/wiki/Geotagging) with lat/long formats
- [Geographic coordinate system](http://en.wikipedia.org/wiki/Geographic_coordinate_system)
- [How to convert address (as text) to gps coordinates?](http://stackoverflow.com/questions/6996577/how-to-convert-address-as-text-to-gps-coordinates)
- [The Google Geocoding API](https://developers.google.com/maps/documentation/geocoding/?csw=1)
- [Free Geocoding Utilities at GPSVisualizer.com](http://www.gpsvisualizer.com/geocoding.html)
- [Calculate distance between 2 GPS coordinates](http://stackoverflow.com/questions/365826/calculate-distance-between-2-gps-coordinates)
- [Calculate distance, bearing and more between Latitude/Longitude points](http://www.movable-type.co.uk/scripts/latlong.html) See accuracy note, for error due to use medium earth radius
- [What is the distance between a degree of latitude and longitude?](http://geography.about.com/library/faq/blqzdistancedegree.htm)
- [Earth Radius](http://en.wikipedia.org/wiki/Earth_radius)

## Contribution

Feel free to [file issues](https://github.com/ajlopez/SimpleGeoLoc) and submit
[pull requests](https://github.com/ajlopez/SimpleGeoLoc/pulls) — contributions are
welcome<

If you submit a pull request, please be sure to add or update corresponding
test cases, and ensure that `npm test` continues to pass.