lindseyb / tarot-api

A simple tarot API

Tarot Api

Requests

GET / [run]

Returns an array of every card

GET /cards [run]

Returns an array of every card

GET /cards/[suit]/[rank] [run]

argument	values	required
suit	one of: swords, wands, cups, coins, or major	yes
rank	one of: king, queen, 1-10 for swords/wands/cups/pentacles or 0-21 for major	yes

Returns a single card in the form of

field	type	description
meanings	hash
meanings["upright"]	array of strings	meanings for this card in the upright position
meanings["reversed"]	array of strings	meanings for this card in the reverse position
name	string	the name of the card written out in words
rank	string or int	rank of the card in the suit up to 21 for major arcana, king through 10 for all other suits
suit	string	major, wands, cups, swords, or pentacles
planet	string	planet associated with this card
signs	array of strings	astrological sign(s) associated with this card
element	string	element associated with this card

Example

GET /cards/swords/10

returns the following JSON

 {
    "name": "Ten of Swords",
    "rank": 10,
    "suit": "swords",
    "planet": null,
    "element": "air",
    "sign": [
       "gemini",
       "libra",
       "aquarius"
    ],
    "meanings": {
       "upright": [
          "failure",
          "defeat",
          "deep wounds",
          "loss",
          "crisis",
          "betrayal"
       ],
       "reversed": [
          "recovery",
          "rebirth",
          "moving on",
          "restoration"
       ]
    }
 }

GET /draw/[n] [run]

Returns n randomly selected cards

argument	values	required
n	positive int	yes

GET /find/[name] [run]

Returns the card by the specified name. Note that the numbers will be spelled out

argument	values	required
name	string name of the card (eg: The Magician)	yes

GET /suits [run]

Returns an array of all the suits of the tarot with key information

GET /suits/[suit]/cards [run]

Returns an array of all the cards in a given suit

argument	values	required
suit	string name of the suit (eg: cups )	yes

GET /suits/[suit] [run]

argument	values	required
suit	string name of the suit (eg: cups )	yes

Returns a single suit in the form of

field	type	description
name	string	the name of the tarot suit
element	string	the element associated with this tarot suit
direction	string	the cardinal direction associated with this tarot suit
season	string	the season associated with this tarot suit
time	string	the time of day associated with this tarot suit
signs	array of strings	astrological signs associated with this suit
keywords	array of strings	words associated with this suit

Testing

bundle exec rake test

Getting Started

bundle install
bundle exec rackup

Deploying

gcloud config set project tarot-api-316423 # set the correct project
gcloud app deploy                          # deploy the app
gcloud app logs tail -s default            # tail the logs to make sure things are gucci

🍦

Thanks

• Sinatra API template https://github.com/noplay/sinatra-api-template
• Initial tarot corpus https://github.com/dariusk/corpora
• Rider-Waite tarot images https://luciellaes.itch.io/rider-waite-smith-tarot-cards-cc0

tarot-api's Issues

Card responses should include links back to the original card

For good API design the card responses should include links to the canonical single card API - might want to add links to the index also for all the different API endpoints.

Add favicon

Update corpus to match how I do readings

The existing tarot api is built on a corpus I found elsewhere. I want to update to use the way I do readings.

Update ruby to 3.2.2

Add Rider-Waite-Smith raw blob of images

https://en.wikipedia.org/wiki/Rider%E2%80%93Waite_Tarot - the images are all open so I can add a response that includes the blob or a custom endpoint to fetch the image blob

Create an endpoint for getting suit information

Create an endpoint for specifically getting suit associations and information.

timing data because I always forget it:

Wands – Days or Spring
Swords – Weeks or Autumn
Cups – Months or Summer
Pentacles – Years or Winter

---

Maybe something like: the table on here https://labyrinthos.co/blogs/tarot-card-meanings-list/the-suit-of-cups-tarot-card-meanings of key data.

403 Forbidden Error on every request with referer set

Every request with a referer set a 403 forbidden error is returned. Not sure why. I've disabled protection and this appears to still be the case. I'm not familiar with debugging problems in rack so. shrug