Hi, I’m new to Supernote and a (very) hobbyist programmer.
I’m playing with the public API, and I have a use-case to retrieve any notes that:
Have a match to some search text, and
Have a specific tag.
For example, no matter how many matching notes I find using the search parameter of Get Selected Cards endpoint, I only want to return matches where the note also has a specific tag.
Using the search parameter seems straightforward, but I can’t find a way to filter the results by tags in the API. Is such a thing possible?
Hey @rogfrich, welcome to the Supernotes community and good question. And the answer is absolutely!
As of Supernotes 3.1, we have standardized the filtering system, so that the same filter_groups you see on Custom Collections you can also use with the filter_group parameter with the Get Selected Cards endpoint.
So if you want to retrieve all cards from the API that have the text “donut” and the tag “sweet”, you could send this request payload to Get Selected Cards:
Having slept on this, I actually thing I was barking up the wrong tree organisationally. This is all about making cards for highlights I’ve made in Kindle, which are automagically synced to Readwise. I have API access to both Readwise and SN, so for fun I’m trying to integrate the two.
I now think I want my hierarchy to look like this:
The idea is that I will fetch all the highlights from Readwise. These are grouped by book, and I may have new highlights for a book that I’ve already got a card for. So the logic will be:
For each book in the list of highlights:
If there is already a card for that book [NOTE 1]
create a child note with that book's card as the parent
Else
create a new card for the book
create a new card for the highlight with the newly created book card as the parent
Note 1 - The book cards will have the title “[book title] by [author]” (values taken from the Readwise API data). I’ll be creating these programmatically, using the Simple API. There may be other notes with similar enough content to come up in a search response, but only the correct book card will be the child of the top level literary notes card. That’s where the tagging idea came in, but I actually prefer the idea of the hierarchy above - the defining feature of a literary note is that it inherits from the top level literary notes card.
So, I think this will work:
payload = {
"search": "[book title] by [author]",
"parent_id": [the id of the top-level literary note card (which will always be the same value]
}
If that comes back empty, then I need to create a new book card. If it finds a match (and there should only ever be one match) then I create the highlight note as a child of the match.
The flow sounds good, but you’ll still want to use the filter_group system rather than the search parameter. Search is a fuzzy search that will match variations on the words as well as matching both in the title and the body of a card. What you actually want is a name filter, like so:
{
"filter_group": {
"type": "group",
"op": "and",
"filters": [
{
"type": "name",
"op": "equals",
"arg": "[book title] by [author]"
},
{
"type": "parent_ids",
"op": "contains",
"arg": "[the id of the top-level literary note card]"
}
]
}
}
In addition, although your usage of the parent_id parameter is correct, I think we will be deprecating that in the near future, as this functionality is now encapsulated by the filtering system, as you can see above.
Ah, thanks for that. I think I’ve wrapped my head around it, although since all the top-level book notes will be children of a single “literary notes” card (and no other notes will be) I can simplify the logic by just grabbing any note that has the correct parent_id.
Point taken on the the parent_id parameter! Thanks for all the help, it’s really appreciated.
