The most up to date reference on World Coin Values

Home Page Coin Encylopedia Developers  

Coin Data API

The data API is located at data.numistip.com and provides information such as mintages, compositions, weights, photos and descriptions of catalogued coins and enables searching and filtering of catalogued coins.

Basics

Coins are catalogued defined by a single numerical number, when working with the NumisTip API, it helps to record this ID number in your own database to refer to specific coins as this number never changes. There are tools such as Javascript form objects available at the bottom of this page to assist in integrating ways of obtaining this number into your website.

Any request made to the data API can be made via a HTTPS request to the following URL: https://data.numistip.com/ This is followed by the function name, then a question mark, then the args in the format argname=value Each separated by the ampersand (&) symbol. Argument names are case sensitive.

Search

The search command is used for both searching for coins through keywords and filtering results by particular fields. It is called with the search function: https://data.numistip.com/search It takes the following arguments:

Argument Data Type Remarks
q string This is the main query string, it takes a boolean logic filter string with the following characteristics.
Order of operations are enforced with braces, { and }
Equalities are specified with =, or ~ for a non-case sensitive equality.
Inequalities are not supported.
The AND operator is +
The OR operator is |
The wildcard operator * can be added at the front or rear of a string.
Strings which have key character must be surronded by single or double quotes.
sort optional string This indicates how you want the results sorted with each sortable field in order of preference separated by a comma and a space then DESC added after a field name to indicate that it is to be sorted in reverse.
lang optional string The lang argument indicates the language you wish to search in, leaving this blank only searches the default language for each coin, adding a language here additionally searches the specified language version if available.
startAt optional integer This specifies which result number you want to start at, the first result is 0.
count optional integer This specifies how many results to display. For low latency requirements such as automatically updating lists, it is recommended that this be set low (5-20) to ensure good performance. For general use we recommend results of between 20 to 100.

For example if we wanted to search for proof coins with the reverse designed by George Kruger Gray and dated 1939 or 1999), the q field would be:

ReverseDesigner=*"Kruger%20Gray"+{Year=1939|Year=1999}+Prefix=PR

We put the wildcard character before Kruger Gray as his name may be specified as George Kruger Gray and we put the two dates in brackets with an OR conditional symbol (|) in between as this needs to be processed first.

If we want the newest coins first, we'd use the sort string:

Year DESC

We can safely leave the rest of the fields out for the final request to be:

https://data.numistip.com/search?ReverseDesigner=*"Kruger Gray"+{Year=1939|Year=1999}+Prefix=PR&sort=Year DESC

This will return an XML sheet with a list of matching Coin objects sorted from newest to oldest.

If on the other hand we wanted to perform a general search for any Australian threepence, ordered from oldest to newest, we can search the ALL tag like so: https://data.numistip.com/search?q=All~*threepence*+All~*australia*&sort=Year

Coin List

Coin list takes in a comma separated list of coin IDs and returns their Coin objects. This is equivalent to a call to the search function with a q of ID=id1|ID=id2|ID=id3 but operates much quicker.

Argument Data Type Remarks
coins string A comma separated list of coin IDs

For example if we wanted to get the Coin objects of coin 1000, 1001 and 1002 we'd call: http://data.numistip.com/coinlist?coins=1000,1001,1002

Groups

The Groups function runs a query similar to that in the search function but instead of returning the coin objects, it returns selected fields and the number of coins matching.

Argument Data Type Remarks
q string This is the main query string, it takes a boolean logic filter string with the following characteristics.
Order of operations are enforced with braces, { and }
Equalities are specified with =, or ~ for a non-case sensitive equality.
The AND operator is + (a URL escaped ampersand)
The or operator is |
The wildcard operator * can be added at the front or rear of a string.
Strings which have key character must be surronded by single or double quotes.
lang optional string The lang argument indicates the language you wish to search in, leaving this blank only searches the default language for each coin, adding a language here additionally searches the specified language version if available.
fields string A comma separated list of fields to separately group by.

For example if we wanted to get the denominations and reverse designers of all Australian coins dated 1939, we'd call:

https://data.numistip.com/groups?q=DateMM=1939+Country=Australia&fields=Denomination,ReverseDesigner

This would return a list of denominations and reverse designers and their counts.

Subscribe | Ask an Expert | Privacy Policy | About Us | Contact Us