Single query

This function works the same way as the search function on the Keyword Research website. A query string containing a search term is sent to the database which returns a list of search term combinations containing the original search term, along with the total number of searches, and the number of monthly searches. The query can be customized to return subsets of data via the parameters outlined below. The single query function is available at the URL:
http://api.keyworddiscovery.com/query.php

Parameters:

Query string/search term (required)
Parameter name: query
Aliases: q, search
Description: The search term to perform the query on.
Example: The following query returns results for the phrase airport parking:
http://api.keyworddiscovery.com/query.php?query=airport+parking

Offset
Parameter name: offset
Aliases: o, s, start, start_at
Default: 0
Maximum: 10,000
Values: integers 0 -> ..
Description: The results number at which to start returning records from.
Example: The following query returns results for the phrase airport parking, starting from the 10th result:
http://api.keyworddiscovery.com/query.php?query=airport+parking&offset=10

To obtain 10,000 results, the offset parameter must be used. eg.

To obtain the first 1000 results for the query "airport":
http://api.keyworddiscovery.com/query.php?query=airport&offset=0&limit=1000

To obtain the next 1000 results, use the offset variable to specify the starting point of 1000:
http://api.keyworddiscovery.com/query.php?query=airport&offset=1000&limit=1000

To obtain the next 1000 results, again increment the offset parameter by 1000:
http://api.keyworddiscovery.com/query.php?query=airport&offset=2000&limit=1000
Etc.

Limit
Parameter name: limit
Aliases: l, m, limited_to, maximum
Default: 10
Maximum: 1000
Values: integers 1 -> 1000
Description: The maximum number of results to return.
Example: The following query returns the top 100 results for the phrase airport parking:
http://api.keyworddiscovery.com/query.php?query=airport+parking&limit=100

Compact results
Parameter name: compact
Aliases: c
Default: 1 (on)
Values: 1,0 (on,off)
Description: Returns results with abbreviated fieldname descriptions. E.g. total="1622" will be displayed as t="1622".
Example: The following query returns the results with abbreviated fieldname descriptions for the phrase airport parking:
http://api.keyworddiscovery.com/query.php?query=airport+parking&compact=1

Database
Parameter name: db
Default: premium
Values: historical,premium,news,ebay,shopping,nl,uk (where premium = global premium database and historical = historical global database)
Description: Performs a search over the chosen database. (nl = Dutch)
Example: The following query returns the premium database results for the phrase airport parking:
http://api.keyworddiscovery.com/query.php?query=airport+parking&db=premium

(note: for compatibility purposes, the global parameter returns results from the premium global database)
For more information about the various databases, please see this page: http://www.keyworddiscovery.com/kd-manual6.html

Exclude
Parameter name: exclude
Default: no
Values: keywords separated by a colon for the 'and' operator, and a comma for the 'or' operator.
Description: Excludes keywords from the result set
Example: The following query returns results for the phrase education degree, exlcuding the keywords (distance and online), or user:
http://api.keyworddiscovery.com/query.php?q=Education+Degree&limit=20&exclude=distance:online,user

Show Total
Parameter name: show_total
Default: no
Values: yes (the query will show the total result if this parameter is included in the address, regardless of its value. omitting this parameter altogether will stop the query displaying the total result)
Description: Shows the total found results from the current query.
Example: The following query shows the total number of results for the phrase airport parking:
http://api.keyworddiscovery.com/query.php?query=airport+parking&show_total=yes

Show query total
Parameter name: show_query_total
Default: no
Values: yes (the query will show the total result if this parameter is included in the address, regardless of its value. omitting this parameter altogether will stop the query displaying the total result)
Description: Shows the total number of results for each item in the result set.
Example The following query shows the total number of results for each result for the phrase airport parking:
http://api.keyworddiscovery.com/query.php?query=airport+parking&show_query_total=yes

WARNING: The show_query_total parameter will use an additional api credit per result. For example, if the limit is set to 1000, the total number of API credits used will be 1001. A query using the show_query_total parameter will be slower than other queries due to the need for additional data fetching.

Results

Results are returned as XML. A simple HTTP GET example:

http://api.keyworddiscovery.com/query.php?query=airport+parking&offset=10&limit=15&show_total=yes

This request is for the search term "airport parking", the query will display data starting from the 10th result, and a maximum of 15 results will be returned. By default, compact result display is turned on. The XML returned from this query is shown below:

<?xml version="1.0"?>
<results compact="true" maximum="15" offset="10" query="airport parking" total_found="14944">
  <r m="1028" q="airport parking, gatwick" t="2057" />
  <r m="144" q="dfw airport parking" t="1875" />
  <r m="117" q="airport car parking" t="1759" />
  <r m="122" q="manchester airport parking" t="1710" />
  <r m="135" q="airport parking gatwick" t="1628" />
  <r m="97" q="san diego airport parking" t="1360" />
  <r m="112" q="san jose airport parking" t="1346" />
  <r m="141" q="sacramento airport parking" t="1274" />
  <r m="104" q="seatac airport parking" t="1250" />
  <r m="79" q="logan airport parking" t="1187" />
  <r m="90" q="atlanta airport parking" t="1170" />
  <r m="93" q="detroit metro airport parking" t="1126" />
  <r m="76" q="heathrow airport parking" t="1072" />
  <r m="78" q="laguardia airport parking" t="1021" />
  <r m="66" q="midway airport parking" t="994" />
</results>

Each result is returned as an 'r' tag with the following attributes

q - query string
t - total search
m - monthly estimate. (takes into account a percentage of data that Keyword discovery has in relation to the total number searches done world wide.)

NOTE: Data provided on a URL has to be correctly URL encoded.

< How to access the API | Multiple queries >