jointhestudentlife

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 15, 2026 License: MIT Imports: 12 Imported by: 0

README

jointhestudentlife-go

Official Go SDK for The Student Life: student events, ticket prices, city guides and student deals in 85+ cities, for international and exchange students.

The API is open. No key, no signup, no payment. Standard library only.

go get github.com/jointhestudentlife/jointhestudentlife-go
import tsl "github.com/jointhestudentlife/jointhestudentlife-go"

c := tsl.New()
evs, err := c.Events(ctx, tsl.EventsParams{City: "paris", Type: "halloween"})
// evs.Events[0].Tickets.Options: [{Round 1 9.5 EUR} ...]

guide, err := c.City(ctx, "lisbon")

// async report job: 202 Accepted, then poll until it succeeds
job, err := c.RunReport(ctx, tsl.ReportRequest{Type: "city_comparison", Cities: []string{"berlin", "lisbon"}})

Methods: Info, Cities, City, Events, Event, Partners, Pricing, AllCities, AllEvents, CreateReport, GetReport, RunReport, SendMessage. Errors are *tsl.Error with Status and Code (including timeout and network_error). Requests retry on 429 (honouring Retry-After); reads also retry on 5xx, while a message is only retried when it carries an idempotency key, so it is never sent twice by the SDK.

SendMessage emails our team on someone's behalf. Only use it with that person's consent and their own name and email. Set DryRun: true to validate without sending, and pass a fresh idempotency key per message so a retry is recognised. Messages are limited to a few per minute.

Also available: the MCP server at https://jointhestudentlife.com/mcp, the JavaScript SDK and CLI on npm (jointhestudentlife), the Python SDK on PyPI (jointhestudentlife) and the OpenAPI spec at https://jointhestudentlife.com/openapi.json. Full docs: https://jointhestudentlife.com/developers

Licence

The MIT licence covers the code of this module only. The data the API returns, the website content and The Student Life name and logo stay with Socials BV.

Documentation

Overview

Package jointhestudentlife is the official Go SDK for The Student Life: student events, ticket prices, city guides and student deals in 85+ cities, from the open REST API at https://jointhestudentlife.com/api/v1 (docs: https://jointhestudentlife.com/developers).

Standard library only. The API is open: no key, no signup.

c := jointhestudentlife.New()
evs, err := c.Events(ctx, jointhestudentlife.EventsParams{City: "berlin", Type: "halloween"})

Index

Constants

View Source
const DefaultBaseURL = "https://jointhestudentlife.com"

DefaultBaseURL is the production API host.

View Source
const Version = "1.0.0"

Version of this SDK.

Variables

This section is empty.

Functions

This section is empty.

Types

type CitiesParams

type CitiesParams struct {
	Q, Country, Cursor string
	Limit              int
}

CitiesParams filters a city search.

type City

type City struct {
	Slug         string  `json:"slug"`
	Name         string  `json:"name"`
	Country      string  `json:"country"`
	CountryCode  string  `json:"country_code"`
	Summary      string  `json:"summary"`
	FestivalName string  `json:"festival_name"`
	CityGuideURL string  `json:"city_guide_url"`
	FestivalURL  string  `json:"festival_url"`
	HalloweenURL *string `json:"halloween_url"`
}

City is a city card from a search.

type CityList

type CityList struct {
	Total      int     `json:"total"`
	Cities     []City  `json:"cities"`
	NextCursor *string `json:"next_cursor"`
}

CityList is one page of cities.

type Client

type Client struct {
	BaseURL    string
	HTTPClient *http.Client
	MaxRetries int // retries for 429, and for 5xx on GET or a POST with an idempotency key (0 to 5)
	UserAgent  string
}

Client talks to the API. The zero value is not usable; call New.

func New

func New(opts ...Option) *Client

New returns a client for the production API with a 30 second timeout and 2 retries.

func (*Client) AllCities

func (c *Client) AllCities(ctx context.Context, p CitiesParams) ([]City, error)

AllCities walks every page of a city search.

func (*Client) AllEvents

func (c *Client) AllEvents(ctx context.Context, p EventsParams) ([]Event, error)

AllEvents walks every page of an event listing.

func (*Client) Cities

func (c *Client) Cities(ctx context.Context, p CitiesParams) (*CityList, error)

Cities searches the cities The Student Life covers.

func (*Client) City

func (c *Client) City(ctx context.Context, slugOrName string) (map[string]any, error)

City returns the full student guide for one city (slug or name). The guide is rich, so it is a map.

func (*Client) CreateReport

func (c *Client) CreateReport(ctx context.Context, r ReportRequest) (*ReportJob, error)

CreateReport starts a report job (the API answers 202 Accepted).

func (*Client) Event

func (c *Client) Event(ctx context.Context, id string) (*Event, error)

Event returns one event by id, for example "berlin-hw26".

func (*Client) Events

func (c *Client) Events(ctx context.Context, p EventsParams) (*EventList, error)

Events lists events with ticket prices and status.

