How to use the standard query format: "q" parameter

MAPEGY API supports advanced search functionalities through the standard "q" parameter. Below is an overview of the search types available and how they are applied using q.

MAPEGY API search uses logical operators like AND, OR, and NOT to filter results based on keywords.

You can use the Autosuggest function to generate these queries using natural language.

The "q" parameter:

The q parameter is the standard query format for interacting with the MAPEGY API.
Below is an example in JavaScript showing how to structure a query using the q parameter:

// example in JavaScript

function ScoutQuery() {
	this.format_version = '1.6.0';
	this.data = {
		/*
			Each field contains a nested array of search terms in the format [[x1,x2,...], [y1,y2,...], ...]
			which represents the Boolean query (x1 OR x2 OR ...) AND (y1 OR y2 OR ...) AND ...
		*/

		// Topic names
		topics: [],
		not_topics: [], // AND NOT (...)

		// Organization names
		organizations: [],
		not_organizations: [], // AND NOT (...)
	};
};

// initialize query
var query = new ScoutQuery();

// add terms to query
query.data.topics.push(['artificial intelligence', 'deep learning']);

// build url
var queryParam = '?q=' + encodeURIComponent(JSON.stringify(query));
var route = 'Documents';
var url = 'https://api.mapegy.com/' + route + '/' + queryParam;

‍

Search query tokenization & matching behavior

Stemming, spelling & exact matches

  • Exact matches: Only straight ASCII quotes ("...") mark an exact term. Curly quotes (“...”—often inserted by Word or chat tools) are treated as an unquoted search. An exact match means the phrase must appear verbatim and unstemmed in the title or abstract.
  • Case insensitivity: All searches are case-insensitive (e.g., LNP matches lnp), including exact matches inside double quotes.
  • Stemming & acronyms: The API uses stemming, not just plurals. For example, model, models, and modelling all match each other. However, acronym plurals are not merged (e.g., LNPs ≠ LNP).
  • Spelling variants: Variations in spelling (e.g., sulfide vs. sulphide) are not merged and must be queried separately using OR logic.
  • Subscripts & superscripts: Sub- and superscripts are dropped entirely during indexing. For example, a search for cm² actually searches for cm. Similarly, a search for Li₆PS₅Cl drops the subscripts and will not find Li6PS5Cl.

Stopwords & word gaps

  • Stopword list: The API uses a standard English stopword list of approximately 120 function words (e.g., a, the, and, or, not).
  • Boundary stopwords: For unquoted terms, stopwords at the beginning or end of a search are dropped (e.g., unquoted vitamin a is searched as vitamin). However, for quoted exact matches (e.g., "vitamin a"), the exact text is required in the title or abstract, so the stopword counts.
  • Internal stopwords: Inside an unquoted phrase, a stopword acts as a single-word wildcard, leaving a gap of exactly one word (e.g., unquoted system on chip matches system with chip). Inside a quoted exact match, this wildcard behavior does not apply, so "system on chip" will not match "system with chip".

Hyphens, dashes & special characters

  • Hyphens vs. spaces: The standard ASCII hyphen (-) creates a compound token along with its individual parts. Because of this, a phrase with a hyphenated word never matches the same phrase written with a space, in either direction (e.g., lithium-ion battery will not find lithium ion battery). Advice: Always query both forms with OR. Furthermore, different compound tokens do not match each other (e.g., solid-state battery does not find all-solid-state battery).
    • Only the standard ASCII hyphen builds a compound token. Other dashes (en dash, non-breaking hyphen, minus sign, etc.) behave like spaces.‍
    • Signed numbers: A hyphen directly preceding a digit is indexed as a signed number. For example, the "-8" in ZIF-8 is treated as a signed number, meaning ZIF 8 does not find ZIF-8 and vice versa. The same applies to terms like COVID-19 and UiO-66. Advice: Always query both forms with OR.‍
  • Dropped characters: The + symbol is ignored (ZKB++ is searched as ZKB).‍
  • Spaces: Brackets () are treated as spaces (poly(lactic acid) is searched as poly lactic acid).‍
  • Joined words: Forward slashes / bind adjacent words into a single token (PLA/PCL will not match PLA PCL). Letters and digits without spaces remain a single token (Li6PS5Cl).

Performance drivers & fallbacks

  • Query execution time grows based on how common the words are across the database, not by the volume of terms in the query. Avoid using very common words (e.g., system, method, device) as standalone search terms.
  • If a broad query times out, split the request into smaller chunks by querying specific document types (NEWS, PATENT) or narrowing the date range.

‍

Learn more about queries: 

Related articles