pinterest-url-normalizer

Parse, classify, and normalize Pinterest URLs without making network requests.

TypeScript package on JSR · Source code

The package recognizes Pin, pin.it, profile, board, and Ideas URLs across Pinterest country domains. It uses an exact host allow list, rejects HTTP URLs and lookalike domains, and removes tracking parameters from normalized output.

Install

python -m pip install pinterest-url-normalizer

Python API

from pinterest_url_normalizer import (
    is_pinterest_url,
    normalize_pinterest_url,
    parse_pinterest_url,
)

parsed = parse_pinterest_url("https://de.pinterest.com/pin/987654321/?utm_source=share")

print(parsed.kind)  # pin
print(parsed.pin_id)  # 987654321
print(parsed.normalized_url)  # https://www.pinterest.com/pin/987654321/

is_pinterest_url("https://pin.it/AbC123")
normalize_pinterest_url("https://pinterest.co.uk/savepinner/media-tools/")

Command line

Normalize URL arguments:

pinterest-url-normalizer \
  "https://pinterest.co.uk/pin/123/?utm_source=share" \
  "https://pin.it/AbC123"

Or pipe one URL per line and emit JSON Lines:

printf '%s\n' 'https://www.pinterest.com/pin/123/' | \
  pinterest-url-normalizer --json

The command exits with status 1 when any input is invalid and 2 when no input is provided.

Supported URL kinds

pin.it links are classified and normalized but are not followed. Resolving them requires a network request and belongs in the consuming application.

API

• parse_pinterest_url(value) returns an immutable ParsedPinterestUrl. It raises PinterestUrlError with code INVALID_URL or UNSUPPORTED_URL on failure.
• normalize_pinterest_url(value) returns the canonical URL.
• is_pinterest_url(value) validates a supported URL form.
• is_pinterest_host(host) checks a hostname against the exact country-domain allow list.

Why this package exists

This parser only prepares canonical links; it never fetches media. When a public Pin contains a still image, continue in the Pinterest image downloader to compare the image and thumbnail variants exposed for that Pin. The package itself contains no downloader, tracking, browser automation, or remote code.

Pinterest is a trademark of Pinterest, Inc. This project is independent and is not affiliated with or endorsed by Pinterest.

License

MIT