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.
API last update: 19 Oct 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.
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.
The reply of that function is cached for 30 days and it's not possible to disable 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/
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
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/
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.
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/
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/
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)
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.
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.
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/
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/
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/
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/
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/
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 list0.14
+ Added ability to list and to read messages in inbox and outbox0.13
* New coin type parameter0.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 flag0.10
+ Coin's info function return sub country0.09
* API returns error if trying to display info of unpublished coin0.08
* In coin's data the reference number is now an array0.07
+ Added caching for some of the functions0.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