freefind
menu   Login

home features pricing search faq library site map policies contact
XML Reference
Library > Reference > XML Reference  
FreeFind subscribers may use our XML feed to get site search results directly from our servers in a format suitable for further programatic processing. Typically, it will be accessed from your web server or from the pages of your website via javascript.

The feed API syntax is such that it can be crafted using a standard HTML form or built from software (either in-page javascript or server side code).

The feed request is implemented using standard HTTP "GET" requests and is stateless; each requests stands alone and does not depend on requests that went before.

The feed may only be accessed in response to a user entering a search term and may not be accessed for robotically generated queries.

The feed may only be accessed by subscription accounts.

 
Contents
Initiating API Requests
Request Parameter Summary
Response DTD
Response Tag Summary
Required Request Parameters
Optional Request Parameters
Other Request Parameters
Response Tags
Usage Example
Parameter and Tag Index
[top]

Initiating API Requests(top)

Requests to the FreeFind XML API are initiated by sending a GET request to:

http://search.freefind.com/find.xml
or
https://search.freefind.com/find.xml
and including a query string with the request parameters.

For example:

https://search.freefind.com/find.xml?si=YOUR_SITE_ID&query=words+to+find

Only subscription accounts may use the XML feed, and only regular site search results are available.

The feed can be used by your server or can be used directly from your javascript code in your website's pages.

Important Note: The feed may only be accessed in response to a user entering a search term and may not be accessed for robotically generated queries.

[top]

Request Parameter Summary(top)

All request parameters must be application/x-www-form-urlencoded.

Required Search Request Parameters
si
site ID (account ID)
and at least one of:
query
q1
q2
q3
q4
user-entered query. matching documents must match the query.
matches must contain all these words (ignored if <query> used)
matches must contain this phrase (ignored if <query> used)
matches must contain any of these words (ignored if <query> used)
matches must not contain any of these words (ignored if <query> used)
Optional Search Request Parameters
asen
csen
dl
dtd
fr
mode
rpp
oq
s
search
srt
stm
xslt
accent sensitivity in matches
case sensitivity in matches
description text length
send DTD (document type definition) with XML output (new)
0-based index of first returned result
matches must contain ANY or ALL query words (only valid with <query>)
results per page
old query for "refine" type search (required if search=these)
subsection selection
type of search: "new", "refine" or "web"
result sorting
stemming (looser word matching) options
send XSLT statement with XML (new)
Other Search Request Parameters
ics
id
input character set (ignored for XML requests)
site ID (account ID) (deprecated. see "si")
[top]

Response DTD(top)

This DTD outlines the structure of the XML response.

