Menu

Suggestion for new API

26 posts

This message aims at: suggesting an idea to improve Numista

Status: Implemented
Upvotes: 2
Downvotes: 0

» Quick access to the last post

I'd like to create a sort of "booklet" of the coins in my collection.
It would be nice if an API exists to get all the information about a coin.
The API should expose the following calls:
1) What are the ids of the coins in my collection?

2) given the id of a coin, return its general information.
The information should include:
- all the features (Country, Type, Years, Value, Material, Weight, Diameter, Thickness, Shape, Orientation, References, etc),
- url of images, author, copyright
- obverse, reverse, edge description, engraver, lettering, etc
- comments (eventually in RTF, HTML or any other suitable format to handle text and images)
- references to other coins
- Numista URL about the coin
- Numista copyright details about the retrieved information

3) given the id of a coin, return its information, related to my collection.
The information should include:
- number of coins for each year, quality, comments

Related posts:
https://en.numista.com/forum/topic24819.html#p248217
Quote: "starnutoditopo"​​1) What are the ids of the coins in my collection?
Look for function "Get list of your own coins"
Quote: "starnutoditopo"2) given the id of a coin, return its general information.
Look for official API docs, function "Find a coin by ID"
Quote: "Megas"
Quote: "starnutoditopo"​​1) What are the ids of the coins in my collection?
​Look for function "Get list of your own coins"

Quote: "starnutoditopo"2) given the id of a coin, return its general information.
​Look for official API docs, function "Find a coin by ID"
Thanks for your reply.

1) ​Though the APIs at https://qmegas.info/numista-api/ are really very nice, as far as I understand, are "unofficial". I'd rather prefer something supposed to be maintained, supported, and guaranteed to mirror the data by Numista. Is there any plan to mark the APIs at https://qmegas.info/numista-api/ as "Official"?

2) The official API is missing some data in the output, like obverse description, reverse description, etc.
All this data is available in the web application, so, in principle, one can grab it from the HTML pages; this almost smells like "stole" the data. I'd prefer to have an official way to get them in the proper way...
Quote: "starnutoditopo"
​2) The official API is missing some data in the output, like obverse description, reverse description, etc.
​All this data is available in the web application, so, in principle, one can grab it from the HTML pages; this almost smells like "stole" the data. I'd prefer to have an official way to get them in the proper way...
​Xavier once said that "There is no issue with [...] scraping data from Numista for personal use, as long as you keep a reasonable traffic." https://en.numista.com/forum/topic72165.html
ūūūūū
Quote: "numinis"
Quote: "starnutoditopo"
​​2) The official API is missing some data in the output, like obverse description, reverse description, etc.
​​All this data is available in the web application, so, in principle, one can grab it from the HTML pages; this almost smells like "stole" the data. I'd prefer to have an official way to get them in the proper way...
​​Xavier once said that "There is no issue with [...] scraping data from Numista for personal use, as long as you keep a reasonable traffic." https://en.numista.com/forum/topic72165.html
So, from ​ehe "ethical" point of view, that's fine!
:-P

From a technical perspective, I'm not really concerned about excerpting data from a web page, rather than an API...
Quote: "starnutoditopo"​​1) ​Though the APIs at https://qmegas.info/numista-api/ are really very nice, as far as I understand, are "unofficial". I'd rather prefer something supposed to be maintained, supported, and guaranteed to mirror the data by Numista. Is there any plan to mark the APIs at https://qmegas.info/numista-api/ as "Official"?

​Xavier created an official Numista API (https://en.numista.com/api/doc/). Megas' API is great and covers a lot of operations. I doubt Xavier will integrate Megas' API into the official because the API does not have a huge demand.
https://mnesiccoins.gitlab.io/    https://www.instagram.com/mnesiccoins/
Quote: "MihajloNesic"
Quote: "starnutoditopo"​​1) ​Though the APIs at https://qmegas.info/numista-api/ are really very nice, as far as I understand, are "unofficial". I'd rather prefer something supposed to be maintained, supported, and guaranteed to mirror the data by Numista. Is there any plan to mark the APIs at https://qmegas.info/numista-api/ as "Official"?

