Skip to content

Commit 8de919c

Browse files
ip2locationip2location
committed
Added readthedocs documentation.
1 parent 5855534 commit 8de919c

File tree

10 files changed

+496
-0
lines changed

10 files changed

+496
-0
lines changed

‎.readthedocs.yaml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# .readthedocs.yaml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
# Set the OS, Python version and other tools you might need
9+
build:
10+
os: ubuntu-22.04
11+
tools:
12+
python: "3.11"
13+
# You can also specify other tool versions:
14+
# nodejs: "19"
15+
# rust: "1.64"
16+
# golang: "1.19"
17+
18+
# Build documentation in the "docs/" directory with Sphinx
19+
sphinx:
20+
configuration: docs/source/conf.py
21+
22+
# Optionally build your docs in additional formats such as PDF and ePub
23+
# formats:
24+
# - pdf
25+
# - epub
26+
27+
# Optional but recommended, declare the Python requirements required
28+
# to build your documentation
29+
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
30+
python:
31+
install:
32+
- requirements: docs/requirements.txt

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/requirements.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Defining the exact version will make sure things don't break
2+
sphinx-pdj-theme==0.4.0
3+
myst-parser==2.0.0
4+
markdown-it-py==3.0.0
5+
sphinx-copybutton==0.5.2

