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/sortedtravel, source in go/)
• Ruby: sorted-travel on RubyGems (gem install sorted-travel, source in ruby/)
• Agent skill: skills/sorted-travel/SKILL.md on skills.sh
• 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
• 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/sortedtravel
• RubyGems: https://rubygems.org/gems/sorted-travel

Agent skill (skills.sh)

Install the Sorted Travel agent skill 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

The skill teaches agents when to use Sorted Travel, how to connect MCP at https://sorted.travel/mcp, and which tools to call. Source: skills/sorted-travel/SKILL.md.

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/go/sortedtravel@v0.1.1

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

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.