portmap

Scrape the Wikipedia list of TCP/UDP port numbers into a local NDJSON database with revision tracking. Only fetches from Wikipedia when the article has actually changed.

Install

pip install portmapper

Python Library

from portmap import PortMap

pm = PortMap(data_dir='~/.local/share/portmap')

# Fetch/update from Wikipedia (only if stale)
records = pm.update()

# Force a fresh pull
records = pm.update(force=True)

# Load cached data without hitting the network
records = pm.load()

# Look up specific ports — returns matching record dicts
results = pm.lookup(80, 443, 6667)

# Search descriptions by keyword
results = pm.search('minecraft')

# Fetch the last year of revision history
revisions = pm.history(days=365)

Every method returns plain list[dict] values you can work with directly:

for rec in pm.lookup(22, 80):
    port = rec['port']          # int or "start-end" str
    for svc in rec['services']:
        print(port, svc['tcp'], svc['udp'], svc['description'])

CLI Usage

Examples

# Look up ports
portmap 80,443,6667

# Search for a keyword
portmap -s irc

# NDJSON output (pipe to jq)
portmap 80,443 -j

# Store data in a custom directory
portmap -u --data-dir ~/.local/share/portmap

# Fetch revision history
portmap --history 365

# Start the API server
portmap --serve

# Bind to a specific address and port
portmap --serve --host 0.0.0.0 --port 8080

API Server

Start with portmap --serve. Binds to 127.0.0.1:6660 by default.

curl -s localhost:6660/ports/22,80 | jq .
curl -s 'localhost:6660/ports?search=irc&limit=10' | jq .
curl -s 'localhost:6660/history?limit=5' | jq .

Output

PORT        TCP         UDP         SCTP        DCCP        DESCRIPTION
────────────────────────────────────────────────────────────────────────
80          Yes         Yes         Yes         --          Hypertext Transfer Protocol (HTTP) uses TCP in versions 1.x and 2.
443         Yes         Yes         Yes         --          Hypertext Transfer Protocol Secure (HTTPS) uses TCP in versions 1.x and 2.
6665-6669   Yes         --          --          --          Internet Relay Chat (IRC)

Mirrors: SuperNETs • GitHub • GitLab • Codeberg