‎docs/source/code.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# IP2Location Ruby API
2+
3+
## IP2Location Class
4+
5+
```{py:class} IP2Location()
6+
Construct the IP2Location Class.
7+
```
8+
9+
```{py:function} open(binPath)
10+
Load the IP2Location BIN database for lookup.
11+
12+
:param str binPath: (Required) The file path links to IP2Location BIN databases.
13+
```
14+
15+
```{py:function} getAll(ipAddress)
16+
Retrieve geolocation information for an IP address.
17+
18+
:param str ipAddress: (Required) The IP address (IPv4 or IPv6).
19+
:return: Returns the geolocation information in array. Refer below table for the fields avaliable in the array
20+
:rtype: array
21+
22+
**RETURN FIELDS**
23+
24+
| Field Name | Description |
25+
| ---------------- | ------------------------------------------------------------ |
26+
| countryShort | Two-character country code based on ISO 3166. |
27+
| countryLong | Country name based on ISO 3166. |
28+
| region | Region or state name. |
29+
| city | City name. |
30+
| isp | Internet Service Provider or company\'s name. |
31+
| latitude | City latitude. Defaults to capital city latitude if city is unknown. |
32+
| longitude | City longitude. Defaults to capital city longitude if city is unknown. |
33+
| domain | Internet domain name associated with IP address range. |
34+
| zipCode | ZIP code or Postal code. [172 countries supported](https://www.ip2location.com/zip-code-coverage). |
35+
| timeZone | UTC time zone (with DST supported). |
36+
| netSpeed | Internet connection type. |
37+
| iddCode | The IDD prefix to call the city from another country. |
38+
| areaCode | A varying length number assigned to geographic areas for calls between cities. [223 countries supported](https://www.ip2location.com/area-code-coverage). |
39+
| weatherStationCode | The special code to identify the nearest weather observation station. |
40+
| weatherStationName | The name of the nearest weather observation station. |
41+
| mcc | Mobile Country Codes (MCC) as defined in ITU E.212 for use in identifying mobile stations in wireless telephone networks, particularly GSM and UMTS networks. |
42+
| mnc | Mobile Network Code (MNC) is used in combination with a Mobile Country Code(MCC) to uniquely identify a mobile phone operator or carrier. |
43+
| mobileBrand | Commercial brand associated with the mobile carrier. You may click [mobile carrier coverage](https://www.ip2location.com/mobile-carrier-coverage) to view the coverage report. |
44+
| elevation | Average height of city above sea level in meters (m). |
45+
| usageType | Usage type classification of ISP or company. |
46+
| addressType | IP address types as defined in Internet Protocol version 4 (IPv4) and Internet Protocol version 6 (IPv6). |
47+
| category | The domain category based on [IAB Tech Lab Content Taxonomy](https://www.ip2location.com/free/iab-categories). |
48+
| district | District or county name. |
49+
| asn | Autonomous system number (ASN). BIN databases. |
50+
| as | Autonomous system (AS) name. |
51+
```
52+
53+
## IPTools Class
54+
55+
```{py:class} IPTools ()
56+
Initiate IPTools class.
57+
```
58+
59+
```{py:function} isIPV4(ipAddress)
60+
Verify if a string is a valid IPv4 address.
61+
62+
:param str ipAddress: (Required) IP address.
63+
:return: Return True if the IP address is a valid IPv4 address or False if it isn't a valid IPv4 address.
64+
:rtype: boolean
65+
```
66+
67+
```{py:function} isIPV6(ipAddress)
68+
Verify if a string is a valid IPv6 address
69+
70+
:param str ipAddress: (Required) IP address.
71+
:return: Return True if the IP address is a valid IPv6 address or False if it isn't a valid IPv6 address.
72+
:rtype: boolean
73+
```
74+
75+
```{py:function} ipV4ToDecimal(ipAddress)
76+
Translate IPv4 address from dotted-decimal address to decimal format.
77+
78+
:param str ipAddress: (Required) IPv4 address.
79+
:return: Return the decimal format of the IPv4 address.
80+
:rtype: int
81+
```
82+
83+
```{py:function} decimalToIPV4(ipNumber)
84+
Translate IPv4 address from decimal number to dotted-decimal address.
85+
86+
:param str ip_number: (Required) Decimal format of the IPv4 address.
87+
:return: Returns the dotted-decimal format of the IPv4 address.
88+
:rtype: string
89+
```
90+
91+
```{py:function} ipV6ToDecimal(ipAddress)
92+
Translate IPv6 address from hexadecimal address to decimal format.
93+
94+
:param str ipAddress: (Required) IPv6 address.
95+
:return: Return the decimal format of the IPv6 address.
96+
:rtype: int
97+
```
98+
99+
```{py:function} decimalToIPV6(ipNumber)
100+
Translate IPv6 address from decimal number into hexadecimal address.
101+
102+
:param str ip_number: (Required) Decimal format of the IPv6 address.
103+
:return: Returns the hexadecimal format of the IPv6 address.
104+
:rtype: string
105+
```
106+
107+
```{py:function} ipV4ToCIDR(ip_from, ip_to)
108+
Convert IPv4 range into a list of IPv4 CIDR notation.
109+
110+
:param str ip_from: (Required) The starting IPv4 address in the range.
111+
:param str ip_to: (Required) The ending IPv4 address in the range.
112+
:return: Returns the list of IPv4 CIDR notation.
113+
:rtype: array
114+
```
115+
116+
```{py:function} cidrToIPV4(cidr)
117+
Convert IPv4 CIDR notation into a list of IPv4 addresses.
118+
119+
:param str cidr: (Required) IPv4 CIDR notation.
120+
:return: Returns an list of IPv4 addresses.
121+
:rtype: array
122+
```
123+
124+
```{py:function} ipV6ToCIDR(ip_from, ip_to)
125+
Convert IPv6 range into a list of IPv6 CIDR notation.
126+
127+
:param str ip_from: (Required) The starting IPv6 address in the range.
128+
:param str ip_to: (Required) The ending IPv6 address in the range.
129+
:return: Returns the list of IPv6 CIDR notation.
130+
:rtype: array
131+
```
132+
133+
```{py:function} cidrToIPV6(cidr)
134+
Convert IPv6 CIDR notation into a list of IPv6 addresses.
135+
136+
:param str cidr: (Required) IPv6 CIDR notation.
137+
:return: Returns an list of IPv6 addresses.
138+
:rtype: array
139+
```
140+
141+
142+
```{py:function} compressIPV6(ipAddress)
143+
Compress a IPv6 to shorten the length.
144+
145+
:param str ipAddress: (Required) IPv6 address.
146+
:return: Returns the compressed version of IPv6 address.
147+
:rtype: str
148+
```
149+
150+
```{py:function} expandIPV6(ipAddress)
151+
Expand a shorten IPv6 to full length.
152+
153+
:param str ipAddress: (Required) IPv6 address.
154+
:return: Returns the extended version of IPv6 address.
155+
:rtype: str
156+
```
157+
158+
## Country Class
159+
160+
```{py:class} Country(csvFilePath)
161+
Initiate Ip2locationCountry class and load the IP2Location Country Information CSV file. This database is free for download at <https://www.ip2location.com/free/country-information>.
162+
163+
:param str csvFilePath: (Required) The file path links to IP2Location Country Information CSV file.
164+
```
165+
166+
```{py:function} getCountryInfo(countryCode)
167+
Provide a ISO 3166 country code to get the country information in array. Will return a full list of countries information if country code not provided.
168+
169+
:param str countryCode: (Required) The ISO 3166 country code of a country.
170+
:return: Returns the country information in array. Refer below table for the fields avaliable in the array.
171+
:rtype: array
172+
173+
**RETURN FIELDS**
174+
175+
| Field Name | Description |
176+
| ---------------- | ------------------------------------------------------------ |
177+
| countryCode | Two-character country code based on ISO 3166. |
178+
| countryAlpha3Code | Three-character country code based on ISO 3166. |
179+
| countryNumericCode | Three-character country code based on ISO 3166. |
180+
| capital | Capital of the country. |
181+
| countryDemonym | Demonym of the country. |
182+
| totalArea | Total area in km{sup}`2`. |
183+
| population | Population of year 2014. |
184+
| idd_code | The IDD prefix to call the city from another country. |
185+
| currencyCode | Currency code based on ISO 4217. |
186+
| currencyName | Currency name. |
187+
| currencySymbol | Currency symbol. |
188+
| langCode | Language code based on ISO 639. |
189+
| langName | Language name. |
190+
| cctld | Country-Code Top-Level Domain. |
191+
```
192+
193+
## Region Class
194+
195+
```{py:class} Region(csvFilePath)
196+
Initiate Ip2locationRegion class and load the IP2Location ISO 3166-2 Subdivision Code CSV file. This database is free for download at <https://www.ip2location.com/free/iso3166-2>
197+
198+
:param str csvFilePath: (Required) The file path links to IP2Location ISO 3166-2 Subdivision Code CSV file.
199+
```
200+
201+
```{py:function} getRegionCode(countryCode, regionName)
202+
Provide a ISO 3166 country code and the region name to get ISO 3166-2 subdivision code for the region.
203+
204+
:param str countryCode: (Required) Two-character country code based on ISO 3166.
205+
:param str regionName: (Required) Region or state name.
206+
:return: Returns the ISO 3166-2 subdivision code of the region.
207+
:rtype: str
208+
```

