Skip to content

Tarot Cards API

Tarot Cards API will help you to get random tarot cards with upright and reversed cards. Not random but calculated based on your numerology meaning (name, date of birth, question).

API Endpoints Reference

draw_cards async 

draw_cards(request: CardsAPIRequest) -> CardsAPIResponse
Method Path Description
POST /tarot-cards/draw Get shuffled tarot cards
PARAMETER DESCRIPTION
request

The request object containing the name, dob, and count.

TYPE: CardsAPIRequest

RETURNS DESCRIPTION
CardsAPIResponse

The response object containing the cards.

TYPE: CardsAPIResponse

Note

This function uses the get_shuffled_cards function to get the shuffled tarot cards.

Example Request

{
    "name": "John Doe",
    "dob": "2000-01-01",
    "count": 5,
    "follow_numerology": false
}

Example Response

{
    "cards": [
        {
            "name": "Eight of Pentacles",
            "is_upright": false,
            "image_url": "/tarot-cards/images/72.jpg",
            "full_card_name": "Eight of Pentacles (REVERSED)"
        },
        {
            "name": "King of Cups",
            "is_upright": false,
            "image_url": "/tarot-cards/images/36.jpg",
            "full_card_name": "King of Cups (REVERSED)"
        },
        ...
    ]
}
Source code in api/index.py 
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
@app.post("/tarot-cards/draw", response_model=CardsAPIResponse, tags=["Tarot Cards API"])
async def draw_cards(request: CardsAPIRequest) -> CardsAPIResponse:
    """
    | Method | Path                       | Description                                       |
    | ------ | -------------------------- | ------------------------------------------------- |
    | `POST` | `/tarot-cards/draw`        | Get shuffled tarot cards                          |

    Params:
        request (CardsAPIRequest): The request object containing the name, dob, and count.

    Returns:
        CardsAPIResponse: The response object containing the cards.

    !!! note
        This function uses the `get_shuffled_cards` function to get the shuffled tarot cards.

    !!! example "Example Request"

        ```json
        {
            "name": "John Doe",
            "dob": "2000-01-01",
            "count": 5,
            "follow_numerology": false
        }
        ```

    !!! example "Example Response"

        ```json
        {
            "cards": [
                {
                    "name": "Eight of Pentacles",
                    "is_upright": false,
                    "image_url": "/tarot-cards/images/72.jpg",
                    "full_card_name": "Eight of Pentacles (REVERSED)"
                },
                {
                    "name": "King of Cups",
                    "is_upright": false,
                    "image_url": "/tarot-cards/images/36.jpg",
                    "full_card_name": "King of Cups (REVERSED)"
                },
                ...
            ]
        }
        ```
    """
    if request.follow_numerology:
        universe_number = NUMEROLOGY_READER.calculate(request.name, request.dob)["personal_numerology"]
    else:
        universe_number = None

    tarot_deck = TarotDeck(seed=universe_number)
    shuffled_cards = tarot_deck.draw(count=request.count)
    return CardsAPIResponse(cards=shuffled_cards)

get_card_info 

get_card_info(card_number: int) -> CardInfoAPIResponse
Method Path Description
GET /tarot-cards/get-card-info Get card info by number
PARAMETER DESCRIPTION
card_number

The card number (Range: 1-78).

TYPE: int

RETURNS DESCRIPTION
CardInfoAPIResponse

The response object containing the card info.

TYPE: CardInfoAPIResponse

Note

This function uses the TarotDeck class to get the card info.

Example Response

