# KRCG API
[](https://badge.fury.io/py/krcg-api)
[](https://github.com/lionel-panhaleux/krcg-api/actions/workflows/validation.yml)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
A web API for V:tES based on
the VEKN [official card texts](http://www.vekn.net/card-lists)
and the [Tournament Winning Deck Archive (TWDA)](http://www.vekn.fr/decks/twd.htm).
Portions of the materials are the copyrights and trademarks of Paradox Interactive AB,
and are used with permission. All rights reserved.
For more information please visit [white-wolf.com](http://www.white-wolf.com).
## Online API and documentation
KRCG is a free to use (and documented) [online API](https://api.krcg.org/).
Anyone is free to use it, without warranty.
Breaking changes will only be introduced at major version upgrades,
after a proper deprecation period.
## Contribute
**Contributions are welcome !**
This API is an offspring of the [KRCG](https://github.com/lionel-panhaleux/krcg)
python package, so please refer to that repository for issues, discussions
and contributions guidelines.
## Examples
Query a card by name or ID, get text, rulings and image URL:
```bash
curl -X GET "http://127.0.0.1:8000/card/Alastor" -H "accept: application/json"
```
```json
{
"_name": "Alastor",
"_set": "Gehenna:R, KMW:PAl, KoT:R",
"artists": [
"Monte Moore"
],
"card_text": "Requires a justicar or Inner Circle member...",
"id": 100038,
"name": "Alastor",
"ordered_sets": [
"Gehenna",
"Kindred Most Wanted",
"Keepers of Tradition"
],
"printed_name": "Alastor",
"rulings": {
"links": {
"[ANK 20200901]": "http://www.vekn.net/forum/rules-questions/78830-alastor-and-ankara-citadel#100653",
"[LSJ 20040518-2]": "https://groups.google.com/g/rec.games.trading-cards.jyhad/c/4emymfUPwAM/m/JF_o7OOoCbkJ",
"[LSJ 20040518]": "https://groups.google.com/d/msg/rec.games.trading-cards.jyhad/4emymfUPwAM/B2SCC7L6kuMJ"
},
"text": [
"If the weapon retrieved costs blood, that cost is paid by the vampire chosen by the vote. [LSJ 20040518]",
"Requirements do not apply. If a discipline is required (eg. {Inscription}) and the Alastor vampire does not have it, the inferior version is used. [ANK 20200901] [LSJ 20040518-2]"
]
},
"scans": {
"Gehenna": "https://static.krcg.org/card/set/gehenna/alastor.jpg",
"Keepers of Tradition": "https://static.krcg.org/card/set/keepers-of-tradition/alastor.jpg",
"Kindred Most Wanted": "https://static.krcg.org/card/set/kindred-most-wanted/alastor.jpg"
},
"sets": {
"Gehenna": [{ "rarity": "Rare", "release_date": "2004-05-17"}],
"Keepers of Tradition": [{ "rarity": "Rare", "release_date": "2008-11-19"}],
"Kindred Most Wanted": [
{
"copies": 1,
"precon": "Alastors",
"release_date": "2005-02-21"
}
]
},
"types": ["Political Action"],
"url": "https://static.krcg.org/card/alastor.jpg"
}
```
Search for cards by text, type, discipline, title, city, artist, set,
preconstructed starter, group, capacity, trait, sect, bonus values, etc.:
```bash
curl
-X POST "http://127.0.0.1:8000/card_search"
-H "Content-Type: application/json"
-d "{\"type\":[\"political action\"],\"sect\":[\"anarch\"]}"
```
```json
[
"Anarch Salon",
"Eat the Rich",
"Firebrand",
"Free States Rant",
"Patsy",
"Reckless Agitation",
"Revolutionary Council",
"Sweeper"
]
```
Get candidates for your decklist out of the **TWDA**:
```bash
curl
-X POST "http://127.0.0.1:8000/candidates"
-H "Content-Type: application/json"
-d "{\"cards\":[\"Cybele\",\"Nana Buruku\"]}"
```
```json
[
{
"average": 14,
"card": "Ashur Tablets",
"deviation": 6.25,
"score": 1
},
{
"average": 1,
"card": "Giant's Blood",
"deviation": 0,
"score": 1
},
{
"average": 2,
"card": "The Parthenon",
"deviation": 0.81,
"score": 1
},
{
"average": 1,
"card": "Archon Investigation",
"deviation": 0,
"score": 0.9
},
...
]
```
And a few other features, including:
- search decks in the TWDA, by cards, dates, author and number of players
- deck list format conversion
- retrieving a decklist from an Amaranth share URL
- card name completions
Check the [online documentation](https://api.krcg.org/) for more.
### Hosting the web API
To host the web API, you can use pip to install it:
```bash
pip install "krcg-api"
```
No wsgi server is installed by default, you need to install one.
HTTP web servers can then easily be configured to serve WSGI applications,
check the documentation of your web server.
The API can be served with [uWSGI](https://uwsgi-docs.readthedocs.io):
```bash
uwsgi --module krcg_api.wsgi:application
```
or [Gunicorn](https://gunicorn.org):
```bash
gunicorn krcg_api.wsgi:application
```
Two environment variables are expected: `GITHUB_USERNAME` and `GITHUB_TOKEN`,
to allow the API to connect to Github as a user in order to post new rulings
as issues on the repository (`/submit-ruling` endpoint).
See the [Github help](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)
on how to generate a personal token for the account you want KRCG to use.
#### Development
The development version of KRCG installs uWSGI to serve the API,
this is the preferred WSGI server for now.
```bash
$ pip install -e ".[dev]"
$ make serve
...
uwsgi socket 0 bound to TCP address 127.0.0.1:8000
```
You can check the API is running by using your browser
on the provided address [http://127.0.0.1:8000](http://127.0.0.1:8000).
The environment variables `GITHUB_USERNAME` and `GITHUB_TOKEN` can be provided
by a personal `.env` file at the root of the krcg folder (ignored by git):
```bash
export GITHUB_USERNAME="dedicated_github_username_for_the_api"
export GITHUB_TOKEN="the_matching_github_token"
```
Raw data
{
"_id": null,
"home_page": null,
"name": "krcg-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "vtes, Vampire: The Eternal Struggle, CCG, TWD, TWDA, api, web",
"author": null,
"author_email": "Lionel Panhaleux <lionel.panhaleux+krcg@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2f/21/3a06aac741cff1163a8c023d9f1b68771676415415aa2fef2bf6eecdaf6f/krcg_api-3.1.tar.gz",
"platform": null,
"description": "# KRCG API\n\n[](https://badge.fury.io/py/krcg-api)\n[](https://github.com/lionel-panhaleux/krcg-api/actions/workflows/validation.yml)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n\nA web API for V:tES based on\nthe VEKN [official card texts](http://www.vekn.net/card-lists)\nand the [Tournament Winning Deck Archive (TWDA)](http://www.vekn.fr/decks/twd.htm).\n\nPortions of the materials are the copyrights and trademarks of Paradox Interactive AB,\nand are used with permission. All rights reserved.\nFor more information please visit [white-wolf.com](http://www.white-wolf.com).\n\n\n\n## Online API and documentation\n\nKRCG is a free to use (and documented) [online API](https://api.krcg.org/).\nAnyone is free to use it, without warranty.\n\nBreaking changes will only be introduced at major version upgrades,\nafter a proper deprecation period.\n\n## Contribute\n\n**Contributions are welcome !**\n\nThis API is an offspring of the [KRCG](https://github.com/lionel-panhaleux/krcg)\npython package, so please refer to that repository for issues, discussions\nand contributions guidelines.\n\n## Examples\n\nQuery a card by name or ID, get text, rulings and image URL:\n\n```bash\ncurl -X GET \"http://127.0.0.1:8000/card/Alastor\" -H \"accept: application/json\"\n```\n\n```json\n{\n \"_name\": \"Alastor\",\n \"_set\": \"Gehenna:R, KMW:PAl, KoT:R\",\n \"artists\": [\n \"Monte Moore\"\n ],\n \"card_text\": \"Requires a justicar or Inner Circle member...\",\n \"id\": 100038,\n \"name\": \"Alastor\",\n \"ordered_sets\": [\n \"Gehenna\",\n \"Kindred Most Wanted\",\n \"Keepers of Tradition\"\n ],\n \"printed_name\": \"Alastor\",\n \"rulings\": {\n \"links\": {\n \"[ANK 20200901]\": \"http://www.vekn.net/forum/rules-questions/78830-alastor-and-ankara-citadel#100653\",\n \"[LSJ 20040518-2]\": \"https://groups.google.com/g/rec.games.trading-cards.jyhad/c/4emymfUPwAM/m/JF_o7OOoCbkJ\",\n \"[LSJ 20040518]\": \"https://groups.google.com/d/msg/rec.games.trading-cards.jyhad/4emymfUPwAM/B2SCC7L6kuMJ\"\n },\n \"text\": [\n \"If the weapon retrieved costs blood, that cost is paid by the vampire chosen by the vote. [LSJ 20040518]\",\n \"Requirements do not apply. If a discipline is required (eg. {Inscription}) and the Alastor vampire does not have it, the inferior version is used. [ANK 20200901] [LSJ 20040518-2]\"\n ]\n },\n \"scans\": {\n \"Gehenna\": \"https://static.krcg.org/card/set/gehenna/alastor.jpg\",\n \"Keepers of Tradition\": \"https://static.krcg.org/card/set/keepers-of-tradition/alastor.jpg\",\n \"Kindred Most Wanted\": \"https://static.krcg.org/card/set/kindred-most-wanted/alastor.jpg\"\n },\n \"sets\": {\n \"Gehenna\": [{ \"rarity\": \"Rare\", \"release_date\": \"2004-05-17\"}],\n \"Keepers of Tradition\": [{ \"rarity\": \"Rare\", \"release_date\": \"2008-11-19\"}],\n \"Kindred Most Wanted\": [\n {\n \"copies\": 1,\n \"precon\": \"Alastors\",\n \"release_date\": \"2005-02-21\"\n }\n ]\n },\n \"types\": [\"Political Action\"],\n \"url\": \"https://static.krcg.org/card/alastor.jpg\"\n}\n```\n\nSearch for cards by text, type, discipline, title, city, artist, set,\npreconstructed starter, group, capacity, trait, sect, bonus values, etc.:\n\n```bash\ncurl\n -X POST \"http://127.0.0.1:8000/card_search\"\n -H \"Content-Type: application/json\"\n -d \"{\\\"type\\\":[\\\"political action\\\"],\\\"sect\\\":[\\\"anarch\\\"]}\"\n```\n\n```json\n[\n \"Anarch Salon\",\n \"Eat the Rich\",\n \"Firebrand\",\n \"Free States Rant\",\n \"Patsy\",\n \"Reckless Agitation\",\n \"Revolutionary Council\",\n \"Sweeper\"\n]\n```\n\nGet candidates for your decklist out of the **TWDA**:\n\n```bash\ncurl\n -X POST \"http://127.0.0.1:8000/candidates\"\n -H \"Content-Type: application/json\"\n -d \"{\\\"cards\\\":[\\\"Cybele\\\",\\\"Nana Buruku\\\"]}\"\n```\n\n```json\n[\n {\n \"average\": 14,\n \"card\": \"Ashur Tablets\",\n \"deviation\": 6.25,\n \"score\": 1\n },\n {\n \"average\": 1,\n \"card\": \"Giant's Blood\",\n \"deviation\": 0,\n \"score\": 1\n },\n {\n \"average\": 2,\n \"card\": \"The Parthenon\",\n \"deviation\": 0.81,\n \"score\": 1\n },\n {\n \"average\": 1,\n \"card\": \"Archon Investigation\",\n \"deviation\": 0,\n \"score\": 0.9\n },\n ...\n]\n```\n\nAnd a few other features, including:\n\n- search decks in the TWDA, by cards, dates, author and number of players\n- deck list format conversion\n- retrieving a decklist from an Amaranth share URL\n- card name completions\n\nCheck the [online documentation](https://api.krcg.org/) for more.\n\n### Hosting the web API\n\nTo host the web API, you can use pip to install it:\n\n```bash\npip install \"krcg-api\"\n```\n\nNo wsgi server is installed by default, you need to install one.\nHTTP web servers can then easily be configured to serve WSGI applications,\ncheck the documentation of your web server.\n\nThe API can be served with [uWSGI](https://uwsgi-docs.readthedocs.io):\n\n```bash\nuwsgi --module krcg_api.wsgi:application\n```\n\nor [Gunicorn](https://gunicorn.org):\n\n```bash\ngunicorn krcg_api.wsgi:application\n```\n\nTwo environment variables are expected: `GITHUB_USERNAME` and `GITHUB_TOKEN`,\nto allow the API to connect to Github as a user in order to post new rulings\nas issues on the repository (`/submit-ruling` endpoint).\n\nSee the [Github help](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)\non how to generate a personal token for the account you want KRCG to use.\n\n#### Development\n\nThe development version of KRCG installs uWSGI to serve the API,\nthis is the preferred WSGI server for now.\n\n```bash\n$ pip install -e \".[dev]\"\n$ make serve\n...\nuwsgi socket 0 bound to TCP address 127.0.0.1:8000\n```\n\nYou can check the API is running by using your browser\non the provided address [http://127.0.0.1:8000](http://127.0.0.1:8000).\n\nThe environment variables `GITHUB_USERNAME` and `GITHUB_TOKEN` can be provided\nby a personal `.env` file at the root of the krcg folder (ignored by git):\n\n```bash\nexport GITHUB_USERNAME=\"dedicated_github_username_for_the_api\"\nexport GITHUB_TOKEN=\"the_matching_github_token\"\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Web API for VTES cards and TWDA",
"version": "3.1",
"project_urls": {
"Homepage": "https://api.krcg.org",
"Repository": "https://github.com/lionel-panhaleux/krcg-api"
},
"split_keywords": [
"vtes",
" vampire: the eternal struggle",
" ccg",
" twd",
" twda",
" api",
" web"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0e1f422fb17312ef6a15c9d778d9cf4baed8b1e42fff3645604817e3d4c6f892",
"md5": "05d26d2ce6be74824919be65d72d064b",
"sha256": "2d19747dd5d2f18c36d0cdf5beab321b31bec488fecf4e00b26c653f6c4b60c7"
},
"downloads": -1,
"filename": "krcg_api-3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "05d26d2ce6be74824919be65d72d064b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 25714,
"upload_time": "2024-09-15T15:35:31",
"upload_time_iso_8601": "2024-09-15T15:35:31.708564Z",
"url": "https://files.pythonhosted.org/packages/0e/1f/422fb17312ef6a15c9d778d9cf4baed8b1e42fff3645604817e3d4c6f892/krcg_api-3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2f213a06aac741cff1163a8c023d9f1b68771676415415aa2fef2bf6eecdaf6f",
"md5": "8408819a602b1fc18c7b2f2978e5c5c0",
"sha256": "84c3068ae043019fa2b36b5627ef0ee61793a00e603ea4ea5bb03110663a344d"
},
"downloads": -1,
"filename": "krcg_api-3.1.tar.gz",
"has_sig": false,
"md5_digest": "8408819a602b1fc18c7b2f2978e5c5c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 25640,
"upload_time": "2024-09-15T15:35:33",
"upload_time_iso_8601": "2024-09-15T15:35:33.516498Z",
"url": "https://files.pythonhosted.org/packages/2f/21/3a06aac741cff1163a8c023d9f1b68771676415415aa2fef2bf6eecdaf6f/krcg_api-3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-15 15:35:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lionel-panhaleux",
"github_project": "krcg-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "krcg-api"
}
JSON
