{"id":15896259,"url":"https://github.com/numberoverzero/finder","last_synced_at":"2025-04-02T18:26:01.240Z","repository":{"id":142803949,"uuid":"10569161","full_name":"numberoverzero/finder","owner":"numberoverzero","description":"Search API for MtG cards - Feature parity with Gatherer","archived":false,"fork":false,"pushed_at":"2013-08-22T06:49:55.000Z","size":204,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-08T09:12:23.129Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/numberoverzero.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-06-08T13:58:45.000Z","updated_at":"2014-04-22T20:28:44.000Z","dependencies_parsed_at":"2023-03-15T04:35:36.839Z","dependency_job_id":null,"html_url":"https://github.com/numberoverzero/finder","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numberoverzero%2Ffinder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numberoverzero%2Ffinder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numberoverzero%2Ffinder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numberoverzero%2Ffinder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/numberoverzero","download_url":"https://codeload.github.com/numberoverzero/finder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246867800,"owners_count":20846819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-06T09:07:17.157Z","updated_at":"2025-04-02T18:26:01.206Z","avatar_url":"https://github.com/numberoverzero.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Finder\n=========================================\n\nFinder is a web service that aims for near parity with magiccards.info search features.\n\nFeatures:\n\n*   **Custom data hydration** Why load artist name or collector's number if you don't use them?  Specify the attributes you want filled.\n\n*   **Paginated APIs** - Unless you like everything at once.  That's fine too.  *(Not included in initial release)*\n\n*   **Small footprint** - All card data fits in a single ~16MB sqlite db, so you can easily download updated databases as new sets come out.\n\n*   **Batteries included** - Want to do your own updates?  Includes scripts to add proper comparable fields to a gatherer scrape, such as cmc and integer power/toughness fields.  Full database translation in less than 15 seconds.\n\nAPI\n=========================================\n\nSession Key Generation\n-----------------------------------------\n::\n\n/[APIKEY]/generate?duration=[SECONDS]\n\nSession Keys allow you to embed calls to finder in your website without exposing your account API key.\nWhen generating session keys, you can specify a custom key duration in seconds.  The default is 300 seconds (5 minutes).\n\n\nSearching\n-----------------------------------------\n\nCard queries are passed as json in the body, result settings in the querystring.\n\n* (optional) ``fields`` is a comma-delimited list of card attributes to include in the results, such as ``fields=name,colors,cmc``.  Defaults to all fields.\n\n* (optional) ``remove_dupes`` is a boolean to remove duplicate cards by name from results.  If true, this keeps only one instance of the newest printing of a card.  Default is true.\n\nURI::\n\n    /[SESSIONKEY]/search?fields=[RESULTFIELDS]\u0026remove_dupes=true\n\n\nLet's find cards that have between 4 and 6 power (inclusive), cmc of 3 or less, and are multicolored.\nWe only want the newest printing, and we only want name, id, and mana cost back::\n\n    /[SESSIONKEY]/search?fields=name,id,mana\u0026remove_dupes=true\n\n    {\n        \"AND\": [\n            \"power\": \"\u003e=4\",\n            \"power\": \"\u003c=6\",\n            \"cmc\": \"\u003c=3\",\n            \"colors\": [\"multi\"]\n        ]\n    }\n\n\nThis can be compacted a bit, by using short names and color values::\n\n    {\n        \"AND\": [\n            \"pow\": \"\u003e=4\",\n            \"pow\": \"\u003c=6\",\n            \"cmc\": \"\u003c=3\",\n            \"c\": [\"m\"]\n        ]\n    }\n\nNote that the top-level AND is required - otherwise we would have two \"pow\" keys in the top-level object, which is invalid.\nThis is required for all queries, even if the keys are unique.\n\nSearch: Logical operators\n-----------------------------------------\n\nThere are three supported logical operators: ``AND``, ``OR``, and ``NOT``.  Both ``AND`` and ``OR`` must be an array,\nwhere each element is either a field:value pair or another logical operator.\n``NOT`` is an object with a single element - any NOT object with more than one key:value pair will make the query invalid.\n\nFinally, note that logical operators CANNOT be the value for a card field - ``\"name\": { \"OR\": [\"Foo\", \"Bar\"]}`` is invalid.\n\n::\n\n    {\n        \"AND\": [\n            \"OR\": [\n                \"name\": \"Foo\",\n                \"name\": \"Bar\",\n            ],\n\n            \"AND\": [\n                \"type\": \"Creature\",\n                \"OR\": [\n                    \"pow\": \"\u003c5\",\n                    \"tou\": \"\u003c5\"\n                ]\n            ],\n\n            \"NOT\": {\n                \"set\": \"Return To Ravnica\"\n            }\n        ]\n    }\n\n\n\nSearch: Nesting operators\n-----------------------------------------\n\nThe operators ``AND``, ``OR``, and ``NOT`` can be nested to create complex queries.\nSuppose we want all creatures with cmc 3 or less, and the cards must either be blue only, or at least red and white::\n\n    {\n        \"AND\": [\n            \"cmc\": \"\u003c=3\",\n            \"type\": \"Creature\",\n            \"OR\": [\n                \"color\": [\"strict\", \"blue\"],\n                \"color\": [\"red\", \"white\", \"multi\"]\n            ]\n        ]\n    }\n\nThe minimum criteria is our first two and values: it must have cmc \u003c=3, and type \"Creature\".  Then, it can match one of\ntwo criteria: either be exclusively blue, or have at least the two colors red and white.  Note that the second option\nis expressed as red/white/multi, since red/white alone allows mono-red and mono-white.\n\nHere's the compacted version::\n\n    {\n        \"AND\": [\n            \"cmc\": \"\u003c=3\",\n            \"t\": \"Creature\",\n            \"OR\": [\n                \"c\": [\"!\", \"u\"],\n                \"c\": [\"r\", \"w\", \"m\"]\n            ]\n        ]\n    }\n\nSearch: Field keys and formats\n-----------------------------------------\n\nNumeric fields can use any of the following six operators::\n\n    ==  !=  \u003c  \u003e  \u003c=  \u003e=\n\nStrings always compare ignoring case, and non-ascii characters are replaced with their closest ascii values (mostly\nremoving combining characters such as accents).  The only (optional) string operator is \"!\" which forces a strict\nmatch - \"!Foo\" will not match \"FooBar\" or \"MyFoo\".  String comparison defaults to non-strict matching\n(so \"foo\" will match \"my foo\").\n\nExamples:\n\n* ``\"artist\": \"John\"`` would match both \"John Von Bear\" and \"Green Johnman\"\n\n* ``\"id\": \"\u003e=56123\"`` would match any cards with multiverse id 56123 and up.\n\n* ``\"name\": \"\u0026\"`` is a partial search on the name \"\u0026\" which will find cards including `\"Look at me, I'm R\u0026D\" \u003chttp://gatherer.wizards.com/Pages/Card/Details.aspx?multiverseid=74360\u003e`_.\n\nIn the following table, type is with respect to which operators it allows.\nNote that all values must be passed as strings, even numeric fields such as id or power\n(because they require an operator)\n\n+----------+----------+----------+----------+----------+----------+\n|Field     |Short Name|Type      |Field     |Short Name|Type      |\n+==========+==========+==========+==========+==========+==========+\n|id        |id        | numeric  |flavor    |fla       | string   |\n+----------+----------+----------+----------+----------+----------+\n|name      |n         | string   |watermark |wat       | string   |\n+----------+----------+----------+----------+----------+----------+\n|type      |t         | string   |number    |num       | numeric  |\n+----------+----------+----------+----------+----------+----------+\n|set       |s         | string   |artist    |a         | string   |\n+----------+----------+----------+----------+----------+----------+\n|rarity    |r         | string   |rulings   |rul       | string   |\n+----------+----------+----------+----------+----------+----------+\n|power     |pow       | numeric  |cmc       |cmc       | numeric  |\n+----------+----------+----------+----------+----------+----------+\n|toughness |tou       | numeric  |colors    |c         | array    |\n+----------+----------+----------+----------+----------+----------+\n|rules     |o         | string   |loyalty   |lo        | numeric  |\n+----------+----------+----------+----------+----------+----------+\n|format    |f         | string   |          |          |          |\n+----------+----------+----------+----------+----------+----------+\n\nSearch: Special field keys\n-----------------------------------------\n\n``colors`` is an array of strings.  Each element is either a single character, or the full name, such as \"w\" or \"white\".\n\n* Case insensitive.\n\n* Order isn't important.\n\n* Duplicate values are redundant.\n\n+----------+----------+\n|Name      |Short Name|\n+==========+==========+\n|white     |w         |\n+----------+----------+\n|blue      |u         |\n+----------+----------+\n|black     |b         |\n+----------+----------+\n|red       |r         |\n+----------+----------+\n|green     |g         |\n+----------+----------+\n|multi     |m         |\n+----------+----------+\n|land      |l         |\n+----------+----------+\n|colorless |c         |\n+----------+----------+\n|strict    |!         |\n+----------+----------+\n\n\nThe following returns cards that contain at least blue or at least white::\n\n    {\n        \"AND\": [\n            \"color\": [\n                \"blue\",\n                \"white\"\n            ]\n        ]\n    }\n\nThe following returns cards that contain blue, white, or blue and white (and no other colors)::\n\n    {\n        \"AND\": [\n            \"color\": [\n                \"blue\",\n                \"white\",\n                \"strict\"\n            ]\n        ]\n    }\n\nFinally, the following returns cards that contain both blue and white, and no other colors::\n\n    {\n        \"AND\": [\n            \"color\": [\n                \"blue\",\n                \"white\",\n                \"strict\",\n                \"multi\"\n            ]\n        ]\n    }\n\nSearch Results: As-printed fields\n-----------------------------------------\n\nSome fields such as name, power, toughness are simplified in order to make searching easier\n(such as allowing ascii replacements for non-ascii characters - try search?q=name:aether for an example).\nHowever, many users would like to access the card's printed values as well as the computed values.\nTherefore these fields are available by their computed name (the same used to search) as well as the original\nprinted value, available as ``printed_[FIELD]``.  Currently the additional result fields are:\n\n* ``printed_name``\n\n* ``printed_power``\n\n* ``printed_toughness``\n\n* ``printed_cost`` even though there's no ``cost``.  The goal is to make it clear that the original printing of the cost is a string and can contain, for example, ``{2/g}`` as a representation for a split cost.\n\n* ``formats`` - formats that the card is legal in\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumberoverzero%2Ffinder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnumberoverzero%2Ffinder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumberoverzero%2Ffinder/lists"}