<!DOCTYPE ret [
  <!ELEMENT ret (sts, msg?, srch?) >
    <!ELEMENT sts (#PCDATA)>
    <!ELEMENT msg (#PCDATA)>
    <!ELEMENT srch (nttl, nret, idx, q, qe, spell?, spelle?,
                    spelll?, ss?, pl?, nl?, aor?, items?)>
      <!ELEMENT nttl (#PCDATA)>
      <!ELEMENT nret (#PCDATA)>
      <!ELEMENT idx (#PCDATA)>
      <!ELEMENT q (#PCDATA)>
      <!ELEMENT qe (#PCDATA)>
      <!ELEMENT spell (#PCDATA)>
      <!ELEMENT spelle (#PCDATA)>
      <!ELEMENT spelll (#PCDATA)>
      <!ELEMENT ss (s)*>
        <!ELEMENT s (#PCDATA)>
      <!ELEMENT pl (#PCDATA)>
      <!ELEMENT nl (#PCDATA)>
      <!ELEMENT aor (#PCDATA)>
      <!ELEMENT items (i)* >
        <!ELEMENT i (n?, t?, d?, u, tg?, du, dt?)>
          <!ELEMENT n (#PCDATA)>
          <!ELEMENT t (#PCDATA)>
          <!ELEMENT d (#PCDATA)>
          <!ELEMENT u (#PCDATA)>
          <!ELEMENT tg (#PCDATA)>
          <!ELEMENT du (#PCDATA)>
          <!ELEMENT dt (#PCDATA)>
]>
[top]

Response Tag Summary(top)

Response Tags
<aor>
<d>
<dt>
<du>
<i>
<idx>
<items>
<msg>
<n>
<nl>
<nret>
<nttl>
<pl>
<q>
<qe>
<ret>
<s>
<spell>
<spelle>
<spelll>
<srch>
<ss>
<sts>
<t>
<tg>
<u>
mode
description
date
URL
single matching item
0-based index of first item returned in this response
of matching items
message (for status code != 0)
item number (1 based)
next link
number of matches returned in this result
number of matches found
previous link
user query
user query, encoded
returned response object
name of section(s) being searched
spelling suggestion query
spelling suggestion query, URL encoded
link to run spelling suggestion query
returned search results
list of sections being searched
status (error) code
title
link target
click URL
[top]

Required Request Parameters(top)

Parameter: si
For: Account ID (site ID)
Type: String
Value: Assigned when user creates account
[top]

Parameter: query
For: User-entered query
Type: String
Value: <user provided words>
Notes: Only one query value per request allowed.
Simple word list or boolean expression. See search tips for query syntax details.
[top]

Parameter: q1
For: User-entered query. Result matches must contain all of these words
Type: String
Value: <user provided words>
Notes: Ignored if query parameter used
[top]

Parameter: q2
For: User-entered query. Result matches must contain all of these words as a phrase
Type: String
Value: <user provided words>
Notes: Ignored if query parameter used
[top]

Parameter: q3
For: User-entered query. Result matches must contain at least one of these words
Type: String
Value: <user provided words>
Notes: Ignored if query parameter used
[top]

Parameter: q4
For: User-entered query. Result matches must not contain any of these words
Type: String
Value: <user provided words>
Notes: Ignored if query parameter used
[top]

Optional Request Parameters(top)

Parameter: asen
For: Accent sensitivity in matches
Type: String: "y" or "n"
Value: "n" accents are ignored, "y" accents in document must match query
Default: "n"
Notes: Optional
[top]

Parameter: csen
For: Case sensitivity in matches
Type: String: "y" or "n"
Value: "n" case is ignored, "y" case in document must match query
Default: "n"
Notes: Optional
[top]

Parameter: dl
For: Description text length
Type: String: "m", "s" or "l"
Value: "m" normal, "s" short, "l" long
Default: "m"
Notes: Optional
[top]

Parameter: dtd
For: Send DTD (document type definition) with XML output
Type: String: "y" or "n"
Value: "n" do not include DTD with XML results, "y" include DTD
Default: "n"
Notes: Optional
DTD stands for "document type definition", part of the XML standard
[top]

Parameter: fr
For: 0-based index of first returned result
Type: Integer
Value: Any non-negative number
Default: 0
Notes: Optional
[top]

Parameter: mode
For: Matches must contain ANY or ALL query words
Type: String: "any" or "all"
Value: "any" matches must contain any query words, "all" matches must contain all query words
Default: "all"
Notes: Optional
Only used if query field contains data
[top]

Parameter: rpp
For: Results per page
Type: Integer
Value: 1 - 25
Default: 10
Notes: Optional
Only valid for site search results
[top]

Parameter: oq
For: Old query for "refine" type search
Type: String
Value: <user's previous query>
Default:
Notes: Optional
Required if search=these (ie "refining" search results)
[top]

Parameter: s
For: Subsection selection
Type: String
Value: "site" search entire site, "<subsection name>" search specific subsection
Default: "site"
Notes: Optional
May use multiple times in one request to search multiple subsections
[top]

Parameter: search
For: Type of search: "new", "refine" or "web"
Type: String: "new", "these" or "web"
Value: "new" for entirely new search, "these" to search within current results or "web" to search the web
Default: "new"
Notes: Optional
When refining search ("these"), both query and oq fields are used and required
[top]

Parameter: srt
For: Result sorting
Type: String: "r", "d"
Value: "r" sort by relevance, "d" sort by date
Default: "r"
Notes: Optional
See date sorting info in control center before using date sorting
[top]

Parameter: stm
For: Stemming (looser word matching) options
Type: String, "", "n", "en", "pt"
Value: "" (empty string) auto, "n" none, "en" English, "pt" Portuguese
Default: ""
Notes: Optional
[top]

Parameter: xslt
For: Send XSLT statement with returned XML (new)
Type: String URL
Value: URL of XSLT document (fully specified, http://....)
Default:
Notes: Optional
Value must be URL encoded (percent-encoded)
[top]

Other Request Parameters(top)

These parameters still work, but have been replaced with newer versions for new code.

Parameter: ics
For: Input character set (ignored for XML requests)
Type: String
Value: "1" for UTF-8, or a character set name
Default: 1
Notes: The query is expected to be encoded in the given character set (then url encoded)
Only applicable for HTML results. Not relevant for XML results.
[top]

Parameter: id
For: Account ID (site ID)
Type: String
Value: Assigned when user creates account
Notes: Deprecated. See si
[top]

Response Tags(top)

This section lists all possible tags that may be part of an XML response.

Tag: <aor>
For: Indicates auto-or mode occurred
Type: Boolean, "0" or "1"
Value: 0 or 1 or not present (0)
Default: 0
Notes: Only included in returned result when search engine enters auto-or mode
[top]

Tag: <d>
For: Result item description
Type: HTML
Notes: The description consists of illustrative excerpts extracted from the matching document
[top]

Tag: <dt>
For: Result item date
Type: String
Notes: "2006-03-03 22:56:49 GMT", for example
[top]

Tag: <du>
For: Display URL
Type: HTML
Notes: This is a shortened version of the click URL intended for display to the user
[top]

Tag: <i>
For: Contains single matching result item
Type: XML container tag
Value: n? t? d? u tg? du date?
[top]

Tag: <idx>
For: 0-based index of first item returned in this response
Type: Integer
[top]

Tag: <items>
For: List of matching result items
Type: XML container tag
Value: (i)*
Notes:
[top]

Tag: <msg>
For: Error message (when status code != 0)
Type: Text
Notes: If status code == 0, this field is not included in the response
[top]

Tag: <n>
For: Result item number
Type: Integer
Notes: 1-based. Optional
[top]

Tag: <nl>
For: "Next" link
Type: HTML
Notes: Only included when there is another page of results available
[top]

Tag: <nret>
For: The total number of matches returned in this response
Type: Integer
[top]

Tag: <nttl>
For: The total number of matches found
Type: Integer
[top]

Tag: <pl>
For: "Previous" link
Type: HTML
Notes: Only included when there is a previous page of results available
[top]

Tag: <q>
For: User query
Type: HTML
[top]

Tag: <qe>
For: URL encoded user query
Type: HTML
Notes: URL encoded (percent-encoded)
[top]

Tag: <ret>
For: Top level returned response object
Type: XML container tag
Value: sts msg? srch
[top]

Tag: <s>
For: Name of section being searched
Type: Text
[top]

Tag: <spell>
For: Spelling suggestion query
Type: HTML
Notes: Optional query suggestion value. Would replace query value in its entirety.
[top]

Tag: <spelle>
For: Spelling suggestion query, URL encoded
Type: HTML
Notes: Optional URL encoded query suggestion value. Would replace query value in its entirety.
[top]

Tag: <spelll>
For: Optional link to run spelling suggestion query
Type: HTML
[top]

Tag: <srch>
For: Returned search results
Type: XML container tag
Value: nttl nret idx q spell? ss? aor? items?
[top]

Tag: <ss>
For: List of sections being searched
Type: XML container tag
Value: (s)*
[top]

Tag: <sts>
For: Status (error) code
Type: Number
Value: 0 = no error, results returned
1 = other error (more details in msg)
2 = unauthorized access error
3 = account closed (or account ID invalid) error (details in msg)
4 = invalid parameter(s) in request (details in msg)
[top]

Tag: <t>
For: Title of a result item
Type: HTML
[top]

Tag: <tg>
For: Result item link target
Type: HTML
Notes: "", "_blank", "myframe", etc. Used with u
[top]

Tag: <u>
For: Result item click URL
Type: HTML
Notes: Target for link, if any, is in tg tag
[top]

Example(top)

Request:

https://search.freefind.com/find.xml?si=3225682&rpp=3&query=exlude+part+of+page
Response:
[top]

Parameter and Tag Index(top)

XML Request Parameters
asen  csen  dl  dtd  fr  ics  id  mode  oq  q1  q2  q3  q4  query  rpp  s  search  si  srt  stm  xslt 
XML Response Tags
<aor>  <d>  <dt>  <du>  <i>  <idx>  <items>  <msg>  <n>  <nl>  <nret>  <nttl>  <pl>  <q>  <qe>  <ret>  <s>  <spell>  <spelle>  <spelll>  <srch>  <ss>  <sts>  <t>  <tg>  <u> 

 

login home features pricing search faq library sitemap policies contact
FreeFind and FreeFind.com are trademarks of FreeFind.com.
Copyright 1998 - 2017