API methods: General overview

The basic URL schema for API requests is as follows:


The placeholders in curly brackets must be replaced by specific values, whereas userName refers to the account’s user name that is used to log in to mergeflow.net (provided by Mergeflow) and method specifies the method and therefore the type of resource returned by the API. queryString contains the definition of the query consisting of search terms and other filters. 

To avoid URL length restrictions, the queryString can be placed in the request body instead of the URL. The query string must be placed as a raw string (text/plain), the syntax stays the same as in the URL. Query strings found in the request body are preferred over query strings in the URL. 

All requests must be performed via HTTP GET or HTTP POST. The available methods and query parameters are specified below. Requests that accept data are only available via HTTP POST.

General Query Parameters

Several parameters are available to express a query. This section specifies all available parameters. As not all parameters can be used with every API method, each method definition lists its applicable parameters.

Parameter Description Supported Values Examples
q Used to specify the search terms. Boolean searches (OR, AND, NOT) are supported. Multiple q parameters are allowed within one query. Search terms (Strings) q=”foo bar” (exact match)q=foo|bar (OR)q=foo&q=bar (AND)

q=-foo (NOT)

date Limits the search to a certain date range. The range is specified by an anchor date and a timespan in days (going back in time) yyyy-mm-dd-b date=2015-08-25-10(2015/08/15 – 2015/08/25)
sp Repository filter; limits the search to one or more repositories. Takes the IDs of the repositories as value; OR and NOT are supported Repository IDs (Integer) sp=2655sp=2655|2687 (OR)sp=-2655 (NOT)
site Limits the search to a certain site/host. OR and NOT are supported Sites (Strings) site=arxiv.org
rows Specifies the result rows returned by the API method. Default value is 10 Integer rows=20
start Defines the start index of result rows (zero based). Can be used for pagination. Default value is 0 Integer start=20
orderby Specifies the sort order of result documents. Default value is by date (descending) date, rel orderby=rel
groupby Groups the results by the specified category and returns the document count for each group date (Daily)month (Monthly)year (Yearly) groupby=date
tagcount Specifies the amount of tags returned. Default value is 40 Integer tagcount=40
tagcat Specifies the entity class of tags returned. Entity class name (see below) tagcat=person
tagtype Specifies the type of the tags. Set the value to “custom” to see your search terms allcustom tagtype=custom

To clarify the use and the complete available feature set, some of the above parameters will be explained in detail.

q Parameter

Searches are mainly based on search terms. The following syntax enables strong and flexible query expressions:

  • Exact MatchesUsing quotation marks will search for an exact match.  For instance, q=”sensor network” will only retrieve documents containing “sensor network” but not for instance documents containing “sensor networks”, “sensor”, or “network”.
  • Wildcardsmergeflow supports wildcards (“*”).  Searching for q=sensor* will retrieve documents containing “sensor”, “sensors”, “sensoring”, etc..
  • Boolean Search – ORIn order to search for “energy harvesting” or “power harvesting”, for example, use the pipe operator (“|”):  q=“energy harvesting”|“power harvesting”.
  • Boolean Search – ANDIn order to search for “energy harvesting” and “sensor network”, for example, use a second q parameter:  q=“energy harvesting”&q=“sensor network”.
  • Boolean Search – NOTIn order to exclude the search term “sensor network”, for example, prepend the minus operator: q=-“sensor network”.
  • Entity class searchIn order to restrict a search term to a certain entity class, append the entity class name in square brackets. For example, use q=Apple[Company] to search for documents where „Apple“ was recognized as company. For countries, use the ISO 3166-1 alpha-2 country code as search term, e.g. q=US[Country]. See tagcat parameter below for all available entity classes. To retrieve all documents with companies, for example, use the Wildcard: q=*[Company].

See "Mergeflow's search syntax" for further information.

tagcat Parameter

This parameter specifies the entity class of nodes in a graph or matrix. Currently the following entity classes are available:

Entity Class Description
Anatomy Entities related to anatomy, e.g. blood, neurons, etc.
Company Companies
Country Countries
Disease Diseases
Spotlight Emerging technology (click here to see the topics)
Event Events like conferences
Investor Financial investors and institutions 
IPC International Patent Classification (using CPC codes)
Location Locations, mainly names of towns and cities
Material Chemical compounds, as described e.g. in PubChem
Organism Entities related to organisms, e.g. bacteria, rats, Staphylococcus
Organization Governmental and research institutions, universities
Person Names of persons

Entity classes can be combined with the pipe operator, e.g. tagcat=Company|Person. This is useful to analyze the relationship between entities.

Still need help? Contact Us Contact Us