​​Xavier created an official Numista API (https://en.numista.com/api/doc/). Megas' API is great and covers a lot of operations. I doubt Xavier will integrate Megas' API into the official because the API does not have a huge demand.

Whatever... I mean: mine is a request for an enhancement. It would be nice for me if it could be implemented.
As I'm going to use it for personal interest, it would be fine, if available at qmegas. Or I could even grab the data I'm interested in from numista's HTML pages...

​​​​​​My purpose was to give an hint for a feature that may interest someone else, too. :-)
Hello,
The API was improved with:
  • More content to describe a coin type
  • Get the coins in a user's collection (with OAuth 2.0 authentication)
  • Get the list of issuers
Quote: "Xavier"​Hello,
​The API was improved with:

  • More content to describe a coin type

  • Get the coins in a user's collection (with OAuth 2.0 authentication)

  • Get the list of issuers

​Did the URL change? At https://en.numista.com/api/doc/ responds with "not found"...
The URL should be working again :)
Quote: "Xavier"​Hello,
​The API was improved with:

  • More content to describe a coin type

  • Get the coins in a user's collection (with OAuth 2.0 authentication)

  • Get the list of issuers

​​Thanks for update.

I have a few things to say about it:

1) Where do we get client_id for OAuth? In documentation we see following:
Quote{client_id} is the client ID which was assigned to your application and provided together with your API key.
but later I found out that I need just use my numista login. Why? For example I develope mobile application "Numista App" and when I redirect user to authorization form I whould like him to see message "Would you like to authorize Numista App to perform the following actions on your Numista account?" and not "Would you like to authorize Megas to perform the following actions on your Numista account?". At the same time the redirect domain should be locked to that client id, otherwise anyone who build scam website, can use my client ID and impact authority of my app. We need to be able to configure all these parameters on our API page.

2) Where do we see all possible options for scope parameter?

3) Can we get more information about the logged user? I need to know at least his login/nickname, because once he logged in my application I would like to address him correctly "Hello, %nickname%!", but currently I know only his ID, so what should I say "Hello, numista user 21231"? Of course it's better to have separate API function to get detailed user's information.
Thank you Megas for your feedback.

1) The client ID is not necessarily the same as your username. I can change it if you like, as well as your application name.
In terms of security, your client ID can be used only in combination with your API key, preventing other people from using it.

2) The possible values for scope are visible in the authorization window. Currently view_collection and edit_collection are defined, although only view_collection has an effect at the moment.

3) I didn't think about that. I will add a new service to get user information.
Generally speaking, I admit the API is still pretty limited at the moment. I'll continue adding functionalities depending on what people tell me they need.
Is there any reason why not each numista member have a self-generated API key and client ID, accessible from settings page?
Hello,

The API now offers retrieving basic details about a user (username, avatar). Sorry I messed up with caching, so you may have to clear or disable your browser cache to see the updated documentation.

I didn't put in place self-service API key generation yet. It's not a priority for me, given that there are few API users at the moment and I like to have some visibility about who and how the API is used, as we are still in the early stage of the API.
The current process is to request a key by email at postmaster@numista.com and you are welcome to apply!
Status changed to Implemented (Xavier, 15-Mar-2020, 03:29PM)
Looks pretty good until now. I have a suggestion for language mandatory parameter. It's simply annoying, can you set a default value for this parameter?

EDIT:
Some details like engravers, references, tags are not yet implemented, right?
Quote: "Andy289"​Looks pretty good until now. I have a suggestion for language mandatory parameter. It's simply annoying, can you set a default value for this parameter?

