Math Web Search API
Provided API
The search server also provides a search API to be used by other applications. This API is available at raspberry.eecs.jacobs-university.de on port 19843 (simply use a TCP/IP connection).
The accepted set of commands is:
Notes:
- The search commands are not case sensitive.
- All lines should be terminated by \r\n not just \n.
- The commands XMLQ.ALL, STRING.ALL, EALL and CALL are not used by the provided web interface. They are provided for convenience.
- If you feel you need a new command that is not yet provided, please contact the authors.
Modifiers
The commands in the API allow modifiers to be applied to them. The expected format is COMMAND_NAME/MODIFIER. The list of supported modifiers is:
Example: sending XMLQ/RANK as command name acts as the XMLQ command with the RANK modifier applied.
XMLQ
This is the essential command of the protocol. It is short for "XML Query". XML queries described in Help are sent to the search server using this command. The expected input is four lines of text, representing:
XMLQ number of requested results to display (integer) offset to begin display at (integer, most often 0) the XML Query converted into a one line string
The output for this command, if successful, will be:
OK an id number used to refer to this search (client should remember this) the search time (seconds) number of total found results
followed by (at most number of requested results)x3 lines, describing each result. An individual result looks like:
title link description
title and description are self-explained. link is a bit more complicated. The first character of the link is one of U, E, C or S. U means that the link is unique for that document (there is a single formula matched in that document). E means that there are more matched formulas under that link. An Expand button should then appear to show the other links (we call them sublinks). Once a link is expanded, its first character changes to C. The link can then be collapsed (a Collapse button should appear). Sublinks for expanded links are marked with an S in front. After this first character, one or two links appear, separated by a 0x01 character. If 0x01 is present in the link string, it means that both presentation and source are available for the result document. The first link should be used for the title (the presentation document) and the second one should be used for an extra button named Source. If 0x01 is not present in the link string, only the source link is available. That should be used for the title of the result and no Source button should be present.
It is sometimes the case that some assumptions are made in the search. Those are turned into warnings and are attached as one extra line after the individual results. This and the STRING command are currently the only ones that can have warnings.
In case of an error, the following output is given:
ERROR error messages ...
The same error output message format is used for the rest of the commands as well.
XMLQ.ALL
This is a convenience command. The expected input is just the XML Query as discussed for XMLQ There is simply no limit on the number of results that should be produced.
XMLQ.ALL the XML Query converted into a one line string
The output for this command is exactly the same as for XMLQ.
STRING
This command is almost the same as XMLQ. The only differences are that STRING is sent instead of XMLQ for the command name and the sent XML Query is replaced by a string encoding of the search term. Currently only internal representations of terms, ASCII and Mathematica expressions are well processed as strings. By default, input for Mathematica is assumed. To require processing as internal representation, prefix your search string with a # sign. In the future, LaTeX queries will be accepted here as well and the API will not change.
STRING.ALL
This is another convenience command. It acts for STRING as XMLQ.ALL does for XMLQ. Only a string is sent as the input and the output is the same as for STRING
CONT
This command is a helper command for XMLQ or STRING. As you probably noticed above, not all found results are sent to the client, but only a required number of them and an id. Using the CONT command, other subsets of the found results can be accessed for 30 minutes since the search was performed. The exact input is:
CONT number of requested results to display (integer) offset to begin display at (integer) an id returned by XMLQ or STRING (expires after 30 minutes)
The output is exactly the same as for XMLQ and STRING. No warnings are sent currently, but an implementation of this protocol should handle them anyway since they may be added at a later point in time.
ELINK
This is the command used for expanding links. Once an Expand button is clicked, this command is sent to the search server. The parameters are:
ELINK number of requested results to display (integer) offset to begin display at (integer) an id returned by XMLQ or STRING (expires after 30 minutes) the offset of the link whose Expand button was clicked
The output is exactly the same as for CONT.
EALL
This command is again a convenience command. Its purpose is to expand all links. The format is:
EALL an id returned by XMLQ or STRING (expires after 30 minutes)
The output is just
OK
or
ERROR error messages ...
CLINK
This is the command used for collapsing links. Once a Collapse button is clicked, this command is sent to the search server. The parameters are:
CLINK number of requested results to display (integer) offset to begin display at (integer) an id returned by XMLQ or STRING (expires after 30 minutes) the offset of the link whose Collapse button was clicked
The output is exactly the same as for CONT.
CALL
This command is again a convenience command. Its purpose is to collapse all links. The format is:
CALL an id returned by XMLQ or STRING (expires after 30 minutes)
The output is the same as for EALL.
DETAIL
For every result shown, a Detail button is available. When this button is clicked, we get more detailed information about a result. The exact input is:
DETAIL an id returned by XMLQ or STRING (expires after 30 minutes) the offset of the link whose Detail button was clicked
The output for this command is different. If successful, it is:
OK title link description Presentation MathML formula for the found result
link here has the same format as for the list of results. After this part of the output, a substitution used for the match may follow. The substitution is given as an even number of lines:
variable name #1 Presentation MathML formula or simple string for the replacement #1 variable name #2 Presentation MathML formula or simple string for the replacement #2 ...
SRC
For every result shown, an XML Source button is available. When this button is clicked, we get the source used for indexing the whole term. This may save the user some editing for other related searches. The exact input is exactly the same as for DETAIL. The output, if successful, is of the form:
OK <xmltag> ... </xmltag>
RANK
For commands that return a list of results, this modifier changes the format of the returned link: a value for the rank in the interval (0, 1.0] is added to the end of the returned link, separated by 0x02.