Find Similar Domains API

This API search all domains for sale that are similar to the specified domains. Search both aftermarket listings and unregistered domains by default. May also be used to search previous sales. The API returns results as a JSON array by default.

You must specify a valid application ID with each request. You can view, request or reset your application ID via the developer program page of MyUpname.

For example, to retrieve all available domains similar to LasikSurgery.com within the .COM or .NET extensions, you would use /search/api/domsimilar.php?dn=LasikSurgery.com&tld=com+net&pid=YOURPID. Replace YOURPID with your own PID. View or Request your partner ID.

Query Parameters

The only mandatory parameters are:

  • dn: the domain name to search similar of, including extension. Case insensitive.
  • tld: space-delimited string of domain extensions to filter results to, for example &tld=com+net+org. Do not include the heading dot. The entire TLD must be passed. For example specifying &tld=uk may return somedomain.uk, but not somedomain.co.uk. The extension of the domain int he &dn= will always be considered as well.
  • pid: your unique partner ID. Request your partner id.

You may also tailor your search with the following parameters:

  • hs=1: Set to 1 to search historical sales only, regardless if the domain is currently for sale or not. If not specified, the API only returns domains that are currently available for sales (or free for registration), regardless if they had previous sales or not.
  • num: nb of results to return. Defaults to 5. Maximum is 100.
  • output=xml to return results as XML. Default is to return results as a JSON array.

Result array

Valid queries with at least one result will return as a JSON-formatted array of matching domains, UTF-8 encoded.

The array will have 2 elements plus the array with actual similar domains and details of the sale offer:

  • STATUS: 'OK' if success, or "Ennn" if error. See below for error messages.
  • SEARCH: The full-text description of the search, including filters.
  • the status and summary of the search, and the sub-array containing all the results. The sub-array is ordered according to the sorting option specified (or by relevance if no sorting option was passed int he query).

Within the result array, each item will be an array containing relevant information about the domain:

  • name: the name of the domain, without the extension.
  • tld: extension of the domain, for example 'com' or 'co.uk'.
  • language: ISO639 code of the languageof the domain, or blank if no language can be associated to the domain.
  • catid: numerical ID of the most relevant category of the domain. Optional.
  • idn: 1 if domain is an IDN, 0 if not.
  • status: Returns 'open' if the domain is for sale in the aftermarket, or 'free' if the domains is freely available for registration. If you had &hs=1 in the query, results that are no longer for sale will have status 'closed'.
  • seller: name of the seller of the domain, or the marketplace where the domain is/was listed for sale.
  • type: type of the listing, one of: 'auction','dutch','live','makeoffer','buyitnow','preorder'
  • orig: Returns "own" if the domain is sold by owner, "exp" if this is an expiring domain, or "drop" if a deleted domain.
  • star: date the domain was last listed for sale or the auction started, YYYY-MM-DD. Optional.
  • enddate: date the sale/auction is scheduled to end, or when the domain was sold, YYYY-MM-DD HH:MM:SS. If none, listing is "until closed by seller".
  • bid: Current minimum bid, or initial bid. For non-auction types, this is the reserve price. Float. Optional.
  • price: Buy-now price. Float. Optional.
  • sold: Final price the domain sold at. Only applicable for domains where type is 'closed'.
  • currency: ISO currency symbol for all price data for this domain. Optional.
  • reservemet: 1 if the reserve or minimum price was met, 0 otherwise. Only if reserve.
  • nbbids: number of bids or offers. Optional.

Error Messages

If the status field is different from 'OK', it will contain an error message with the format "Ennn description", where nnn is the code of the error and description the full textual description of the error. Below are all possible values returned on error:

  • E001: System not available, please try again later.
  • E002: No more credit available. Please purchase more credits.
  • E003: Not a valid application key. Please login to MyUpname and check your developer credentials.
  • E300: Not a valid domain name.

Query Cost

Each call consumes one query-credit per domain returned.