(or Ctrl+Enter) | | format query | decode query | copy query  +  | clear | show log | [0,0] | -1
open
|
| copy URL
| clear, copy or download results copy or download results | {*} [*]
| ↑ ↓ 0 [0] | JSONPath | size:
JSONpath navigator | copy X


NBA Query scratchpad help X

General This tool helps you to build queries for the Netherlands Biodiversity API (NBA), execute them, and store them for re-use. It is not a true query-builder, but rather a collection of functions that makes it easier to understand what a query should look like, helps you construct and test them, and examine their resulting output. Before you start, it might be good to get acquainted with the NBA:

If you want to use the NBA directly, it can be accessed at .

About this help You can click and drag the header to move this window to a position of your liking. Click the 'X' top right to close. Click and hold marked items to highlight the corresponding item in the main screen.

Writing & running queries Service list
List of available endpoints in the API. Endpoints are grouped by document type: specimen, taxon, multimedia, geo or other. For most endpoints, a short description of the service's function is shown when you hover with the mouse over the item in the list. Some items additionally display one or more icons:

'Simple type' queries have the form parameter=value (for instance: collectionType=Aves), whereas regular queries have a more complex form. There are templates available to help you on your way with more complex queries; see the section 'Inserting query-elements' below.
Explainable services can be called with an added 'explain' parameter that changes the regular output to a breakdown of the steps that lead to that output. Check add explain to enable.

Server link: link to the root of the NBA server.

Query window
Window for writing the query you want to run. This can be either a JSON-object (for querySpec-queries) or a query-string (for human readable queries). Specify just the actual query, not the rest of the URL (or the '?') - these are inferred from the values selected in the service list. When you first open this page, two example queries will be automatically added to the list of saved queries to give you an idea what they look like.
Queries can be spread across multiple lines (for readability). Empty lines will be ignored, and lines that start with one of these character(s): will be treated as comment and ignored.

Execute query
Click the execute query-button to run your query. When you click the button, the program will, in short:

  1. Take the selected entry from the service list;
  2. If the service requires a query, take the contents of the query window, and encode them if required. If the selected service does not require a query, the contents of the query window are ignored;
  3. Put them all together to turn it into a NBA-query;
  4. Print the the complete resulting URL;
  5. Execute the query and print the formatted result in the result window.

Notes:

