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.
|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)
|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.
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.
This parameter specifies the entity class of nodes in a graph or matrix. Currently the following entity classes are available:
|Anatomy||Entities related to anatomy, e.g. blood, neurons, etc.|
|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.