You are currently viewing this document outside of the gdSuite web site template system. Click here to view it with the templates.
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.
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.
Everything in this API is case sensitive. Command line variables and their values as well as template variables are case sensitive.
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.
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.
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.
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.
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.
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
| Variable | Required | Values |
Description |
|---|---|---|---|
initial |
yes |
[none] |
This tells gdSuite to run the initial settings wizard. If this wizard is not run, the gdSuite API will not work. This wizard will be shown to the user. All other arguments will be ignored |
silent |
yes |
[none] |
This variable is used to tell gdSuite that the API is being used. Without this argument, gdSuite would show its search interface and all the below arguments would be ignored |
output_type |
no |
xml |
This tells gdSuite what type you want to the output to be. Set this variable to csv or xml or specify your own templates by specifying [tplHeader],[tplItem],[tplFooter],[tplError],[tplEscape] as the value where the tplXxxxxx are the paths to the template files. For more information, see Templates below. |
output_file |
yes |
[custom] |
Specifies the filename to output the results to. |
status_file |
no |
[custom] |
Specifies the filename to output the status to. |
status_mode |
no |
create_when_finished |
Specifies the mode for the status file. 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). |
noencode |
no |
[none] |
If you specify this value, no characters will be escaped/encoded in the output and the escape/encode template will be ignored. |
show_form |
no |
[none] |
If you specify this value, gdSuite will be shown while the search is being performed. This is very useful for debugging you applications. You will notice that the search bar on the left will be populated with the filters you specified in the command line arguments. Don't be surprised when the results list remains blank; results are written to the file, not added to the results list. |
max_results |
no |
0 (no limit) | Specifies how many results the API should fetch. Specify zero for unlimited results. |
Filter Options: |
|||
date_type |
no |
week month year custom |
Specifies the date range: the last year, the last month, the last week, or a custom range specified by date_value. |
date_value |
no |
[mm/dd/yyyy],[mm/dd/yyyy] |
Specifies the range of dates if you use custom for date_type. Use the format date1,date2 where date is in either the mm/dd/yyyy (recommended) or mm/dd/yy format. |
type |
no |
email |
Specifies the type of item: e-mail, AIM conversation, web page, or file. |
email_from |
no |
[custom] |
Specifies who an email is from (or, with sent items, who the email is to) |
email_subject |
no |
[custom] |
Specifies the subject of the email. |
aim_conv_with |
no |
[custom] |
Specifies who the AIM conversation is with. |
web_title |
no |
[custom] |
Specifies the web page title. |
web_url |
no |
[custom] |
Specifies the web page URL |
file_extension |
no |
[custom] |
Specifies the file extension in the form xyz (no preceding period necessary). |
file_name |
no |
[custom] |
Specifies the file name. |
terms |
no |
[custom] |
Specifies the basic search terms. These terms are not always required; some other filters can generate searches themselves, including file name and item type. If you omit these terms and it turns out they are required, an invalid search terms error will be written to the output file. |
folder |
no |
[custom] |
Specifies the folder to search in. Use backslashes (\) and DO NOT include a trailing backslash. Thus, a folder should look like this: X:\Folder\Subfolder\LookHere . |
subfolder |
no |
[none] |
The presence of this argument tells the API to include subfolders. |
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"
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"
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]
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.
| Variable | Description |
|---|---|
session |
Google Desktop session ID number. This is the s=________ in Google Desktop URLs |
port |
Google Desktop port number. This is the 127.0.0.1:xxxx in Google Desktop URLs |
URL_Prefix |
This is the prefix that should be prepended to all URLs that are relative to the Google Desktop web pages and thus don't start with http://... This prefix is simply http://127.0.0.1:[port] |
| Variable | Column in gdSuite | Description |
|---|---|---|
result_number |
[none] |
This specifies what the number the result is. This is 1-based, so the first result has a result_number of 1. |
date |
Date |
Google Desktop date/time |
special_url |
[none] |
URL for special action described by special_title |
special_title |
Cached/Threaded |
Describes the special action available for this item. If special_title is [yes] , no special_url will be provided because the open_url performs the action. |
open_url |
[none] |
The URL to open the item. |
path |
Full Path/URL/From/Conversation With |
Full path to file, URL of web page, who the email is from, who the AIM conversation is with. |
type |
Type |
The type of item: E-Mail , AIM , Web Page , or File . |
title |
File Name/Title |
The title of the item. This is the heading the item is listed under in Google Desktop. Usually, this is the e-mail subject, file name, web page title, or AIM conversation title. |
snippet |
Snippet |
This is the snippet of the item that Google Desktop provides . |
raw_data |
[none] |
This is the internal raw data that the API parses, trimmed to include only the HTML for the current result. Due to the size of this data, it is not recommended that you use this variable. The CSV and XML templates that come with the gdSuite API to not include this variable. |
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.
| Variable | Description |
|---|---|
type |
The category of the error. |
description |
The description of the error, as it should be shown to the user. |
extra_info |
Extra information provided for debug purposes. This should usually not be displayed to the user in a dialog box. |
| Variable | Description |
|---|---|
percent |
The estimated percent of the search that gdSuite has conducted. |
done |
The number of results gdSuite has processed. |
total |
The estimated total number of results. |
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
& &
' '
> >
< <
" "
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.