(or Ctrl+Enter) | | add slashes | decode query | copy query + | clear | [0,0]

direct NBA link: new window | re-use window | clear results | copy URL | copy results | 0 [0] | JSONPath

(; ) | | help | running on:
help X

This tool helps you to build NBA-queries, 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:

Saved queries will be stored in the local storage of your browser, and will survive across sessions (and emptying your cache, most likely). However, they do not work in private sessions and are not available across different browsers, so if you have queries you really want to hang on to, make sure to save them somewhere else as well.
Please note that for reasaons of technical convenience, this program uses a proxy for communicating with the NBA server. If you want to use the NBA directly, you can access it 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 the bold topics to highlight the corresponding item in the main screen.

Writing & running queries
Service list
List of services available in NBAv2. Each item shows the actual path of the query, an optional [name] and an optional %-sign to indicate that the service requires html-encoded queries, or a - to indicate that a service doesn't expect a query. The list of services is automatically retrieved from the NBA server.
Note: the %-sign is just for information - you don't have to do any encoding yourself; the application will take care of it.

Server status
Link to the root of the NBA-server, shows the status page of the server (opens in a new window). Page also displays version info.

Query window
Window to specify 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 should 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 application will:

  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 in the form of a URL;
  4. Print that URL in the resulting URL window;
  5. Execute the query and print the formatted result in the result frame.

(1) The application does not check whether the combined service and query actually makes sense. If for instance you combine a JSON-query with a human readale service, the application will open the URL to the NBA all the same, which will generate an error as output.
(2) The application does not check in any way whether the query is legal; you can enter anything you like. There is no predefined field list, and the application does not balance brackets (alas).
(3) Mouse-aversive users can also execute a query by pressing Ctrl+enter (works globally).

Query window manipulation
Inserting query-elements
Right-click in the query window to see the edit, insert code and insert logical operator menus. Hover over the menu title to access each menu's options. Select and click an item from insert code to insert it into the query window at the cursor position, or over the selected text. insert logical operator works in 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 add slashes to add slashes to all double-quotes in the selected text in the query window. Hold down Ctrl while clicking to also remove newlines and replace multiple spaces by single ones.
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. 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)
open in new window: opens the last executed URL in a new browser window; always opens a new window. open in same window: opens the last executed URL in a new browser window, then re-uses that window when you click the link again (avoid browser-tab overload). clear results: clear the result frame. copy URL: copies the last executed URL to the windows clipboard (not sure about mac/linux). please note that these three work with the last URL that was actually executed. if you change something in resulting URL but do not execute the result, these three links will use the last URL that was (hence their absence when you first open the page).

Result frame
Results of your query from the NBA-server.

Saving queries and executing saved queries
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.
Same, but for queries without a saved service (the selected service remains unchanged when you click this).
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 load a saved query that includes a reference to a service that no longer exists, no service will be set. Note that the path of the service is used as unique identifier; if, for some reason, you have different services with the exact same path, the one that comes first in the list will be the one that is set when loading. When you have no saved queries, the application automatically creates two 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.

Query maintenance
Click the query maintenance-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 query maintenance, 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 frame is set, and the frame'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

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

version history

known issues

Netherlands Biodiversity API (NBA)

Useful tools

JSONpath results | copy X