README.md 2.95 KB
Newer Older
1
Geoclue: The Geoinformation Service
Zeeshan Ali Khan's avatar
Zeeshan Ali Khan committed
2
3
===================================

4
5
Geoclue is a D-Bus geoinformation service. The goal of the Geoclue project
is to make creating location-aware applications as simple as possible.
Zeeshan Ali Khan's avatar
Zeeshan Ali Khan committed
6

7
Geoclue is Free Software, licensed under GNU GPLv2+.
8

9
Geoclue comprises the following functionalities :
10
11
- WiFi-based geolocation (accuracy: in meters)
- GPS(A) receivers (accuracy: in centimeters)
12
- GPS of other devices on the local network, e.g smartphones (accuracy:
13
14
15
  in centimeters)
- 3G modems (accuracy: in kilometers, unless modem has GPS)
- GeoIP (accuracy: city-level)
16
- Static location source (reads location from a system-wide file)
17

18
19
WiFi-based geolocation makes use of 
[Mozilla Location Service](https://wiki.mozilla.org/CloudServices/Location). 
Iqbal Inzamam's avatar
Iqbal Inzamam committed
20

21
22
23
24
25
26
27
28
29
30
31
32
33
34
If geoclue is unable to find you, you can easily fix that by installing 
and running a 
[simple app](https://wiki.mozilla.org/CloudServices/Location#Contributing) on 
your phone. For using phone GPS, you'll need to install the latest version of 
[GeoclueShare app](https://github.com/ankitstarski/GeoclueShare/releases)
on your phone (currently, this is supported only on Android devices).

Geoclue was also used for (reverse-)geocoding but that functionality has 
been dropped in favour of the 
[geocode-glib library](http://ftp.gnome.org/pub/GNOME/sources/geocode-glib/).

# History
Geoclue was started during the GNOME Summit 2006 in Boston. At least 
Keith Preston and Tuomas Kuosmanen can be blamed. There was a total rewrite 
35
after version 0.9.
36
37
38
39
40
41
42

There was yet another rewrite that we call geoclue2. The first version to 
introduce the re-write was version 1.99.

# Communication and Contribution

- Discussions take place on the 
43
[GNOME Discourse](https://discourse.gnome.org/c/platform).
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
- The IRC chat for geoclue is on __#gnome-maps__ at irc.gimp.org .
- Issues are tracked on 
[Gitlab](https://gitlab.freedesktop.org/geoclue/geoclue/issues).

# Get Source Code
The source code is available as a tar-ball and in a Git repository.

For latest release tarballs, use the `Download` option of Gitlab on the 
[tag of your choice](https://gitlab.freedesktop.org/geoclue/geoclue/tags/).

Older (than 2.4.13) releases are available 
[here](http://www.freedesktop.org/software/geoclue/releases/2.4/).

Git repository for Geoclue: https://gitlab.freedesktop.org/geoclue/geoclue
  
Iqbal Inzamam's avatar
Iqbal Inzamam committed
59
60
# Building Geoclue

61
62
The guidelines for building geoclue have been documented 
[here](https://gitlab.freedesktop.org/geoclue/geoclue/blob/master/HACKING.md). 
Iqbal Inzamam's avatar
Iqbal Inzamam committed
63

64
65
66
67
68
69
70
71
72
# Using Geoclue in an application
 
- __D-Bus API__: The documentation for using geoclue with D-Bus API is 
[here](http://www.freedesktop.org/software/geoclue/docs/).
- __Libgeoclue API documentation__:  The documentation is available 
[here](https://www.freedesktop.org/software/geoclue/docs/libgeoclue/).
- __C user application__: 
[Here](https://gitlab.freedesktop.org/geoclue/geoclue/blob/master/demo/where-am-i.c)
is an example showing a C application that uses 
73
geoclue to locate its user.