URL Encoding

URLs can only contain a limited set of characters as defined in RFC 3986. Special characters or non-ASCII characters (e.g., German umlauts) must be encoded to avoid conflicts or misinterpretation.

What is URL Encoding?

URL encoding is a method to convert special characters in a URL into a safe format. This is essential because URLs are restricted to specific characters, such as letters (A-Z, a-z), numbers (0-9), and a few symbols (-, _, .).

Characters that do not meet this rule, such as spaces, #, or non-English letters (ä, ë, à), must be encoded. Other characters (e.g., /, ?, &) have specific meanings in URLs and can only be used as encoded values in query parameters.

Encoding replaces each character with a combination of:

1. A percent sign (%).
2. Two hexadecimal digits, representing the ASCII or UTF-8 value of the character.

In the context of the CodeListHub API, this primarily concerns the values and regular expressions in the URL parameters searchTerm, canonicalUri, and canonicalVersionUri.

Which Characters Must Be Encoded?

1. Special Characters and Spaces:

   • A space becomes %20.
   • & becomes %26.
   • = becomes %3D.
   • etc.

2. Non-English Letters (Umlauts, Accents, etc.):

   • ä becomes %C3%A4.
   • ö becomes %C3%B6.
   • à becomes %C3%A0.
   • ë becomes %C3%AB.
   • etc.

3. Other Special Symbols:

   • # becomes %23.
   • + becomes %2B.
   • / becomes %2F.
   • etc.

Example

The following CodeListHub API example returns all document entries whose name begins with ISO:

• Original:

  PowerShell 7Bash

  curl -X GET 'https://api.codelisthub.org/v1/documents/index?searchTerm=^ISO' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json
  

  curl -X GET 'https://api.codelisthub.org/v1/documents/index?searchTerm=^ISO' -H 'accept: text/json' | json_pp
  

• With URL Encoding:

  PowerShell 7Bash

  curl -X GET 'https://api.codelisthub.org/v1/documents/index?searchTerm=%5EISO' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json
  

  curl -X GET 'https://api.codelisthub.org/v1/documents/index?searchTerm=%5EISO' -H 'accept: text/json' | json_pp
  

Here, the circumflex ^ in the regular expression has been encoded as %5E.

Tool

The following tool helps you to encode any value. To do this, type the text into the first text field and click on ‘Encode’.

Encode

You can see the URL encoded result here:

Encoding Tables

Latin Characters with Accents and Diacritics

Special Characters