pinteresturl

README

pinterest-url-normalizer-go

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

SavePinner · Go documentation · npm · PyPI · crates.io · Packagist

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 query parameters and fragments from normalized output.

Install

go get github.com/jiankn/pinterest-url-normalizer-go@v0.1.0

Library

package main

import (
	"fmt"

	pinteresturl "github.com/jiankn/pinterest-url-normalizer-go"
)

func main() {
	parsed, err := pinteresturl.Parse(
		"https://de.pinterest.com/pin/987654321/?utm_source=share",
	)
	if err != nil {
		panic(err)
	}

	fmt.Println(parsed.PinID)         // 987654321
	fmt.Println(parsed.NormalizedURL) // https://www.pinterest.com/pin/987654321/
}

CLI

go run ./cmd/pinterest-url-normalizer \
  "https://de.pinterest.com/pin/987654321/?utm_source=share" \
  "https://pin.it/AbC123"

Read one URL per line and emit JSON Lines:

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

The process exits with status 1 when any input is invalid and status 2 for usage errors.

Supported URLs

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.

License

MIT

Documentation

Overview

Package pinteresturl parses, classifies, and normalizes supported Pinterest URLs without making network requests.

Full Pinterest URLs are normalized to www.pinterest.com. Short pin.it links retain their host because resolving them requires a network request.

For a browser-based Pinterest downloader, see SavePinner: https://savepinner.com/pinterest-downloader/

Index

• func IsPinterestHost(host string) bool
• func IsPinterestURL(input string) bool
• func Normalize(input string) (string, error)
• type ErrorCode
  • func ErrorCodeOf(err error) ErrorCode
• type Kind
• type ParseError
  • func (e *ParseError) Error() string
• type ParsedURL
  • func Parse(input string) (ParsedURL, error)

Functions

func IsPinterestHost

func IsPinterestHost(host string) bool

IsPinterestHost reports whether host is an exact supported Pinterest host.

func IsPinterestURL

func IsPinterestURL(input string) bool

IsPinterestURL reports whether input is a supported Pinterest URL.

func Normalize

func Normalize(input string) (string, error)

Normalize returns the canonical URL for a supported Pinterest URL.

Types

type ErrorCode

type ErrorCode string

ErrorCode is a stable, machine-readable error category.

const (
	InvalidURL     ErrorCode = "INVALID_URL"
	UnsupportedURL ErrorCode = "UNSUPPORTED_URL"
)

func ErrorCodeOf

func ErrorCodeOf(err error) ErrorCode

ErrorCodeOf returns the stable code for a parsing error.

type Kind

type Kind string

Kind identifies a supported Pinterest URL class.

const (
	KindPin     Kind = "pin"
	KindShort   Kind = "short"
	KindProfile Kind = "profile"
	KindBoard   Kind = "board"
	KindIdeas   Kind = "ideas"
)

type ParseError

type ParseError struct {
	Code    ErrorCode `json:"code"`
	Message string    `json:"message"`
}

ParseError describes an invalid URL or an unsupported Pinterest path.

func (*ParseError) Error

func (e *ParseError) Error() string

type ParsedURL

type ParsedURL struct {
	Kind          Kind   `json:"kind"`
	OriginalURL   string `json:"original_url"`
	NormalizedURL string `json:"normalized_url"`
	Host          string `json:"host"`
	PinID         string `json:"pin_id,omitempty"`
	Shortcode     string `json:"shortcode,omitempty"`
	Username      string `json:"username,omitempty"`
	BoardSlug     string `json:"board_slug,omitempty"`
	IdeaSlug      string `json:"idea_slug,omitempty"`
	IdeaID        string `json:"idea_id,omitempty"`
}

ParsedURL contains a supported Pinterest URL and its canonical fields.

func Parse

func Parse(input string) (ParsedURL, error)

Parse classifies a supported Pinterest URL and returns canonical fields.