​EDIT:
​Some details like engravers, references, tags are not yet implemented, right?
​Also for me, engravers, references and tags would be interesting information to get.
Bug report:
I tried to fetch coin 111; in the UI, it seems to have 1 related coin, while the API has no "related_coins" field at all:

{ "id": 111, "url": "https://en.numista.com/catalogue/pieces111.html";, "title": "1 Euro (1st map)", "issuer": { "code": "allemagne", "name": "Germany - Federal Republic" }, "minYear": 2002, "maxYear": 2006, "type": "Standard circulation coin", "value": { "text": "1 Euro", "currency": { "id": 67, "name": "Euro" } }, "shape": "Round", "composition": { "text": "Bimetallic: copper-nickel clad nickel centre in nickel brass ring" }, "weight": 7.5, "size": 23.25, "thickness": 2.33, "orientation": "medal", "obverse": { "description": "The eagle, the traditional symbol of German sovereignty, is surrounded with the twelve stars of Europe.", "lettering": "2003 A", "picture": "https://en.numista.com/catalogue/photos/allemagne/1379-original.jpg";, "thumbnail": "https://en.numista.com/catalogue/photos/allemagne/1379-135.jpg";, "picture_copyright": "Florino28" }, "reverse": { "description": "A map, next to the face value, shows the gathering of the fifteen states of the European Union", "lettering": "1 EURO LL", "picture": "https://en.numista.com/catalogue/photos/allemagne/1380-original.jpg";, "thumbnail": "https://en.numista.com/catalogue/photos/allemagne/1380-135.jpg";, "picture_copyright": "Florino28" }, "edge": { "description": "Segmented reeding", "picture": "https://en.numista.com/catalogue/photos/allemagne/2238-original.jpg";, "thumbnail": "https://en.numista.com/catalogue/photos/allemagne/2238-135.jpg";, "picture_copyright": "Cyrillius" } }

Cheers,
Xc
Several fields describing a coin are still missing, including engravers, references, tags, related coins, comments, numeric face value, mints, rulers, type of coin and demonetization date.
I will add them progressively.
Status changed to Started (Xavier, 16-Mar-2020, 01:40PM)
Quote: "Xavier"​Several fields describing a coin are still missing, including engravers, references, tags, related coins, comments, numeric face value, mints, rulers, type of coin and demonetization date.
​I will add them progressively.
​Fine. My bug report was just to point out that the API documentation provides a field called "related_coins", but the result is missing it.
;)
Engravers, comments, related coins, tags and references have been added.
To help about references, it's also possible to retrieve the full list of catalogues.
The parameter "lang" becomes optional. English language won the coin toss to become the default language.
Great work Xavier but "See my API key" section is the greatest addition.
Quote: "Andy289"​Great work Xavier but "See my API key" section is the greatest addition.
​It was already there, located at the bottom of the page. I only moved it up ;)
Happy to see it helped!
Mints, rulers and numeric face value have been added.
Status changed to Implemented (Xavier, 17-Mar-2020, 10:02PM)
Something small that nice to have... If user already accepted authorization for specific client ID and the scope, then I think there is no need to show him confirmation dialog again, it's better automatically redirect to return url. Or at least do not show the dialog with in first month after last authorization.
I actually see no reason to have a validity of only 1 hour. It must be frustrating for users to keep logging in every hour. Another option would be refresh tokens, but they make the process more complicated for little added value. So I just increased the access tokens validity to 3 months.
I guess this is a more reasonable expiry time, and I'll make something for users to be able to revoke the authorization from their account settings.
I have 2 small additional requests:

1) Can we please have commemorative series info in coin's data?

2) In case I try to receive info of coin that have not been published yet, the response is empty with HTTP code 200. In order to be consistent different HTTP code should be received. But much better is to return coin's info and add new status field with possible values "PUBLISHED" or "NOT PUBLISHED".

» Top of the page

Used time zone is UTC+2:00.
Current time is 07:04PM.