Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 168 lines (109 sloc) 4.428 kb
152063a Updates README to use markdown
Jeroen Jacobs authored
1 # GeoIp
2
3 Retreive the geolocation of an IP address based on the [ipinfodb.com](http://ipinfodb.com/) webservice.
4
5 As of 8th November 2010, the service is asking that all users [register](http://ipinfodb.com/register.php) for an API key.
6
7 Consider making a donation to [ipinfodb.com](http://ipinfodb.com/) at [http://ipinfodb.com/donate.php](http://ipinfodb.com/donate.php).
8
9 ## Usage
10
11 ### Set API key
891b621 Upgrades to code to v3 of the API. Refactors a big part of the code
Jeroen Jacobs authored
12 GeoIp.api_key = 'YOUR_API_KEY'
152063a Updates README to use markdown
Jeroen Jacobs authored
13
14 This must be done before making the geolocation call.
15
16 ### Retrieve geolocation
17 GeoIp.geolocation(ip_address)
18
19 ### Example
20
21 # 209.85.227.104 = google.be (US)
22 GeoIp.geolocation('209.85.227.104')
23
24 returns:
25
26 {
891b621 Upgrades to code to v3 of the API. Refactors a big part of the code
Jeroen Jacobs authored
27 :status_code => "OK",
28 :status_message => "",
29 :ip => "209.85.227.104"
30 :country_code => "US",
31 :country_name => "UNITED STATES",
32 :region_name => "CALIFORNIA",
33 :city => "MONTEREY PARK",
34 :zip_code => "91754",
35 :latitude => "34.0505",
36 :longitude => "-118.13"
152063a Updates README to use markdown
Jeroen Jacobs authored
37 }
38
39 ### Country only
40
41 There is an option to only retreive the country information and thus excluding the city details. This results in a faster response from the service since less queries need to be done.
42
891b621 Upgrades to code to v3 of the API. Refactors a big part of the code
Jeroen Jacobs authored
43 GeoIp.geolocation('209.85.227.104', :precision => :country)
152063a Updates README to use markdown
Jeroen Jacobs authored
44
45 returns:
46
47 {
891b621 Upgrades to code to v3 of the API. Refactors a big part of the code
Jeroen Jacobs authored
48 :status_code => "OK",
49 :status_message => "",
50 :ip => "209.85.227.104"
51 :country_code => "US",
52 :country_name => "UNITED STATES"
152063a Updates README to use markdown
Jeroen Jacobs authored
53 }
54
55 ### Timezone information
56
57 There is an option now to retrieve optional timezone information too:
58
38d99ca Adds private ip lookup to README (by @Rylon)
Jeroen Jacobs authored
59 GeoIp.geolocation('209.85.227.104', :timezone => true)
152063a Updates README to use markdown
Jeroen Jacobs authored
60
61 returns:
62
63 {
891b621 Upgrades to code to v3 of the API. Refactors a big part of the code
Jeroen Jacobs authored
64 :status_code => "OK",
65 :status_message => "",
66 :ip => "209.85.227.104"
67 :country_code => "US",
68 :country_name => "UNITED STATES",
69 :region_name => "CALIFORNIA",
70 :city => "MONTEREY PARK",
71 :zip_code => "91754",
72 :latitude => "34.0505",
73 :longitude => "-118.13"
74 :timezone => "-08:00"
152063a Updates README to use markdown
Jeroen Jacobs authored
75 }
76
77 Obviously it is not possible to have the country precision enabled while retrieving the timezone information.
78
38d99ca Adds private ip lookup to README (by @Rylon)
Jeroen Jacobs authored
79 ### Reserved / Private / Local IPs
80
81 Passing reserved, private or local IPs, such as `127.0.0.1` will return `-` for all location data, for example:
82
03a5476 @jeroenj Fixes typo in README
authored
83 GeoIp.geolocation('127.0.0.1')
38d99ca Adds private ip lookup to README (by @Rylon)
Jeroen Jacobs authored
84
85 returns:
86
87 {
88 :status_code => "OK",
89 :status_message => "",
90 :ip => "127.0.0.1",
91 :country_code => "-",
92 :country_name => "-",
93 :region_name => "-",
94 :city => "-",
95 :zip_code => "-",
96 :latitude => "0",
97 :longitude => "0"
98 }
99
7210063 Adds timeout information to readme
Jeroen Jacobs authored
100 ### Timeout
101
102 It is possible to set a timeout for all requests. By default it is one second, but you can easily set a different value. Just like you would set the api_key you can set the timeout:
103
104 GeoIp.timeout = 5 # In order to set it to five seconds
105
152063a Updates README to use markdown
Jeroen Jacobs authored
106 ## Getting it
107
108 GeoIp can be installed as a Ruby Gem:
109
110 gem install geo_ip
111
c018b49 Updates README with more detailed instructions for Rails
Jeroen Jacobs authored
112 ### Rails
152063a Updates README to use markdown
Jeroen Jacobs authored
113
3a1495e @jeroenj Update README.md
authored
114 #### Bundler enabled (Rails 3.x and 2.3.x)
c018b49 Updates README with more detailed instructions for Rails
Jeroen Jacobs authored
115
116 In your Gemfile:
117
3a1495e @jeroenj Update README.md
authored
118 gem 'geo_ip'
c018b49 Updates README with more detailed instructions for Rails
Jeroen Jacobs authored
119
120 Then create an initializer `config/initializers/geo_ip` (or name it whatever you want):
121
891b621 Upgrades to code to v3 of the API. Refactors a big part of the code
Jeroen Jacobs authored
122 GeoIp.api_key = 'YOUR_API_KEY'
c018b49 Updates README with more detailed instructions for Rails
Jeroen Jacobs authored
123
124 #### Pre-bundler (Rails 2.3.x or older)
125
126 In your `config/environment.rb`:
127
3a1495e @jeroenj Update README.md
authored
128 config.gem 'geo_ip'
c018b49 Updates README with more detailed instructions for Rails
Jeroen Jacobs authored
129
130 Then create an initializer `config/initializers/geo_ip` (or name it whatever you want):
131
891b621 Upgrades to code to v3 of the API. Refactors a big part of the code
Jeroen Jacobs authored
132 GeoIp.api_key = 'YOUR_API_KEY'
152063a Updates README to use markdown
Jeroen Jacobs authored
133
134 ## Testing
135
136 Set up your API key first for the test suite by creating a spec/api.yml file. Follow the example in spec/api.yml.example. Then run the tests with:
137
138 ruby spec/geo_ip_spec.rb
139
140 If you get a LoadError, you should run the tests with:
141
142 ruby -rubygems spec/geo_ip_spec.rb
143
144 ## Contributors
145
146 * [seanconaty](https://github.com/seanconaty)
147 * [luigi](https://github.com/luigi)
148 * [idris](https://github.com/idris)
533731f Adds @Rylon to the contributors list
Jeroen Jacobs authored
149 * [Rylon](https://github.com/Rylon)
5c3f0b9 @jeroenj Updates Changes and contributors for 0.5.0
authored
150 * [harleyttd](https://github.com/harleyttd)
152063a Updates README to use markdown
Jeroen Jacobs authored
151
5d066f4 Updates Bugs in README
Jeroen Jacobs authored
152 ## Bugs
153
154 Please report them on the [Github issue tracker](https://github.com/jeroenj/geo_ip/issues)
155 for this project.
156
157 If you have a bug to report, please include the following information:
158
3670e3b @jeroenj Update README.md
authored
159 * Version information for geo_ip, ruby and/or rails.
5d066f4 Updates Bugs in README
Jeroen Jacobs authored
160 * Stack trace and error message.
161
162 You may also fork this project on Github and create a pull request.
163 Do not forget to include tests.
152063a Updates README to use markdown
Jeroen Jacobs authored
164
165 ## Copyright
166
3670e3b @jeroenj Update README.md
authored
167 Copyright (c) 2010-2013 Jeroen Jacobs. See LICENSE for details.
Something went wrong with that request. Please try again.