pinterest-url-normalizer

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

SavePinner · 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

Kind	Example
pin	https://www.pinterest.com/pin/123456789/
short	https://pin.it/AbC123
profile	https://www.pinterest.com/savepinner/
board	https://www.pinterest.com/savepinner/media-tools/
ideas	https://www.pinterest.com/ideas/space-wallpaper/926295399832/

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 is maintained by the team behind SavePinner, a browser tool for inspecting media exposed by public Pinterest Pin URLs. The package 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