Numista API Documentation
Version: 0.14
API last update: 09 Sep 2017
Documentation last update: 09 Sep 2017

All API request should be done using HTTP protocol. Data returned in JSON format.

Available functions

Public functions
Get coin information
URL: http://qmegas.info/numista-api/coin/{coin_id}/
Some information, like coin's lettering or commemorative description still not available.
Attention! This data is cached for 30 days! In order to disable cache add force_cache=1 parameter to API request.
Function status: Partial data (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
coin_id Required ID of the coin
force_cache Optional 0 Set this to 1 in order to disable cache
Reply example on success
{
    "commemorative_description": "United States Mint's 50 State Quarters\u00ae Program",
    "country": "United States",
    "diameter": 24.26,
    "id": 631,
    "images": {
        "obverse": {
            "preview": "https:\/\/static-numista.com\/catalogue\/photos\/etats-unis\/0001.jpg",
            "fullsize": "https:\/\/static-numista.com\/catalogue\/photos\/etats-unis\/g0001.jpg"
        },
        "reverse": {
            "preview": "https:\/\/static-numista.com\/catalogue\/photos\/etats-unis\/0029.jpg",
            "fullsize": "https:\/\/static-numista.com\/catalogue\/photos\/etats-unis\/g0029.jpg"
        },
        "edge": {
            "preview": "https:\/\/static-numista.com\/catalogue\/photos\/etats-unis\/3220.jpg",
            "fullsize": "https:\/\/static-numista.com\/catalogue\/photos\/etats-unis\/g3220.jpg"
        }
    },
    "info_type": {
        "is_verified": false,
        "is_complete_year": false,
        "error": "Unknown info type"
    },
    "is_commemorative": true,
    "is_demonetized": false,
    "is_non_circulating": false,
    "is_token": false,
    "km": [
        "KM# 357",
        "Sch\u00f6n# 359"
    ],
    "metal": "Copper-nickel clad Copper",
    "orientation": "Coin alignment \u2191\u2193",
    "rarity_index": "7",
    "shape": "Round",
    "thickness": 1.75,
    "title": "\u00bc Dollar \"Washington Quarter\" Texas",
    "value": "Quarter Dollar = 25 Cents",
    "weight": 5.67,
    "years": [
        {
            "year": "2004\u00a0D",
            "mintage": "263000000",
            "remark": ""
        },
        {
            "year": "2004\u00a0P",
            "mintage": "278800000",
            "remark": ""
        },
        {
            "year": "2004\u00a0S",
            "mintage": "2740684",
            "remark": "Proof"
        }
    ],
    "years_range": "2004"
}
Reply example on error
{
    "error": "Coin not found"
}
Get list of users that want to exchange specific coin
URL: http://qmegas.info/numista-api/coin/{coin_id}/exchange/
Function status: Good (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
coin_id Required ID of the coin
Reply example on success
{
    "list": [
        {
            "year": "2004\u00a0D",
            "users": [
                {
                    "id": "11257",
                    "name": "@josephjk"
                },
                {
                    "id": "44197",
                    "name": "aragorn1980"
                },
                {
                    "id": "40112",
                    "name": "AU24K"
                }
            ]
        },
        {
            "year": "2004\u00a0P",
            "users": [
                {
                    "id": "16059",
                    "name": "abeilleecureuil"
                },
                {
                    "id": "11323",
                    "name": "acx"
                },
                {
                    "id": "10522",
                    "name": "AlainJ"
                },
                {
                    "id": "46598",
                    "name": "AmerSalmeh"
                }
            ]
        }
    ],
    "id": 631
}
Get list of countries
URL: http://qmegas.info/numista-api/country/list/
Receive list of available countries
Function status: Good (Function doesn't work? Report it!)
Reply example on success
{
    "countries": [
        {
            "id": "afghanistan",
            "name": "Afghanistan"
        },
        {
            "id": "albanie",
            "name": "Albania"
        },
        {
            "id": "aurigny",
            "name": "Alderney"
        }
    ]
}
Get list of coins for specific country
URL: http://qmegas.info/numista-api/country/{country_id}/coins/
Function status: Good (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
limit Optional 10 Coins per page. Value from 10 to 1000
page Optional 1 Current page
filter_circulating Optional 1 Defines if show circulating coins
filter_non_circulating Optional 1 Defines if show non circulating coins
filter_tokens Optional 0 Defines if show tokens
filter_trial_strikes Optional 0 Defines if show trial strikes coins
filter_euro Optional 1 Defines if show euro coins
Reply example on success
{
    "total_coins": 54,
    "list": [
        {
            "image": {
                "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/50.jpg",
                "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/51.jpg"
            },
            "id": 5589,
            "name": "5 Cents - Beatrix (magnetic)"
        },
        {
            "image": {
                "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/52.jpg",
                "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/53.jpg"
            },
            "id": 5349,
            "name": "10 Cents - Beatrix (magnetic)"
        },
        {
            "image": {
                "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/186.jpg",
                "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/187.jpg"
            },
            "id": 902,
            "name": "25 Cents - Beatrix \/ Willem Alexander(magnetic)"
        },
        {
            "image": {
                "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/58.jpg",
                "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/59.jpg"
            },
            "id": 6840,
            "name": "50 Cents - Beatrix (magnetic)"
        },
        {
            "image": {
                "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/177.jpg",
                "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/178.jpg"
            },
            "id": 6433,
            "name": "1 Florin - Beatrix (magnetic)"
        },
        {
            "image": {
                "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/161.jpg",
                "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/162.jpg"
            },
            "id": 67081,
            "name": "1 Florin - Willem-Alexander"
        },
        {
            "image": {
                "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/191.jpg",
                "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/188.jpg"
            },
            "id": 7698,
            "name": "2\u00bd Florin - Beatrix (magnetic)"
        },
        {
            "image": {
                "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/192.jpg",
                "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/193.jpg"
            },
            "id": 70652,
            "name": "2\u00bd Florin - Willem-Alexander (magnetic)"
        },
        {
            "image": {
                "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/189.jpg",
                "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/190.jpg"
            },
            "id": 9340,
            "name": "5 Florin - Beatrix (magnetic)"
        },
        {
            "image": {
                "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/137.jpg",
                "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/aruba\/138.jpg"
            },
            "id": 10214,
            "name": "5 Florin - Beatrix (50 Years Charter for Kingdom)"
        }
    ],
    "country": "aruba",
    "pages": {
        "current": 1,
        "max": 6
    },
    "filter": {
        "circulating": true,
        "non_circulating": true,
        "tokens": false,
        "trial_strikes": false,
        "euro": true
    }
}
Reply example on error
{
    "error": "Wrong page"
}
Get user information
URL: http://qmegas.info/numista-api/user/{user_id}/
Attention! This data is cached for 30 days! In order to disable cache add force_cache=1 parameter to API request.
Function status: Good (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
user_id Required ID of the user
force_cache Optional 0 Set this to 1 in order to disable cache
Reply example on success
{
    "collection": {
        "coins_count": 4099,
        "countries_count": 195
    },
    "exchange_coins_count": 790,
    "feedback": {
        "count": 33,
        "average": 10
    },
    "forum_posts_count": 3060,
    "id": 2,
    "image": "https:\/\/static-numista.com\/forum\/avatars\/20002403351640d537b85a.png",
    "is_collection_visible": true,
    "is_exchange_coins_visible": false,
    "languages": [
        "French",
        "Chinese",
        "English"
    ],
    "location": "Antibes, France",
    "member_since": "16-Jan-2007",
    "name": "Xavier",
    "special_status": "Creator and main administrator of Numista",
    "swaps_on_road": 0,
    "user_notes": {
        "collects": "",
        "wants": ""
    }
}
Reply example on error
{
    "error": "User not found"
}
Get user feedbacks
URL: http://qmegas.info/numista-api/user/{user_id}/feedbacks/
Function status: Good (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
user_id Required ID of the user
Reply example on success
{
    "feedback": {
        "count": 33,
        "average": 10
    },
    "list": [
        {
            "rating": 5,
            "user": {
                "id": 6673,
                "name": "solo"
            },
            "date": "11-Feb-2011",
            "comment": "Lot bien re\u00e7u, merci \u00e0 vous,echange excellent.Au plaisir."
        },
        {
            "rating": 5,
            "user": {
                "id": 5265,
                "name": "darinrase"
            },
            "date": "10-Dec-2010",
            "comment": "Excellent Trade with Xavier."
        },
        {
            "rating": 5,
            "user": {
                "id": 1723,
                "name": "AHICOR"
            },
            "date": "23-Nov-2010",
            "comment": "UN ECHANGE PARFAIT. UNE LIVRAISON RAPIDE. UN ENVOI SOIGNE. TOUT PARFAIT QUOI\u00a0!! :)))) AU PROCHAIN..."
        },
        {
            "rating": 5,
            "user": {
                "id": 4310,
                "name": "adriarth"
            },
            "date": "23-Nov-2010",
            "comment": "ECHANGE PARFAIT A TOUT POINT DE VU"
        },
        {
            "rating": 5,
            "user": {
                "id": 2035,
                "name": "madatet"
            },
            "date": "5-Nov-2010",
            "comment": "Troisi\u00e8me \u00e9change au top avec Xavier... j'ai m\u00eame re\u00e7u des cadeaux... :)\r\nNe change rien, la perfection \u00e0 tous les niveaux... A tr\u00e8s bientot pour le prochain... ++ Julien"
        },
        {
            "rating": 5,
            "user": {
                "id": 3427,
                "name": "monet"
            },
            "date": "26-Oct-2010",
            "comment": "echange de tres grande qualite, pres pour le suivant."
        },
        {
            "rating": 5,
            "user": {
                "id": 2182,
                "name": "kommodore"
            },
            "date": "6-Oct-2010",
            "comment": "GOOD EXCHANGE"
        },
        {
            "rating": 5,
            "user": {
                "id": 1862,
                "name": "tichat40"
            },
            "date": "2-Jun-2010",
            "comment": "Enfin un 1er \u00e9change avec le boss\u00a0!! super contente de mes nouvelles acquisitions. On recommence quand tu veux\u00a0!"
        },
        {
            "rating": 5,
            "user": {
                "id": 2035,
                "name": "madatet"
            },
            "date": "1-Jun-2010",
            "comment": "Deuxi\u00e8me \u00e9change avec Xavier, RAS, perfection \u00e0 tous les niveaux... et les enveloppes avec le Logo Numista dessus, \u00e7a d\u00e9chire... :)\r\nEncore merci \u00e0 toi pour ton oeuvre qui nous permet \u00e0 tous de passer de supers moments... A tr\u00e8s bientot, ++ Julien"
        },
        {
            "rating": 5,
            "user": {
                "id": 781,
                "name": "roberchan"
            },
            "date": "22-May-2010",
            "comment": "Premier \"\u00e9change \" officiel\u00a0! Sans probl\u00e8me. J'ai admir\u00e9 la simplicit\u00e9 de l'emballage autant que son efficacit\u00e9."
        }
    ],
    "id": 2
}
Reply example on error
{
    "error": "User not found"
}
Get exchange coins of the user
URL: http://qmegas.info/numista-api/user/{user_id}/exchange/
Function status: Good (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
user_id Required ID of the user
Reply example on success
{
    "summary": {
        "total_coins": 790,
        "total_countries": 54,
        "different_types": 278
    },
    "list": [
        {
            "id": 797,
            "name": "20 Francs",
            "country_name": "Algeria",
            "km": "KM# 91",
            "year": "1949",
            "count": 3
        },
        {
            "id": 1755,
            "name": "100 Francs",
            "country_name": "Algeria",
            "km": "KM# 93",
            "year": "1952",
            "count": 1
        },
        {
            "id": 2925,
            "name": "50 Centimes",
            "country_name": "Algeria",
            "km": "KM# 102",
            "year": "1973",
            "count": 1
        },
        {
            "id": 2220,
            "name": "2 Centavos",
            "country_name": "Argentina",
            "km": "KM# 33",
            "year": "1892",
            "count": 1
        },
        {
            "id": 5229,
            "name": "10 Pesos",
            "country_name": "Argentina",
            "km": "KM# 72",
            "year": "1976",
            "count": 1
        },
        {
            "id": 2214,
            "name": "10 Centavos (reeded edge; non-magnetic)",
            "country_name": "Argentina",
            "km": "KM# 107",
            "year": "1992",
            "count": 1
        },
        {
            "id": 2214,
            "name": "10 Centavos (reeded edge; non-magnetic)",
            "country_name": "Argentina",
            "km": "KM# 107",
            "year": "2004",
            "count": 1
        }
    ]
}
Get collection coins of the user
URL: http://qmegas.info/numista-api/user/{user_id}/collection/
Receive list of user's coins (only if available)
Function status: Good (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
user_id Required ID of the user
page Optional 1 Current page
filter_country Optional null Filter coins by country ID
Reply example on success
{
    "list": [
        {
            "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/tokens\/18098.jpg",
            "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/tokens\/18099.jpg",
            "name": "0.02 Lipe (Lipa Holding, Ljubljana Series)",
            "km": "X# Tn5",
            "country_name": "* Tokens * (Slovenia)",
            "id": 2147,
            "years": [
                {
                    "year": "1992",
                    "vg": 0,
                    "f": 0,
                    "vf": 1,
                    "xf": 0,
                    "unc": 0,
                    "exchange": 0
                }
            ]
        },
        {
            "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/tokens\/35582.jpg",
            "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/tokens\/35583.jpg",
            "name": "Denver Mint Token",
            "km": "",
            "country_name": "* Tokens * (United States)",
            "id": 45408,
            "years": [
                {
                    "year": "1970",
                    "vg": 0,
                    "f": 1,
                    "vf": 0,
                    "xf": 0,
                    "unc": 0,
                    "exchange": 0
                }
            ]
        },
        {
            "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/exonumia\/2487.jpg",
            "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/exonumia\/2488.jpg",
            "name": "1 ECU (European Union)",
            "km": "X# 145",
            "country_name": "** Exonumia ** (ECU & Pre 1999 Euro)",
            "id": 6328,
            "years": [
                {
                    "year": "1984",
                    "vg": 0,
                    "f": 0,
                    "vf": 0,
                    "xf": 0,
                    "unc": 1,
                    "exchange": 0
                }
            ]
        },
        {
            "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/afghanistan\/258.jpg",
            "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/afghanistan\/259.jpg",
            "name": "Ashrafi - Ahmad",
            "km": "KM# 639",
            "country_name": "Afghanistan",
            "id": 36968,
            "years": [
                {
                    "year": "116\u00a0(1754)",
                    "vg": 0,
                    "f": 0,
                    "vf": 0,
                    "xf": 0,
                    "unc": 0,
                    "exchange": 0
                }
            ]
        }
    ],
    "pages": {
        "current": 1,
        "max": 66
    },
    "filter": {
        "country": null
    }
}
Reply example on error
{
    "error": "User doesn't want to display his collection"
}
Private functions
Authorize yourself in order to receive access to private functions
URL: http://qmegas.info/numista-api/authorize/
Access token will be provided if authorization is successful.
Attention: We guarantee that your Numista login and password will NOT be stored or transferred to any third party. Anyway, use of that function on your own risk only.
Function status: Good (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
login Required Numista login
password Required Numista password
Reply example on success
{
    "access_token": "05e50faa92b979516c5fd0405ac6c2ca51b2ce26"
}
Reply example on error
{
    "error": "Wrong login or password"
}
Destroy authorization token (logout)
URL: http://qmegas.info/numista-api/authorize/destroy/
Function status: Good (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
access_token Required Access token received from "authorize" function
Reply example on success
{
    "destroyed": true
}
Get list of your own coins
URL: http://qmegas.info/numista-api/coins/mine/
Function status: Good (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
access_token Required Access token received from "authorize" function
page Optional 1 Current page
filter_country Optional null Filter coins by country ID
Reply example on success
{
    "list": [
        {
            "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/tokens\/18098.jpg",
            "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/tokens\/18099.jpg",
            "name": "0.02 Lipe (Lipa Holding, Ljubljana Series)",
            "km": "X# Tn5",
            "country_name": "* Tokens * (Slovenia)",
            "id": 2147,
            "years": [
                {
                    "year": "1992",
                    "vg": 0,
                    "f": 0,
                    "vf": 1,
                    "xf": 0,
                    "unc": 0,
                    "exchange": 0
                }
            ]
        },
        {
            "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/tokens\/35582.jpg",
            "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/tokens\/35583.jpg",
            "name": "Denver Mint Token",
            "km": "",
            "country_name": "* Tokens * (United States)",
            "id": 45408,
            "years": [
                {
                    "year": "1970",
                    "vg": 0,
                    "f": 1,
                    "vf": 0,
                    "xf": 0,
                    "unc": 0,
                    "exchange": 0
                }
            ]
        },
        {
            "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/exonumia\/2487.jpg",
            "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/exonumia\/2488.jpg",
            "name": "1 ECU (European Union)",
            "km": "X# 145",
            "country_name": "** Exonumia ** (ECU & Pre 1999 Euro)",
            "id": 6328,
            "years": [
                {
                    "year": "1984",
                    "vg": 0,
                    "f": 0,
                    "vf": 0,
                    "xf": 0,
                    "unc": 1,
                    "exchange": 0
                }
            ]
        },
        {
            "obverse": "https:\/\/static-numista.com\/catalogue\/photos\/afghanistan\/258.jpg",
            "reverse": "https:\/\/static-numista.com\/catalogue\/photos\/afghanistan\/259.jpg",
            "name": "Ashrafi - Ahmad",
            "km": "KM# 639",
            "country_name": "Afghanistan",
            "id": 36968,
            "years": [
                {
                    "year": "116\u00a0(1754)",
                    "vg": 0,
                    "f": 0,
                    "vf": 0,
                    "xf": 0,
                    "unc": 0,
                    "exchange": 0
                }
            ]
        }
    ],
    "pages": {
        "current": 1,
        "max": 66
    },
    "filter": {
        "country": null
    }
}
Reply example on error
{
    "error": "Wrong access token"
}
Get inbox messages
URL: http://qmegas.info/numista-api/messages/inbox/
Function status: Good (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
access_token Required Access token received from "authorize" function
filter_new Optional 0 When set to 1 return only unread messages
Reply example on success
{
    "messages": [
        {
            "id": 1234,
            "is_replied": false,
            "is_new": false,
            "title": "Re: Echange",
            "sender": {
                "id": 1,
                "name": "Xavier"
            },
            "time": "5-Sep-2017 12:33AM"
        },
        {
            "id": 12345,
            "is_replied": true,
            "is_new": true,
            "title": "Re: Echange",
            "sender": {
                "id": 39128,
                "name": "Megas"
            },
            "time": "1-Sep-2017 03:34PM"
        }
    ],
    "filter": {
        "new": false
    }
}
Reply example on error
{
    "error": "Wrong access token"
}
Get outbox messages
URL: http://qmegas.info/numista-api/messages/outbox/
Function status: Good (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
access_token Required Access token received from "authorize" function
filter_unread Optional 0 When set to 1 return only unread messages
Reply example on success
{
    "messages": [
        {
            "id": 1234,
            "is_unread": false,
            "title": "Re: Echange",
            "recipient": {
                "id": 1,
                "name": "Xavier"
            },
            "time": "5-Sep-2017 12:33AM"
        },
        {
            "id": 12345,
            "is_unread": true,
            "title": "Re: Echange",
            "recipient": {
                "id": 39128,
                "name": "Megas"
            },
            "time": "1-Sep-2017 03:34PM"
        }
    ],
    "filter": {
        "unread": false
    }
}
Reply example on error
{
    "error": "Wrong access token"
}
Read message
URL: http://qmegas.info/numista-api/messages/read/
Function status: Good (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
access_token Required Access token received from "authorize" function
id Required Message ID
user_id Required Recipient or sender ID
Reply example on success
{
    "id": 12345,
    "message": "Hi All!",
    "author": {
        "id": 39128,
        "name": "Megas"
    },
    "time": "September 9, 2017, 01:50PM",
    "title": "Hello"
}
Reply example on error
{
    "error": "Message not found"
}

Roadmap

+ Adding SSL version of the API
+ Adding ability to search

Version info

0.14
+ Added ability to list and to read messages in inbox and outbox
0.13
* New coin type parameter
0.12
* Many bugs fixed due to different Numista design changes
* New API documentation page
0.11.1
+ Coin's info function return commemorative description and token flag
0.10
+ Coin's info function return sub country
0.09
* API returns error if trying to display info of unpublished coin
0.08
* In coin's data the reference number is now an array
0.07
+ Added caching for some of the functions
0.06
+ Added support for "No rating" in user's feedback
+ Added support for replies in user's feedback
0.05
+ Added "Get list of your own coins" functions
0.03
+ Added "Get user's exchange coins" functions
+ Added "Get user's coins" functions
0.02
+ Added "Get list of coins for specific country" functions
* Country list function output changed
0.01
+ Added first few functions

Known bugs

* Function "Get list of users that want to exchange this coin" can't retrieve users that have space symbol in their name.