func (*Client) GetReport

func (c *Client) GetReport(ctx context.Context, id string) (*ReportJob, error)

GetReport polls a report job.

func (*Client) Info

func (c *Client) Info(ctx context.Context) (map[string]any, error)

Info returns the API index: endpoints, version and policies.

func (*Client) Partners

func (c *Client) Partners(ctx context.Context, category, q string) (map[string]any, error)

Partners lists student discount codes from partners.

func (*Client) Pricing

func (c *Client) Pricing(ctx context.Context, city string) (map[string]any, error)

Pricing returns what is free and what tickets cost, optionally for one city.

func (*Client) RunReport

func (c *Client) RunReport(ctx context.Context, r ReportRequest) (*ReportJob, error)

RunReport creates a report and polls once a second until it succeeds or ctx ends.

func (*Client) SendMessage

func (c *Client) SendMessage(ctx context.Context, m Message, idempotencyKey string) (map[string]any, error)

SendMessage emails the team on someone's behalf. Set DryRun to validate without sending. Pass a fresh idempotency key (a UUID) per message to make retries safe; "" disables retries on 5xx.

type Error

type Error struct {
	Status  int    // HTTP status, 0 for network errors
	Code    string // API error code, e.g. not_found, rate_limited, timeout, network_error
	Message string
	Body    []byte
}

Error is an error answer from the API, or a network problem (Status 0).

func (*Error) Error

func (e *Error) Error() string

type Event

type Event struct {
	ID            string  `json:"id"`
	Type          string  `json:"type"`
	Name          string  `json:"name"`
	City          string  `json:"city"`
	CitySlug      *string `json:"city_slug"`
	Start         string  `json:"start"`
	End           *string `json:"end"`
	Timezone      *string `json:"timezone"`
	Venue         *Venue  `json:"venue"`
	AgeMin        *int    `json:"age_min"`
	Image         *string `json:"image"`
	Description   string  `json:"description"`
	URL           string  `json:"url"`
	Status        string  `json:"status"`
	Tickets       Tickets `json:"tickets"`
	WaitlistOpen  bool    `json:"waitlist_open"`
	WhatsAppGroup *string `json:"whatsapp_group"`
	EntryRule     *string `json:"entry_rule"`
}

Event is one student event.

type EventList

type EventList struct {
	Total      int     `json:"total"`
	Events     []Event `json:"events"`
	NextCursor *string `json:"next_cursor"`
	Note       string  `json:"note,omitempty"`
}

EventList is one page of events.

type EventsParams

type EventsParams struct {
	City, Type, Cursor string
	IncludePast        bool
	Limit              int
}

EventsParams filters events. Type is all, halloween, welcome_festival, semester_kickoff or orientation_week.

type Message

type Message struct {
	Name    string `json:"name"`
	Email   string `json:"email"`
	Message string `json:"message"`
	Subject string `json:"subject,omitempty"`
	City    string `json:"city,omitempty"`
	DryRun  bool   `json:"dry_run,omitempty"` // validate and send nothing
}

Message is a message to the team. Only send one with the person's consent and their own name and email.

type Option

type Option func(*Client)

Option configures a Client.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL points the client at another host.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient sets the HTTP client (for proxies, custom timeouts or tests).

func WithMaxRetries

func WithMaxRetries(n int) Option

WithMaxRetries sets the retry budget, clamped to 0..5.

type ReportJob

type ReportJob struct {
	ID          string          `json:"id"`
	Type        string          `json:"type"`
	Status      string          `json:"status"`
	CreatedAt   string          `json:"created_at"`
	ExpiresAt   string          `json:"expires_at"`
	CompletedAt string          `json:"completed_at,omitempty"`
	StatusURL   string          `json:"status_url"`
	Result      json.RawMessage `json:"result,omitempty"`
}

ReportJob is the state of a report job; Result is set once Status is "succeeded".

type ReportRequest

type ReportRequest struct {
	Type      string   `json:"type"`
	Cities    []string `json:"cities,omitempty"`
	EventType string   `json:"event_type,omitempty"`
}

ReportRequest starts a report job. Type is city_comparison (2 to 10 Cities) or events_overview.

type TicketOption

type TicketOption struct {
	Name     string  `json:"name"`
	Price    float64 `json:"price"`
	Currency string  `json:"currency"`
}

TicketOption is one ticket type with its price.

type Tickets

type Tickets struct {
	Status      string          `json:"status"` // on_sale, opens_soon, coming_soon, sold_out, ended
	SalesOpenAt *string         `json:"sales_open_at"`
	Options     []TicketOption  `json:"options"`
	EarlyAccess json.RawMessage `json:"early_access"`
	BuyURL      string          `json:"buy_url"`
	Note        string          `json:"note"`
}

Tickets describes what can be bought and when.

type Venue

type Venue struct {
	Name    string `json:"name"`
	Address string `json:"address"`
}

Venue is where an event takes place (nil while the venue is not announced).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL