Site.eu

How to order domain names with punycode via the API

4 min read

How to order domain names with punycode via the API

Want a domain name with special characters, like münchen.de or café.fr? On the internet, such a domain name is written in punycode: only plain letters, digits and hyphens, starting with xn--. So münchen.de becomes xn--mnchen-3ya.de.

You order these domain names with the same API calls as any other domain name. This guide explains what's different. New to ordering through our API? Then first read how to order domain names with the API.

Step 1: convert the domain name

Send the domain name the way you write it. You don't need an API key for this:

POST https://backend.site.eu/v2/domain_names/punycode
Content-Type: application/json

In the body, you send input, for example münchen.de. The answer gives:

  • punycode: the domain name in punycode, like xn--mnchen-3ya.de.
  • language_codes: only when the extension asks for the language of the domain name. Below, you read how to pick the right code.

We also check whether the extension allows these characters. Not every extension does: .nl, for example, has no domain names with special characters. Then you get an error, and supported_tlds lists the extensions that do allow them.

Want to know first whether an extension takes special characters at all? Then ask for the extension, without the dot. You don't need an API key for this either:

GET https://backend.site.eu/v2/tlds?extension=com

Does the answer say isIDN: true? Then the extension takes domain names with special characters.

Does the extension ask for a language?

Look at the answer of step 1:

  • No language_codes in the answer? Then the extension doesn't ask for a language. You don't send language_code.
  • language_codes in the answer? Then pick the code of the language your domain name is in. You send it in step 3.

The list only gives the codes, and each registry writes them its own way. Some use two small letters, like de for German. Others use three capital letters, like GER for .com and .net. Copy the code exactly as it is in the list, with the same capital or small letters.

These are the codes for our languages:

  • Dutch: nl or DUT
  • German: de or GER
  • French: fr or FRE
  • Spanish: es or SPA
  • Polish: pl or POL
  • Swedish: sv or SWE
  • Slovenian: sl or SLV
  • Croatian: hr or SCR

Is the code for your language not in language_codes? Some extensions also have codes for a whole alphabet, like latn or und-Latn for the Latin alphabet, or cyrl for the Cyrillic alphabet. Then pick the one for the letters in your domain name. No code fits? Then this extension doesn't take domain names in your language. Choose another extension.

Step 2: check if it's still free

GET https://backend.site.eu/v2/domain_names/check_availability?domain_name=xn--mnchen-3ya.de

Use the punycode here. It has no special characters, so it fits in the web address as it is. This call doesn't need an API key either.

Step 3: order it

POST https://backend.site.eu/v2/domain_names/register
X-API-Key: your API key
Content-Type: application/json

In the body, you send domain_name, in punycode or the way you write it. We always save it in punycode. Your API key needs domains.order.create, as for every domain name order.

Did step 1 give language_codes? Then also send language_code, with the code you picked. For müller.com, that's GER (German). A code that isn't on the list is refused, and nothing is charged.

A transfer works the same way, with POST /v2/domain_names/transfer. Everything else works as for any other domain name: dry_run, the Idempotency-Key, expected_price and the error codes. So test with dry_run first.

Good to know

  • Capital letters become small letters. MÜNCHEN.de and münchen.de are the same domain name.
  • ß and ss are different. straße.de (xn--strae-oqa.de) and strasse.de are two separate domain names.
  • Want the special characters back? POST /v2/domain_names/unicode turns punycode back into the normal spelling. So xn--mller-kva.com becomes müller.com. No API key needed.
  • Some programs show the punycode. Some email programs and older browsers show xn--mnchen-3ya.de instead of münchen.de. Both lead to the same website.

Need help? Contact us by WhatsApp, Telegram or email.

Couldn’t find what you were looking for?

You can always chat with one of our experts for any questions you might have!

New articles added