Sorted Travel Docs

sorted-travel

Official Python, JavaScript, Go, and Ruby SDK and CLI for the Sorted Travel REST API.

This repository publishes:

• Python: sorted-travel on PyPI (pip install sorted-travel)
• JavaScript: sorted-travel on npm (npm install sorted-travel, source in js/)
• Go: github.com/a-l-e-x-k/sorted-travel-sdk/go (go get github.com/a-l-e-x-k/sorted-travel-sdk/go, source in go/)
• Ruby: sorted-travel on RubyGems (gem install sorted-travel, source in ruby/)
• Agent skills on skills.sh: sorted-travel, sorted-travel-destinations, sorted-travel-weather, sorted-travel-visa
• Agent Plugin: plugin.json, skills/, and mcp.json (Agent Plugins v1)

This is a stdlib-only Python client and a zero-dependency JavaScript client for the public endpoints at https://sorted.travel. Destination ranking, facts, weather, and visa tools are a free tier with zero-auth access. An API key is optional.

• Homepage: https://sorted.travel
• Developer portal: https://sorted.travel/developers
• SDK guide: https://sorted.travel/sdks.md
• OpenAPI: https://sorted.travel/openapi.json
• MCP: https://sorted.travel/mcp
• Docs MCP: https://sorted.travel/docs/mcp
• Smithery: sorted-travel/destinations
• PyPI: https://pypi.org/project/sorted-travel/
• npm: https://www.npmjs.com/package/sorted-travel/
• Go module: https://pkg.go.dev/github.com/a-l-e-x-k/sorted-travel-sdk/go
• RubyGems: https://rubygems.org/gems/sorted-travel

Agent skills (skills.sh)

Install Sorted Travel agent skills for Cursor, Claude Code, Codex, and other supported agents:

npx skills add a-l-e-x-k/sorted-travel-sdk

Non-interactive install for Cursor:

npx skills add a-l-e-x-k/sorted-travel-sdk -y -a cursor

Install one capability area:

npx skills add a-l-e-x-k/sorted-travel-sdk --skill sorted-travel-weather

Skill	Use when
sorted-travel	Where to go / ranked recommendations
sorted-travel-destinations	Place facts for a named destination
sorted-travel-weather	Forecast, climate, best months
sorted-travel-visa	Passport visa hassle

They teach agents when to use Sorted Travel, how to connect the product MCP at https://sorted.travel/mcp and the docs MCP at https://sorted.travel/docs/mcp, and which tools to call. Groupings: skills.sh.json.

Connect MCP directly with mcp.json or Smithery:

npx -y smithery mcp add sorted-travel/destinations

Install SDKs

Python:

pip install sorted-travel

JavaScript:

npm install sorted-travel

Go:

go get github.com/a-l-e-x-k/sorted-travel-sdk/[email protected]

Ruby:

gem install sorted-travel

Quickstart (Python)

from sorted_travel import Client

client = Client()
print(client.status())
page = client.list_destinations(limit=20)
print(page["data"][0]["handle"], page["has_more"])

Destination tools need no key. If a host still requires one:

client = Client(api_key="st_sandbox_...")  # or set SORTED_TRAVEL_API_KEY

Self-serve sandbox keys:

payload = client.create_api_key()

Quickstart (JavaScript)

import { Client } from "sorted-travel"

const client = new Client()
await client.status()
await client.listDestinations({ limit: 20 })

Quickstart (Go)

import (
	"context"

	"github.com/a-l-e-x-k/sorted-travel-sdk/go/sortedtravel"
)

client := sortedtravel.NewClient()
client.Status(context.Background())
limit := 20
client.ListDestinations(context.Background(), nil, &limit)

Quickstart (Ruby)

require "sorted_travel"

client = SortedTravel::Client.new
client.status
client.list_destinations(limit: 20)

CLI

sorted-travel status
sorted-travel destinations --limit 5
sorted-travel sandbox
sorted-travel api-key

JavaScript CLI via npm:

npx sorted-travel status

Go CLI:

go run ./go/cmd/sorted-travel status

Ruby CLI:

sorted-travel status

Configuration

Constructor arg	Environment variable	Default
api_key	SORTED_TRAVEL_API_KEY	—
base_url	SORTED_TRAVEL_BASE_URL	https://sorted.travel
timeout	—	30.0 seconds

Surface

• status() — GET /api/v1/status
• list_destinations(cursor=, limit=) — GET /api/v1/destinations
• create_api_key() — POST /api/v1/api-keys
• sandbox() — GET /sandbox
• create_job(operation, **body) — POST /api/v1/jobs
• get_job(job_id) — GET /api/v1/jobs/{job_id}
• get(path, params=) / post(path, body=) — raw REST escape hatch

Interactive ranking, weather, and visa still go through MCP at https://sorted.travel/mcp. These SDK packages do not wrap JSON-RPC.

License

MIT. The Sorted Travel product remains under its own terms at https://sorted.travel/terms.