Query window manipulation
Inserting query-elements
Right-click in the query window to see the edit, operators and queries menus. Hover over the menu title to access each menu's options. Select and click an item from queries to insert it into the query window at the cursor position, or over selected text. Inserting operators works the same way.
Finding document fields
Type the (partial) name of a field in the type to find field name-input to find a field. As you type, a droplist will appear displaying all fields matching your search term (type a space to see all available fields). Only fields that match the document type of the selected service will be displayed. Click an item to insert it into the query window at the cursor position, or over the selected text. The droplist items include the name of the document type, as well as the fields' datatype and analyzers; these won't be inserted into the query window).
Fields are matched with each part of your search string, which is split by spaces. For instance, searching for ers gath name will match every line that has the strings 'ers', 'gath' and 'name' anywhere in their name, such as "gatheringEvent.gatheringPersons.fullName".
By default, datatypes and operators are excluded from the search process; by checking include datatypes and analyzers in search you can include them in your search (for instance if you are looking for a field of a specific datatype). Check show fields for all document types to see results for all document types, not just the one corresponding with the selected service.
Manipulating text in query window
Use decode query to decode the contents of the query window, useful when you want to investigate a query but only have the full url.
To copy the query to the clipboard, click copy query. Double clicking does the same and additionally adds {code} tags around the copied content for readable pasting into JIRA.
Click copy query + to copy all query elements to the clipboard. (Note: holding down Ctrl while clicking any of the copy-links will additionally log the copied content to the browsers's console).
To clear the query window, click clear query.
If the query window has focus, use Ctrl + F11 to insert a comment char in query-window at the cursor; also works on multiple selected lines (adds them at the beginning of each line), and Ctrl + F12 to enclose selected text in the query-window in double quotes; also works with multiple words (detects word boundaries).

Resulting URL & run altered query
The resulting URL-window shows the resulting URL that the application sends to the NBA. You can directly edit the URL and execute the result by clicking run altered query (button becomes available once you've actually changed the URL). This is intended for quick debugging purposes; please note that your edits will be lost the next time you run execute query.

Query run options (available once you have executed a query)

result window
Results of your query from the NBA-server. You can switch view between JSON and tabular data.

Saving queries and executing saved queries
Note on saved queries
Saved queries are stored in the local storage of your browser. This means they will be available across browser sessions, but are subject to whatever the browser does to its own Local Storage. Emptying your cache will most likely not cause any problems, nor will upgrading your browser. However, re-installing or performing a factory reset or 'fresh up' of your browser will probably cause your saved queries to be deleted. There are, however, several options for exporting and backing up stored queries.
Saved queries will not be available when running a private or incognito session, but they will still be there when you start a regular session. Saved queries are not available across different types of browsers, but you can export them from one end import in another.

Query name to save
Enter the name under which you want to save your query. Max. Length is 64 characters. You can clear the input by clicking the clear query name-symbol.
Prefix your query with a name between straight bracket to create a group of queries. Creating queries [TEST] query a and [TEST] query b will create a group called 'TEST' containing queries 'query a' and 'query b'. You can collapse groups in the query list, which helps maintain overview.

Save query
Click save query to save the content of the query window with the query name to save. The application will also save a reference to the service that is selected in the service list at the moment you save the query. If, for whatever reason, you don't want the service to be saved as well, uncheck the save including service checkbox before you click save.
The query will be saved in your local browser storage, and will remain available across sessions. If you choose a name that already exists, the application will overwrite the existing query without warning.
The application will show a message stating the result of the save action, above the query name-input (see what a message looks like). It will also automatically update the list of saved queries.
please note, the application only saves the query and the service, not the server. So if you load a saved query, you'll have to manually select the appropriate server to run it against.

Saved queries
List of saved queries. Legend to the various symbols:

⟵ Load the saved query into the query window and set the saved service in the service list. Hover over the symbol to see the name of the saved service. Click while holding down Ctrl to cause the query to be executed after loading.
x Delete the query (asks confirmation).
📋 Copy the query name to the query name to save input. Handy when you want to overwrite an existing saved query. Clicking one next to a group copies that group's name to the input, so you can more easily save a query as part of that group.
≡ Open query notes (see below).
≛ Same, but query already has some saved notes (hint indicates note length).
⧉ Indicates a group of queries. Click to expand. The number indicates the number of queries in the group.
When you have no saved queries, the application automatically creates a set of example queries.

Query notes
The application allows you to store notes with a query. Click on one of the ≡-symbols to open a popup with the notes for that query. You can have only one set of notes open at a given time. Clicking a second ≡-symbol while notes are already open will automatically save before opening the next set of notes. Notes are deleted automatically when you delete the corresponding query.
The note title is the same as the query the note belongs to. The number after the title indicates the size of the note (not sure if there's a maximum).
Type your text in the notes input area (which opens with existing notes if there are any) and click save notes to save the notes. To delete, clear the entire input and click save.
Click insert timestamp to insert the current date and time at the cursor position. Click insert line to insert the current date and time at the cursor position. Click close note to close the notes popup.
If there's a valid URL in the notes, you can select it to make a clickable link-icon ↗ appear in the notes window's header (obviously an actual hyperlink would be more practical, but the notes are in a textarea, which doesn't render html).

Query export
Click export all queries to have scratchpad automatically download a backup of all your queries to the browser's downloads-folder. See below for automated backups.

Additional options
Click the additional options-icons (▼ ▲) to toggle the maintenance options.

Use query backup file import to import queries from a previous backup file. By checking enable automatic monthly query-backup, the program will automatically back up your saved queries to the browser's downloads-folder (note: works only if you actually use the scratchpad once in a while).

Use export selected queries to export selected queries as a JSON-string. When you open additional options, checkboxes (☐ ☑) appear for each item in the saved queries list. Use the select all and select none links to change the selection in bulk. Select the queries you want to export, and click export selected queries. The corresponding JSON-string is written to the query window (notes, if any, are included. Services are not). Select and copy the JSON-string from the window and save it as backup in a regular txt-file, or share it with other users. Paste an exported JSON-string into the query window and click import queries to import the queries. All queries are imported; if another query with the same name already exist, a number is added to the name of the newly imported query.

Use delete selected queries in combination with the checkboxes in the saved queries list to delete queries in bulk (after confirmation).

Click query timer to bring up the query execution timer. The timer counts the delay between the moment the full query is launched, and the moment the results come back (more precise, between the moment the src-attribute of the result window is set, and the window's onload-event is triggered). The timer also keeps an average if you execute the same query repeatedly.

Click the output hashes link to bring up a list of output hashes. Each time you run a query, a hash of the resulting output is printed, providing an easy way to quickly see whether the results of two subsequent queries differ. The hashes themselves have no meaning.

Toggle enable Ctrl+s to enable the use of ctrl+s for saving of the current query (content of the query window), using the name of the currently highlighted saved query (= the last one you loaded or saved). Be aware, the program overwrites the stored query without warning, and there's no undo. Functionality is turned off by default.

Key bindings

When service select list is active, press a key to:

About This tool comes "as is". It was originally developed using Firefox 54.x, later in Chromium. This is version ().

version history

known issues, bugs, ideas

links Netherlands Biodiversity API (NBA)

Useful tools