Numista API Documentation

This is a documentation for unofficial Numista API. Lately official API was anounced, thus some of functions will be not supported any more (it won't be fixed if some design changes will occur on Numista), but it still continue working.

Version: 0.22
API last update: 16 May 2019
Documentation last update: 26 Feb 2019

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

Available functions

Public functions
Get coin information* Deprecated, use official API
URL: https://qmegas.info/numista-api/coin/
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: Good (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 Program",
    "country": DEPRECATED: use country.name instead,
    "country": {
        "id": "etats-unis",
        "name": "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"
        },
        "copyright": ""
    },
    "is_commemorative": true,
    "is_demonetized": false,
    "is_non_circulating": false,
    "is_token": false,
    "km": [
        "KM# 357",
        "Schon# 359"
    ],
    "metal": "Copper-nickel clad Copper",
    "orientation": "Coin alignment \u2191\u2193",
    "rarity_index": "7",
    "shape": "Round",
    "thickness": 1.75,
    "title": "Dollar \"Washington Quarter\" Texas",
    "value": "Quarter Dollar = 25 Cents",
    "weight": 5.67,
    "years": [
        {
            "year": "2004",
            "mintage": "263000000",
            "remark": ""
        },
        {
            "year": "2004",
            "mintage": "278800000",
            "remark": ""
        },
        {
            "year": "2004",
            "mintage": "2740684",
            "remark": "Proof"
        }
    ],
    "years_range": "2004"
}
Reply example on error
{
    "error": "Coin not found"
}
Get coin prices
URL: https://qmegas.info/numista-api/coin/prices/
Coin sell prices on different platforms (like eBay)
The reply of that function is cached for 30 days and it's not possible to disable it.
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
{
    "prices": [
        {
            "min": 0.11,
            "max": 71.54,
            "count": 82,
            "average": 8.41,
            "median": 4.68,
            "id": 1,
            "year": "all"
        }
    ]
}
Reply example on error
{
    "error": "Coin not found"
}
Get list of users that want to exchange specific coin
URL: https://qmegas.info/numista-api/coin/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",
            "users": [
                {
                    "id": 11257,
                    "name": "@josephjk",
                    "feedback": {
                        "rating": 5,
                        "count": 36
                    },
                    "country": {
                        "name": "Lithuania"
                    },
                    "languages": [
                        "English",
                        "Lithuanian"
                    ]
                }
            ]
        },
        {
            "year": "2005",
            "users": [
                {
                    "id": 16059,
                    "name": "abeilleecureuil",
                    "feedback": {
                        "rating": 4,
                        "count": 12
                    },
                    "country": {
                        "name": "Latvia"
                    },
                    "languages": [
                        "English"
                    ]
                },
                {
                    "id": 11323,
                    "name": "acx",
                    "feedback": {
                        "rating": 5,
                        "count": 1
                    },
                    "country": {
                        "name": "Netherlands"
                    },
                    "languages": [
                        "English"
                    ]
                }
            ]
        }
    ],
    "id": 631
}
Get list of countries
URL: https://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: https://qmegas.info/numista-api/country/coins/
Function status: Good (Function doesn't work? Report it!)
Parameters
Parameter name Type Default value Description
country_id Required Country ID
limit Optional 10 Coins per page. Value from 10 to 1000
page Optional 1 Current page
filter_common Optional 1 Defines if show common coins
filter_circulating_comm Optional 1 Defines if show circulating commemorative coins
filter_non_circulating Optional 1 Defines if show non circulating coins
filter_tokens Optional 0 Defines if show tokens
filter_pattern Optional 0 Defines if show pattern 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)"
        }
    ],
    "country": "aruba",
    "pages": {
        "current": 1,
        "max": 6
    },
    "filter": {
        "common": true,
        "circulating_comm": true,
        "non_circulating": true,
        "tokens": false,
        "pattern": false,
        "euro": true
    }
}
Reply example on error
{
    "error": "Wrong page"
}
Get user information
URL: https://qmegas.info/numista-api/user/
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: https://qmegas.info/numista-api/user/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"
        }
    ],
    "id": 2
}
Reply example on error
{
    "error": "User not found"
}
Get exchange coins of the user
URL: https://qmegas.info/numista-api/user/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": DEPRECATED: use country.name instead,
            "country": {
                "name": "Algeria"
            },
            "km": "KM# 91",
            "year": "1949",
            "count": 3
        },
        {
            "id": 1755,
            "name": "100 Francs",
            "country_name": DEPRECATED: use country.name instead,
            "country": {
                "name": "Algeria"
            },
            "km": "KM# 93",
            "year": "1952",
            "count": 1
        },
        {
            "id": 2220,
            "name": "2 Centavos",
            "country_name": DEPRECATED: use country.name instead,
            "country": {
                "name": "Argentina"
            },
            "km": "KM# 33",
            "year": "1892",
            "count": 1
        }
    ]
}
Get collection coins of the user
URL: https://qmegas.info/numista-api/user/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": DEPRECATED: use country.name instead,
            "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": DEPRECATED: use country.name instead,
            "country": {
                "name": "* Tokens * (United States)"
            },
            "id": 45408,
            "years": [
                {
                    "year": "1970",
                    "vg": 0,
                    "f": 1,
                    "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: https://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",
    "user_id": 1234
}
Reply example on error
{
    "error": "Wrong login or password"
}
Destroy authorization token (logout)
URL: https://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: https://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
                }
            ]
        }
    ],
    "pages": {
        "current": 1,
        "max": 66
    },
    "filter": {
        "country": null
    }
}
Reply example on error
{
    "error": "Wrong access token"
}
Get inbox messages
URL: https://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: https://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: https://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

+ Ability to view wish list
+ Ability to view swaps

Version info

0.22
* Fixed serious bug in coin's prices
0.21
* Added user_id parameter into authorization reply
0.20
* New filter parameters for function "Get list of coins for specific country"
0.19
* Parameter country in coin's information changed to return both name and country ID
* Few small documentation fixes
0.18
* Due to Numista latest design changes many broken API parameters are fixed.
- Removed info_type from coin information. This parameter not used any more on Numista.
+ Added copyright information to images object in coins information.
+ Updated result of function "list of users that want to exchange specific coin". Added more info about the user, like: feedback rating, country and spoken languages.
* Parameter country_name in user's exchange/collection lists is deprecated and will be removed from API output in few months. Use new country parameter instead (see example output in docs).
0.17
* Why no one send me a message that authorization function doesn't work for a long time?
  Anyway, it fixed.
0.16
+ Coin price function
+ Added SSL support. Now it's possible ot call API functions via HTTPS protocol
* Step by step I'm removing usage of parameters inside function URL, however backward compatibility is supported.
0.15
* Fixed country list
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.