🥏 DiscIt API

RESTful API for disc golf discs.

Enables developers to programmatically access public disc information from the amazing Marshall Street Disc Golf Interactive Flight Guide web page. Disc data is refreshed nightly via the DiscIt API Refresh Service.

Check it out live on fly.io! discit-api.fly.dev

Docs

Check out the Swagger docs at discit-api.fly.dev/docs or see below for endpoints, example requests, and field reference.

Public Endpoints

Method	Route	Description
GET	/disc	All discs
GET	/disc?	By field(s)
GET	/disc/:id	By id

Example Requests

• All discs: /disc
• By one field: /disc?stability=very-overstable
• By multiple fields: /disc?brand=innova&category=control-driver
• By id: /disc/dc3616c5-c9f2-55e3-9563-83a00d0805cb

Refer to the Fields section below for all possible query string parameters.

Fields

Field	Searchable?	Search Operator	Description
id	Yes	=	Unique identifier of the disc
name*	Yes	LIKE	Name of the disc: Aviar, Buzz, Crank SS, etc.
brand*	Yes	LIKE	Brand of the disc: Innova, Discraft, Dynamic Discs, etc.
category*	Yes	LIKE	Distance Driver, Hybrid Driver, Control Driver, Midrange, Putter
speed	Yes	=	The relative rate at which the disc can travel through the air: 1 to 15
glide	Yes	=	The relative ability of the disc to maintain loft during its flight: 1 to 7
turn	Yes	=	The tendency of the disc to turn over or bank to the right (for RHBH throws) at the start of its flight: +1 to -5
fade	Yes	=	The tendency of the disc to hook left (for RHBH throws) at the end of its flight: 0 to 5
stability*	Yes	=	Stable, Overstable, Very Overstable, Understable, Very Understable
link	No	N/A	Link to search for the disc in the Marshall Street Disc Golf web store
pic	No	N/A	Link to a picture showing the approximate flight shape of the disc
color	No	N/A	Text color for the disc on the Marshall Street Flight Guide page
background_color	No	N/A	Background color for the disc on the Marshall Street Flight Guide page

* These fields use a URL-friendly slug string for search comparison. All non-alphanumeric characters are stripped out, and each space is replaced with a hyphen (e.g. Crank SS = crank-ss, #1 Driver = 1-driver).

Setup

• Install bun.
• Install package dependencies: bun i
• Create and populate a .env file based on the .env.example file in the root directory.
  • JWT_SECRET: Secret key used to sign and verify JWTs. Can be any string value.
  • API_KEY: Secret key used to authenticate requests to the API. Can be any string value, but must match the value used in the discit-api-refresh project.
  • MONGO_URI (optional): Connection string to a MongoDB database. If not provided, a Docker container will need to be used instead to host the database locally.
• If not using a custom MongoDB connection string, install and run Docker Desktop. Run bun compose:up to initialize the database container.
• Run bun dev to start in watch mode (server restarts on file save).
• Server will listen for requests on localhost:5000.
• To populate the database with disc data, refer to the setup instructions for the discit-api-refresh process.

Technologies

• TypeScript
• Bun
• Elysia
• MongoDB

See Also

• DiscIt - a responsive disc golf disc search engine that uses the DiscIt API.
• Marshall Street Disc Golf Interactive Flight Guide
• PDGA REST API Services
• Disc Flight Ratings System