‎docs/source/conf.py‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
# Read https://www.sphinx-doc.org/en/master/usage/configuration.html for more options available
3+
4+
import sphinx_pdj_theme
5+
6+
# -- Project information
7+
8+
project = 'IP2Location Node.js'
9+
copyright = '2023, IP2Location'
10+
author = 'IP2Location'
11+
12+
release = '1.0.0'
13+
version = '1.0.0'
14+
15+
# -- General configuration
16+
17+
extensions = [
18+
'sphinx.ext.duration',
19+
'sphinx.ext.doctest',
20+
'myst_parser',
21+
'sphinx_copybutton',
22+
]
23+
24+
# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
25+
26+
myst_enable_extensions = [
27+
"colon_fence",
28+
"deflist",
29+
"fieldlist",
30+
]
31+
32+
# templates_path = ['_templates']
33+
34+
# -- Options for HTML output
35+
36+
html_theme = 'sphinx_pdj_theme'
37+
html_theme_path = [sphinx_pdj_theme.get_html_theme_path()]
38+
39+
# PDJ theme options, see the list of available options here: https://github.com/jucacrispim/sphinx_pdj_theme/blob/master/sphinx_pdj_theme/theme.conf
40+
html_theme_options = {
41+
# Hide the name of the project above the search bar
42+
'home_link': 'hide'
43+
}
44+
45+
# The name of an image file (relative to this directory) to place at the top
46+
# of the sidebar.
47+
html_logo = 'images/ipl-logo-square-1200.png'
48+
49+
# Favicon
50+
html_favicon = 'images/favicon.ico'
51+
52+
html_title = "IP2Location Python"

‎docs/source/images/favicon.ico‎

14.7 KB
Binary file not shown.

‎docs/source/images/ipl-logo-square-1200.png‎

19.8 KB
Loading

‎docs/source/index.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
[![npm](https://img.shields.io/npm/v/ip2location-nodejs.svg)](http://npm.im/ip2location-nodejs)
2+
[![npm](https://img.shields.io/npm/dm/ip2location-nodejs.svg)](http://npm.im/ip2location-nodejs)
3+
# IP2Location Node.js Library
4+
5+
This Node.js module provides a fast lookup of country, region, city, latitude, longitude, ZIP code, time zone, ISP, domain name, connection type, IDD code, area code, weather station code, station name, mcc, mnc, mobile brand, elevation, usage type, address type, IAB category, district, autonomous system number (ASN) and autonomous system (AS) from IP address by using IP2Location database. This module uses a file based database available at IP2Location.com. This database simply contains IP blocks as keys, and other information such as country, region, city, latitude, longitude, ZIP code, time zone, ISP, domain name, connection type, IDD code, area code, weather station code, station name, mcc, mnc, mobile brand, elevation, usage type, address type, IAB category, district, autonomous system number (ASN) and autonomous system (AS) as values. It supports both IP address in IPv4 and IPv6.
6+
7+
This module can be used in many types of projects such as:
8+
9+
- select the geographically closest mirror
10+
- analyze your web server logs to determine the countries of your visitors
11+
- credit card fraud detection
12+
- software export controls
13+
- display native language and currency
14+
- prevent password sharing and abuse of service
15+
- geotargeting in advertisement
16+
17+
The database will be updated on a monthly basis for greater accuracy.
18+
19+
The complete database is available at https://www.ip2location.com under Premium subscription package.
20+
The free LITE database is available at https://lite.ip2location.com.
21+
22+
23+
## Table of contents
24+
```{eval-rst}
25+
.. toctree::
26+
27+
self
28+
quickstart
29+
code
30+
```

0 commit comments

Comments
 (0)