Numista API - Megas Homepage

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.28
API last update: 16 May 2020
Documentation last update: 16 May 2020

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",
            "frequency": "0%",
            "remark": ""
        },
        {
            "year": "2004",
            "mintage": "278800000",
            "frequency": "10%",
            "remark": ""
        },
        {
            "year": "2004",
            "mintage": "2740684",
            "frequency": "17%",
            "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* Deprecated, use official API

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	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.28

+ Added frequency info to coin's year
* Overall parsing improvement
* Fixed coin's demonetization info

0.27

* Fixed country coins items
* Fixed country list

0.26

* Fixed country coins total items

0.25

* Fixed user's language info

0.24

* Fixed cache forcing
+ Added commemorative series info

0.23

* Fixed authorization function

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.