Search methods

Given an example DNS record like the following using the bind zone file format:

RRNAME RRCLASS RRTYPE RDATA
domain.name.tld IN A 1.2.3.4
domain.name.tld IN CNAME. another.domain.name.tld.

we can clearly identify four data types, one per column, defined in this document as:

  • rrname

  • rrclass

  • rrtype

  • rdata

A label is defined as a portion of a fully qualified domain name (FQDN) between two dots. For example: www.deteque.com has three labels (www, deteque and com)

There are two main search methods:

  • The forward search is used to query over the rrname field.

  • The reverse search is used to query over the rdata field.

To access the two search methods, the URL paths are:

  • for the forward search the URL is /v2/_search/rrset/

  • for the reverse search the URL is /v2/_search/rdata/

Query Parameters and Modifiers

The supported query parameters are:

  • stype (search type):

    • em (Exact match) - This is the default value and searches for an exact match in the database.

    • rm (Right match) - Performs a “right match” searching for the records which have the requested string on the rightmost side. (example: *.google.com)

    • lm (Left Match) - Performs a “left match” searching for the records which have the requested string on the leftmost side. (example: www.google.*)

    • wm (Word Match) - Searches for a single string in the target field

    • fm (Fuzzy Match) - Searches for similar domain names using a fuzzy heuristic (forward search only)

  • first_seen_gt - Searches for the first seen Unix timestamp greater than this parameter.

  • first_seen_lt - Searches for the first seen Unix timestamp smaller than this parameter.

  • last_seen_gt (default: last 30 days) - Searches for the last seen Unix timestamp greater than this parameter.

  • last_seen_lt - Searches for the last seen Unix timestamp smaller than this parameter.

  • limit: Defines the maximum number of records returned by the API call. The default limit is 100. The maximum is 10000 and depends on the account type.

  • verbose: Enables use of the first_seen field which is disabled by default. Please note that this operation can have a considerably longer response time and should only be used if required. If verbose is required it is strongly recommended to set a high limit value. Otherwise with large result sets timeouts may occur.

  • format: Please see content negotiation

  • idn: Please see Internationalized domain name search

  • fuzziness: Please see Fuzzy march search type

Content negotiation

The API response follows the best practices for RESTful interfaces: the returned document format will depend on the content of the request Accept header.

Below are details of how you can change the output using the format URL parameter which may have the following values:

  • html => corresponds to an Accept header containing text/html,

  • xml => corresponds to an Accept header containing application/xml,

  • json => corresponds to an Accept header containing application/json,