UpName Domain Search

Use this API to search available domains using the award-winning domain search technology from UpName. Specify search criteria within the URL. Returns matching domains as a JSON array by default. Query parameters are the same as for advanced filtering when using the UpNname.com main site, except you must replace /search/srp.php with /search/api/srp.php.

You must include your private application ID as &pid= in the query URL. View or Request your partner ID.

For example, to search for "camera or camcorder" within .COM domains only, you would use /search/srp.php?q=camera+or+camcorder&tld=COM to return results as HTML, and /search/api/srp.php?q=camera+or+camcorder&tld=COM&pid=YOURPID to return the same set of results as a JSON array.

Query Parameters

There are 2 ways of specifying the query string. First method is to use the single &q= parameter with the search text you would input in the search box.

• q: the search string, up to 64 characters, UTF-8. The search string will be parsed for the logical operator OR, as well the the string in quotes (exact matches). Domain name in the search string will be recognized and only results of the same TLD will be returned. All other non-alphanumerical characters will be ignored and interpreted as spaces.

Alternativaley (and preferably) the search string can be broken down into AND words, OR words and exact match, similarly to how the search options are displayed in the advanced search page:

• and: space-delimited list of words to search, up to 64 characters, UTF-8. All words provided will be treated as with the logicla operator AND. Must contain only alphanumerical characters.
• or: space-delimited string of OR words to search, up to 64 characters, UTF-8. Must contain only alphanumerical characters.
• exact: space-delimited string of words that must appear within the domain name exactly as entered

For example, specifying a search as &q=bond+or+stock+investing+"ibm" is the same as &and=investing&or=bond+stock&exact=ibm. Using the latter makes for slighly faster queries.

All additional optional filters and sorting options on the advanced search page can also be used:

• kord: Set to 1 to force higher ranking to domains that show the searched words in the same order as in the query string. Only meaningful when sorting by relevance and at least 2 search keywords are privded.
• start: Set to 1 to force higher ranking to domains that start with one of the searched words. Only when sorting by relevance.
• nosyn: Set to 1 to prevent the search algorithm from considering synonymous of searched words. Only when sorting by relevance.
• tld: space-delimited string of tlds to filter results to, without the heading dot. The entire TLD must be passed. For example specifying &tld=uk may return somedomain.uk, but not somedomain.co.uk. By default, all TLDs may be returned in the result set.
• hs=1: search historical sales only, regardless if the domain is currently for sale or not. If not specified, the search API only returns domains that are currently available for sales, regardless if they had previous sales or not.
• primin: The minimum price of domains to return. Must be a numerical value. For search domain for sale (no &hs= paramter), this will be the buy-now price of the domain, or the reserve price or highest bid price if auction. Domains that have no pricing information (notably, domains open for offers with no reserve price) will not be returned if you pass this parameter. For historical sales (&hs=1), the price the domain was sold at will be used. The currency used will be always the currency the domain was trading at. By default, domains with any pricing are returned.
• primax: Same as primin, but for the maximum price fo the domain. Must be a numerical value greater than primin. Note that if you specify &primax=0, only free domains (unregistered) will be returned. You cannot use &primax=0 in conjunction with &hs=1.
• showfree: Set to 1 to only return premium domains, or to 0 to only return free (unregistered) domains. If omitted, both premium and free domains will be returned when applicable.
• hassale=1: only return domains that have at least one previous sale.
• hasappr=1: only return domains that have at least one independant appraisal.
• hotauc=1: only include domains that are classified as "hot auctions". Hot auctions are domain auctions (including preorders) that are attracting a high volume of bids or high bid price.
• type: space-delimited list of events type to consider. Each type must be one of: 'auction','dutch','live','makeoffer','buyitnow','preorder'. Ignored if &primax=0. Default is to consider all event types.
• len: Maximum number of characters of the domain names to return. Character count refers to the SLD only. Must be a numeric value 2 or greater. Default is to return all domain length.
• lenw: Maximum number of words in the domain names to return. Note that one-letter strings and very common words are not included in the word count. For example TheDomainX.com will be considered as one word (both "the" and "X" are not considered words). Must be a numeric value. Default is to return all domain length.
• pat: specify domain name pattern such as consonant-vowel-consonant-vowel (CVCV). When constructing the pattern, you can use uppercase C to mandate a consonant, V for a vowel, L for any letter, N for a number. For example if you specify pat=NNN, the API will only return domain names that are made of exactly 3 digits, such as 234.com or 777.net. If you enter a lowercase letter or a digit or a dash, then the specified character must appear in the domain name at that position. For example "19NN" will only match year from the 20th century. Both the len and lenw parameters are ignored if you specify a pattern.
• catid: space-delimited list of category ID to filter to. Each category, either first or second level, has a unique ID. Refers to /search/browsecat.php for all available categories. The ID for a category is the catid parameter of each link on the page.
• hyphen: Set to 1 to filter out domains with dashes from results
• number: Set to 1 bool if filter out domains with digits
• idn=1: to filter out IDN domains. If not specified, all domains are searched.
• lang: space-delimited string of 2-char language codes. Language code should conform to ISO 639 standards. Also include 'all' to return all domains that cannot be reliably associated to one or several language. For example, &lang=fr+it+all will return all domains that are either French, Italian, or unclassified. We recommend including 'all' in all requests as few domains can be reliabily associated to specific languages. Default is returning all language.
• added: Oldest date (YYYY-MM-DD) the domain was last put for sale. For example &added=2009-02-10 will only return domains added since Feb 10, 2009.
• pf: Name of seller or the marketplace the domain is/was listed for sale. Default is to return domains from all sellers. For example &pf=ebay will only return domains listed for sale on eBay. &pf=fab will return domains sold by Fabulous Inc.
• orig: filter to expired domains ("exp"), deleted domains ("drop") and/or domains on sale by their owner ("own"). For example &pf=drop+exp will returned only domains that are expiring or deleting. If you specify &orig=, no free domain will be returned.
• sort: sort option. Can be "rel" (sort by relevance), "name" (sort by name, numbers then A to Z), "-name" (Z to A), "tld" (by extension), "-tld", "nbchars" (by number of character in name, shorter first), "nbwords" (by number of words), "bidprice" (by price, either current bid or sale value or asking price, lowest first), "-bidprice" (same, highest first), "-open" (by listing date, most recent first), "close" (by close date, soonest first), "semscore" (by CPC value of the keywords in the name, highest first), "trafscore" (by pagerank and search engine or type-in traffic). Default is sorting by relevance in most cases.
• num: nb of results to return per page. Defaults to 30. Maximum is 200.
• output: Set to "xml" to return results as XML. Default is to return results as a JSON array.

Note that UpName may ignore some parameters when the search query does not make sense. For example asking for &orig=exp&showfree=1 will ignore the second parameter, since expired domains cannot be free.

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 search results:

• 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: SLD of the domain.
• 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 still for sale, 'closed' if not, or 'cancelled' if the sales listing has been cancelled by the seller. Returns 'free' if the domain is freely available for registration. If you had &hs=1 in the query, all results should normally have status 'closed'. Inversly, if you didn't have &hs=1, then all results should be status='open' or 'free'
• 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.
• E100: Not a valid query. Please refer to the search API documentation.

Query Cost

Each call consumes one query-credit per domain returned.