{
    "name": "The Fool",
    "number": "1",
    "arcana": "The Fool",
    "suit": "Major Arcana",
    "image_url": "/tarot-cards/images/1.jpg",
    "fortune_telling": ["..."],
    "keywords": ["..."],
    "meanings": {...},
    "archetype": "...",
    "hebrew_alphabet": "...",
    "numerology": "...",
    "elemental": "...",
    "mythical_spiritual": "...",
    "questions_to_ask": ["..."]
}
Source code in api/index.py 
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
@app.get("/tarot-cards/get-card-info", response_model=CardInfoAPIResponse, tags=["Tarot Cards API"])
def get_card_info(card_number: int) -> CardInfoAPIResponse:
    """
    | Method | Path                                  | Description                                 |
    | ------ | ------------------------------------- | ------------------------------------------- |
    | `GET`  | `/tarot-cards/get-card-info`          | Get card info by number                     |

    Params:
        card_number (int): The card number (Range: 1-78).

    Returns:
        CardInfoAPIResponse: The response object containing the card info.

    !!! note
        This function uses the `TarotDeck` class to get the card info.

    !!! example "Example Response"

        ```json
        {
            "name": "The Fool",
            "number": "1",
            "arcana": "The Fool",
            "suit": "Major Arcana",
            "image_url": "/tarot-cards/images/1.jpg",
            "fortune_telling": ["..."],
            "keywords": ["..."],
            "meanings": {...},
            "archetype": "...",
            "hebrew_alphabet": "...",
            "numerology": "...",
            "elemental": "...",
            "mythical_spiritual": "...",
            "questions_to_ask": ["..."]
        }
        ```
    """
    if not 1 <= card_number <= 78:
        raise HTTPException(status_code=400, detail="Card number must be between 1 and 78")

    tarot_deck = TarotDeck()
    card_info = tarot_deck.get_card_info(card_number)
    return CardInfoAPIResponse(**card_info)

Models Reference

TarotCard pydantic-model

Show JSON schema: 
{
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "is_upright": {
      "title": "Is Upright",
      "type": "boolean"
    },
    "image_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Image Url"
    }
  },
  "required": [
    "name",
    "is_upright"
  ],
  "title": "TarotCard",
  "type": "object"
}

Fields:

  • name (str)
  • is_upright (bool)
  • image_url (Optional[str])

CardsAPIRequest pydantic-model

Show JSON schema: 
{
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "dob": {
      "title": "Dob",
      "type": "string"
    },
    "count": {
      "default": 10,
      "title": "Count",
      "type": "integer"
    },
    "follow_numerology": {
      "default": false,
      "title": "Follow Numerology",
      "type": "boolean"
    }
  },
  "required": [
    "name",
    "dob"
  ],
  "title": "CardsAPIRequest",
  "type": "object"
}

Fields:

  • name (str)
  • dob (str)
  • count (int)
  • follow_numerology (bool)

Validators:

  • validate_dob_format → dob

CardsAPIResponse pydantic-model

Show JSON schema: 
{
  "$defs": {
    "TarotCard": {
      "properties": {
        "name": {
          "title": "Name",
          "type": "string"
        },
        "is_upright": {
          "title": "Is Upright",
          "type": "boolean"
        },
        "image_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Image Url"
        }
      },
      "required": [
        "name",
        "is_upright"
      ],
      "title": "TarotCard",
      "type": "object"
    }
  },
  "properties": {
    "cards": {
      "items": {
        "$ref": "#/$defs/TarotCard"
      },
      "title": "Cards",
      "type": "array"
    }
  },
  "required": [
    "cards"
  ],
  "title": "CardsAPIResponse",
  "type": "object"
}

Fields:

  • cards (List[TarotCard])

CardInfoAPIResponse pydantic-model

Show JSON schema: 
{
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "number": {
      "title": "Number",
      "type": "string"
    },
    "arcana": {
      "title": "Arcana",
      "type": "string"
    },
    "suit": {
      "title": "Suit",
      "type": "string"
    },
    "image_url": {
      "title": "Image Url",
      "type": "string"
    },
    "fortune_telling": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Fortune Telling"
    },
    "keywords": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Keywords"
    },
    "meanings": {
      "anyOf": [
        {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Meanings"
    },
    "archetype": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Archetype"
    },
    "hebrew_alphabet": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Hebrew Alphabet"
    },
    "numerology": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Numerology"
    },
    "elemental": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Elemental"
    },
    "mythical_spiritual": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Mythical Spiritual"
    },
    "questions_to_ask": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Questions To Ask"
    }
  },
  "required": [
    "name",
    "number",
    "arcana",
    "suit",
    "image_url"
  ],
  "title": "CardInfoAPIResponse",
  "type": "object"
}

Fields:

  • name (str)
  • number (str)
  • arcana (str)
  • suit (str)
  • image_url (str)
  • fortune_telling (Optional[List[str]])
  • keywords (Optional[List[str]])
  • meanings (Optional[Dict[str, List[str]]])
  • archetype (Optional[str])
  • hebrew_alphabet (Optional[str])
  • numerology (Optional[str])
  • elemental (Optional[str])
  • mythical_spiritual (Optional[str])
  • questions_to_ask (Optional[List[str]])