gdSuite API Specifications

You are currently viewing this document inside of the gdSuite web site template system. Click here to break free and view it without the templates.

Introduction

The gdSuite API allows developers to access Google Desktop search results without directly processing the HTML coded results. We have tried to make this document as clear as possible, but we realise that in some places is gets confusing. That's why at the end of this document, there is an example section. If you have any questions feel free to post in the forums or email gdsuite_api@airbearsoftware.com. A changlog is located here.

Distribution

This API, which is available for public download here, is NOT redistributable and cannot be used by developers in their software. However, any developer wishing to use the gdSuite API in their software should contact gdsuite_api@airbearsoftware.com to request the redistributable, (which is smaller in size, performs faster, and has fewer dependencies) and permission to use it. We do not intend to charge at all for use of the gdSuite APIs to Google Desktop. We will grant permission to redistribute these APIs to almost anyone who asks. We use this system only so that we can keep track of who is using the APIs. These APIs are part of gdSuite, and as such, the gdSuite license agreement located here applies.

Case Sensitivity

Everything in this API is case sensitive. Command line variables and their values as well as template variables are case sensitive.

Errors

If an error occurs during a search, the error will be written to the output file and the gdSuite API will exit. However, if an error occurs while processing the arguments, a message box containing information about the error will appear and the API will exit. This is for safety; if processing errors were written to the output file and the output file were misread, important documents could be overwritten.

Using the API

The gdSuite API is provided via a command line interface. This means that to use the gdSuite API, you simply run desktop.exe with the command-line arguments to specify what kind of search you are performing. See the table below for more information on these arguments. Note: desktop.exe is located in the gdSuite program files folder.The location of this folder is stored in the Windows registry in the HKEY_CURRENT_USER\Software\gdSuite key under the value install_dir.

Getting the Results

To get the results out of the API, you must specify an output file as one of these arguments. You must also specify an output type. This type specifies how the results will be formatted. Templates are used to specify the formatting. By default, the API comes with 2 template sets, XML and CSV. For information on making your own templates, see "Templates" below.

The Status File

API searches will usually by instant; however, some searches with many results may take longer. To receive information on how far through the search the API is, you can use status files. To specify the status file, use the status_file command line variable. You must also specify the the status_mode . This can either be none (no status file, the default), create_when_finished (the status will only be written to the status file when the search is done), or populate_during_search (the status file will be updated during the search as new results are found). Note that the format of the status file is dictated by the format of the output (output_type), so if the output_type is xml, the status file will be also formatted in XML.

Command Line Arguments

Introduction

The arguments may be combined in any order using the form -variable1="value1" -variable2="value2" -variable3 .

With one type of variable, such as variable1 and variable2 above, the variable name is preceded by a - and followed by an equals sign. The value of this variable is surrounded by quotes. To include a " in the value of a variable, precede it with a backslash (\). If the value must include a backslash that is not for the aforementioned purpose, it may be preceded by a backslash as well, although this is not necessary. For example, a " in a value must be written as \" and a \ in the variable may be written as either \ or \\ .

With the other type of variable, such as variable3 above, you must include the - and the variable name. No value is required. This will be explained more below.

Many times, the arguments will become very long and may be hard to pass to the gdSuite application. In this case, pass the arguments -silent -load_cmd_from_file="[filename]" . This will force gdSuite to load the arguments from the file [filename] . In this file, you can use line breaks instead of spaces.

List of Command Line Arguments

You may notice that the filter options towards the bottom of the table correspond to advanced search features in gdSuite. For many of these options, there is no default or "all" option. So, if you don't want to engage a filter, simply don't specify the variable related to it.

Key:

Black and Grey: Available in All Versions
Blue: Available in All Versions Except the Redistributable
Orange: Available only in the Redistributable

Examples

Example One

This example will demonstrate how to search for the term gdsuite in the folder D:\Documents and Settings\Aaron\Desktop\desktop\ and its subfolders.

Note that we do not need to specify that the type is file; gdSuite assumes that it is a file because we included a file name and folder. However, this assumption only applies to the file name and folder variables; not any other filters.

We will output the results in XML to D:\output.xml and use the status file D:\status.xml with the status mode create_when_finished. Lastly, we will use a command file located at D:\command.txt to hold the arguments.

The command line:

"D:\Program Files\gdsuite\desktop.exe" -silent -load_cmd_from_file="D:\command.txt"

The contents of D:\command.txt

-silent
-output_type="xml"
-output_file="D:\output.xml"
-status_file="D:\status.xml"
-status_mode="create_when_finished"
-folder="D:\Documents and Settings\Aaron\Desktop\desktop"
-subfolder
-terms="gdsuite"

If we were to do this without using the command file, the command line would look like this:

"D:\Program Files\gdsuite\desktop.exe" -silent -output_type="xml" -output_file="D:\output.xml" -status_file="D:\status.xml" -status_mode="create_when_finished" -folder="D:\Documents and Settings\Aaron\Desktop\desktop" -subfolder -terms="gdsuite"

Example Two

This example will demonstrate how to search for the term google in web pages.

We will output the results in XML to D:\output.xml and use the status file D:\status.xml with the status mode populate_during_search. Lastly, we will use a command file located at D:\command.txt to hold the arguments.

The command line:

"D:\Program Files\gdsuite\desktop.exe" -silent -load_cmd_from_file="D:\command.txt"

The contents of D:\command.txt

-silent
-output_type="xml"
-output_file="D:\output.xml"
-status_file="D:\status.xml"
-status_mode="populate_during_search"
-terms="google"
-type="web"

If we were to do this without using the command file, the command line would look like this:

"D:\Program Files\gdsuite\desktop.exe" -silent -output_type="xml" -output_file="D:\output.xml" -status_file="D:\status.xml" -status_mode="populate_during_search" -terms="google" -type="web"

Templates

Introduction

The API uses templates to format the output. There are five normal templates and one escape character template. In each of these templates, there are variables. These variables look like %variable%. When the output file is generated, these variables are replaced with their data. See below for table of the variables and where they can be used.

The format of the output file is as follows:

[header template]
[item template repeated as many times as necessary]
[error template, if an error occurs]
[footer template]

Using Templates with the API

To specify templates in the API, use the output_type argument. You can either specify xml , csv , or custom templates. To specify custom templates, use a comma separated list of template files. The complete string may look like this:
>-output_type="[path_to_header_template],
[path_to_item_template],
[path_to_footer_template],
[path_to_error_template],
[path_to_status_template],
[path_to_escape_template]"

Line breaks were inserted for readability and should not be present when using the API.

Template Variables

Header

Item

Footer

Error

The error template is used when the API encounters an error. This error is usually either related to the results (i.e. there are no results) or an internal processing error. When an error occurs, the error information is written to the output file, the footer is written, the status file is updated (it will reflect 100% and 1 out of 1 results processed), and gdSuite exits.

Status

The Escape/Encode Template

For many data formats, some characters are illegal and will corrupt the file. In XML, for example, ampersands (&) must be converted to & or the XML will be invalid. The escape/encode template tells the gdSuite API what characters to convert. The first line of this template file must reflect the number of entries. The remaining line contain the original character(s), a space, and the new characters in the format [original] [replacement] . Thus, a typical template may look as follows:

5
& &
' '
> >
< &lt;
" &quot;

Note that even if your custom template does not require escape characters, you MUST have an escape template and you MUST remember to include the 0 on the first line.