Skip to content

Commit e41aadf

Browse files
silvanocerzasilvanocerza
authored
Merge pull request #20 from ipinfo/silvano/eng-612-update-readme-documentation-for-ipinfonode-express
Add documentation for Core and Plus bundles and resproxy
2 parents b0af52f + 388a19f commit e41aadf

File tree

1 file changed

+182
-72
lines changed

1 file changed

+182
-72
lines changed

‎README.md‎

Lines changed: 182 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,34 @@
11
# [<img src="https://ipinfo.io/static/ipinfo-small.svg" alt="IPinfo" width="24"/>](https://ipinfo.io/) IPinfo Node.js Express Client Library
22

3-
This is the official Node.js Express client library for the [IPinfo.io](https://ipinfo.io) IP address API, allowing you to look up your own IP address, or get any of the following details for an IP:
4-
5-
- [IP to geolocation](https://ipinfo.io/ip-geolocation-api) (city, region, country, postal code, latitude, and longitude)
6-
- [IP to ASN](https://ipinfo.io/asn-api) (ISP or network operator, associated domain name, and type, such as business, hosting, or company)
7-
- [IP to Company](https://ipinfo.io/ip-company-api) (the name and domain of the business that uses the IP address)
8-
- [IP to Carrier](https://ipinfo.io/ip-carrier-api) (the name of the mobile carrier and MNC and MCC for that carrier if the IP is used exclusively for mobile traffic)
9-
10-
Check all the data we have for your IP address [here](https://ipinfo.io/what-is-my-ip).
3+
This is the official Node.js Express client library for the
4+
[IPinfo.io](https://ipinfo.io) IP address API, allowing you to look up your own
5+
IP address, or get any of the following details for an IP:
6+
7+
- [IP to geolocation](https://ipinfo.io/ip-geolocation-api) (city, region,
8+
country, postal code, latitude, and longitude)
9+
- [IP to ASN](https://ipinfo.io/asn-api) (ISP or network operator, associated
10+
domain name, and type, such as business, hosting, or company)
11+
- [IP to Company](https://ipinfo.io/ip-company-api) (the name and domain of
12+
the business that uses the IP address)
13+
- [IP to Carrier](https://ipinfo.io/ip-carrier-api) (the name of the mobile
14+
carrier and MNC and MCC for that carrier if the IP is used exclusively for
15+
mobile traffic)
16+
17+
Check all the data we have for your IP address
18+
[here](https://ipinfo.io/what-is-my-ip).
1119

1220
### Getting Started
1321

14-
You'll need an IPinfo API access token, which you can get by signing up for a free account at [https://ipinfo.io/signup](https://ipinfo.io/signup).
22+
You'll need an IPinfo API access token, which you can get by signing up for a
23+
free account at [https://ipinfo.io/signup](https://ipinfo.io/signup).
1524

16-
The free plan is limited to 50,000 requests per month, and doesn't include some of the data fields such as IP type and company data. To enable all the data fields and additional request volumes see [https://ipinfo.io/pricing](https://ipinfo.io/pricing)
25+
The free plan is limited to 50,000 requests per month, and doesn't include some
26+
of the data fields such as IP type and company data. To enable all the data
27+
fields and additional request volumes see
28+
[https://ipinfo.io/pricing](https://ipinfo.io/pricing)
1729

18-
The library also supports the Lite API, see the [Lite API section](#lite-api) for more info.
30+
The library also supports the Lite API, see the [Lite API section](#lite-api)
31+
for more info.
1932

2033
### Installation
2134

@@ -59,102 +72,127 @@ ipinfo({
5972
The following is a full example of using the middleware function.
6073

6174
```javascript
62-
const express = require('express')
63-
const ipinfo = require('ipinfo-express')
64-
65-
const app = express()
66-
app.use(ipinfo({
67-
token: "token",
68-
cache: null,
69-
timeout: 5000,
70-
ipSelector: null
71-
}))
72-
73-
app.get('/', function (req, res) {
74-
res.send(req.ipinfo)
75-
})
75+
const express = require("express");
76+
const ipinfo = require("ipinfo-express");
77+
78+
const app = express();
79+
app.use(
80+
ipinfo({
81+
token: "token",
82+
cache: null,
83+
timeout: 5000,
84+
ipSelector: null
85+
})
86+
);
87+
88+
app.get("/", function (req, res) {
89+
res.send(req.ipinfo);
90+
});
7691

7792
app.listen(3000, () => {
78-
console.log(`Server is running`)
79-
})
93+
console.log(`Server is running`);
94+
});
8095
```
8196

8297
### IP Selection Mechanism
8398

8499
By default, the IP from the incoming request object is used.
85100

86-
Since the desired IP by your system may be in other locations, the IP selection mechanism is configurable and some alternative built-in options are available.
101+
Since the desired IP by your system may be in other locations, the IP selection
102+
mechanism is configurable and some alternative built-in options are available.
87103

88104
#### Using built-in IP selectors
89105

90-
- Default IP Selector
91-
- Originating IP Selector
106+
- Default IP Selector
107+
- Originating IP Selector
92108

93109
##### Default IP selector
94110

95-
A [defaultIPSelector](https://github.com/ipinfo/node-express/blob/master/src/ip-selector/default-ip-selector.js) function is used by default if no IP selection method is provided. It returns the default IP from the incoming request object of Express.
111+
A
112+
[defaultIPSelector](https://github.com/ipinfo/node-express/blob/master/src/ip-selector/default-ip-selector.js)
113+
function is used by default if no IP selection method is provided. It returns
114+
the default IP from the incoming request object of Express.
96115

97-
This selector can be set explicitly by setting the `ipSelector` while setting the middleware function.
116+
This selector can be set explicitly by setting the `ipSelector` while setting
117+
the middleware function.
98118

99119
```javascript
100-
const ipinfo = require('ipinfo-express')
101-
const { defaultIPSelector } = require('ipinfo-express')
102-
103-
const app = express()
104-
app.use(ipinfo({
105-
token: "token",
106-
cache: null,
107-
timeout: 5000,
108-
ipSelector: defaultIPSelector
109-
}))
120+
const ipinfo = require("ipinfo-express");
121+
const { defaultIPSelector } = require("ipinfo-express");
122+
123+
const app = express();
124+
app.use(
125+
ipinfo({
126+
token: "token",
127+
cache: null,
128+
timeout: 5000,
129+
ipSelector: defaultIPSelector
130+
})
131+
);
110132
```
111133

112134
##### Originating IP selector
113135

114-
A [originatingIPSelector](https://github.com/ipinfo/node-express/blob/master/src/ip-selector/originating-ip-selector.js) selects an IP address by trying to extract it from the `X-Forwarded-For` header. This is not always the most reliable unless your proxy setup allows you to trust it. It will default to the source IP on the request if the header doesn't exist.
136+
A
137+
[originatingIPSelector](https://github.com/ipinfo/node-express/blob/master/src/ip-selector/originating-ip-selector.js)
138+
selects an IP address by trying to extract it from the `X-Forwarded-For`
139+
header. This is not always the most reliable unless your proxy setup allows you
140+
to trust it. It will default to the source IP on the request if the header
141+
doesn't exist.
115142

116-
This selector can be set by setting the `ipSelector` while setting the middleware function.
143+
This selector can be set by setting the `ipSelector` while setting the
144+
middleware function.
117145

118146
```javascript
119-
const ipinfo = require('ipinfo-express')
120-
const { originatingIPSelector } = require('ipinfo-express')
121-
122-
const app = express()
123-
app.use(ipinfo({
124-
token: "token",
125-
cache: null,
126-
timeout: 5000,
127-
ipSelector: originatingIPSelector
128-
}))
147+
const ipinfo = require("ipinfo-express");
148+
const { originatingIPSelector } = require("ipinfo-express");
149+
150+
const app = express();
151+
app.use(
152+
ipinfo({
153+
token: "token",
154+
cache: null,
155+
timeout: 5000,
156+
ipSelector: originatingIPSelector
157+
})
158+
);
129159
```
130160

131161
#### Using a custom IP selector
132162

133-
In case a custom IP selector is required, you may set your custom function to `ipSelector`. Your custom function should take [req](https://expressjs.com/en/api.html#req) as an argument and return an IP in `string` format.
163+
In case a custom IP selector is required, you may set your custom function to
164+
`ipSelector`. Your custom function should take
165+
[req](https://expressjs.com/en/api.html#req) as an argument and return an IP in
166+
`string` format.
134167

135168
For example:
136169

137170
```javascript
138-
const ipinfo = require('ipinfo-express')
139-
140-
const app = express()
141-
app.use(ipinfo({
142-
token: "token",
143-
cache: null,
144-
timeout: 5000,
145-
ipSelector: (req) => {
146-
ip = ""
147-
// update ip according to your logic and return the selected IP
148-
return ip
149-
}
150-
}))
171+
const ipinfo = require("ipinfo-express");
172+
173+
const app = express();
174+
app.use(
175+
ipinfo({
176+
token: "token",
177+
cache: null,
178+
timeout: 5000,
179+
ipSelector: (req) => {
180+
ip = "";
181+
// update ip according to your logic and return the selected IP
182+
return ip;
183+
}
184+
})
185+
);
151186
```
152187

153188
### Lite API
154189

155-
The library gives the possibility to use the [Lite API](https://ipinfo.io/developers/lite-api) too, authentication with your token is still required.
190+
The library gives the possibility to use the
191+
[Lite API](https://ipinfo.io/developers/lite-api) too, authentication with your
192+
token is still required.
156193

157-
The IP details returned are slightly different from the Core API middleware, though the arguments are identical.
194+
The IP details returned are slightly different from the Core API middleware,
195+
though the arguments are identical.
158196

159197
```typescript
160198
const { ipinfoLite } = require('ipinfo-express')
@@ -167,13 +205,85 @@ ipinfoLite({
167205
});
168206
```
169207

208+
### Core API
209+
210+
The library also supports the
211+
[Core API](https://ipinfo.io/developers/data-types#core-data), which provides
212+
city-level geolocation with nested geo and AS objects. Authentication with your
213+
token is required.
214+
215+
```typescript
216+
const { ipinfoCore } = require('ipinfo-express')
217+
218+
ipinfoCore({
219+
token: "<token>",
220+
cache: <cache_class>,
221+
timeout: 5000,
222+
ipSelector: null
223+
});
224+
```
225+
226+
### Plus API
227+
228+
The library also supports the
229+
[Plus API](https://ipinfo.io/developers/data-types#plus-data), which provides
230+
enhanced data including mobile carrier info and privacy detection.
231+
Authentication with your token is required.
232+
233+
```typescript
234+
const { ipinfoPlus } = require('ipinfo-express')
235+
236+
ipinfoPlus({
237+
token: "<token>",
238+
cache: <cache_class>,
239+
timeout: 5000,
240+
ipSelector: null
241+
});
242+
```
243+
244+
### Residential Proxy API
245+
246+
The library also supports the
247+
[Residential Proxy API](https://ipinfo.io/developers/residential-proxy-api),
248+
which allows you to check if an IP address is a residential proxy.
249+
Authentication with your token is required.
250+
251+
```typescript
252+
const { ipinfoResproxy } = require('ipinfo-express')
253+
254+
const app = express()
255+
app.use(ipinfoResproxy({
256+
token: "<token>",
257+
cache: <cache_class>,
258+
timeout: 5000,
259+
ipSelector: null
260+
}))
261+
262+
app.get('/', function (req, res) {
263+
// Access residential proxy details
264+
if (req.ipinfo_resproxy) {
265+
console.log(req.ipinfo_resproxy.ip); // 175.107.211.204
266+
console.log(req.ipinfo_resproxy.lastSeen); // 2025-01-20
267+
console.log(req.ipinfo_resproxy.percentDaysSeen); // 0.85
268+
console.log(req.ipinfo_resproxy.service); // Bright Data
269+
}
270+
res.send(req.ipinfo_resproxy)
271+
})
272+
```
170273

171274
### Other Libraries
172275

173-
There are official IPinfo client libraries available for many languages including PHP, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. There are also many third-party libraries and integrations available for our API.
276+
There are official IPinfo client libraries available for many languages
277+
including PHP, Go, Java, Ruby, and many popular frameworks such as Django,
278+
Rails, and Laravel. There are also many third-party libraries and integrations
279+
available for our API.
174280

175281
### About IPinfo
176282

177-
Founded in 2013, IPinfo prides itself on being the most reliable, accurate, and in-depth source of IP address data available anywhere. We process terabytes of data to produce our custom IP geolocation, company, carrier, VPN detection, hosted domains, and IP type data sets. Our API handles over 20 billion requests a month for 100,000 businesses and developers.
283+
Founded in 2013, IPinfo prides itself on being the most reliable, accurate, and
284+
in-depth source of IP address data available anywhere. We process terabytes of
285+
data to produce our custom IP geolocation, company, carrier, VPN detection,
286+
hosted domains, and IP type data sets. Our API handles over 20 billion requests
287+
a month for 100,000 businesses and developers.
178288

179289
[![image](https://avatars3.githubusercontent.com/u/15721521?s=128&u=7bb7dde5c4991335fb234e68a30971944abc6bf3&v=4)](https://ipinfo.io/)

0 commit comments

Comments
 (0)