View Categories

How to Handle Special Characters in API Queries

4 min read

When you submit an API request, the data you are sending to Trestle may contain special characters like pluses (+), dashes (-), or parentheses (()). Other special characters could be included in names, phone numbers, addresses, or email addresses, and depending on whether they need to be considered in your request, the special characters may need to be encoded before it’s sent in the request.

When is encoding necessary? #

Encoding special characters ensures that our system interprets your data correctly. Unencoded special characters may interfere with the parsing of your request, resulting in errors or unintended outcomes.

However, many special characters that might require encoding for us to see are not currently necessary. The most common example is with phone numbers. Pluses, dashes, and parentheses are not required for Trestle to process your request accurately, as they don’t change the results. Encoding spaces in names is also unnecessary, as this type of input is expected and received properly without adding encoding for the space. Some examples of importance are if you receive an email address with a “+” in the address. This character indicates a tumbled email address, and we won’t recognize the email address correctly without the “+” encoded as %2B.

If you were to submit a Real Contact API request for the email address test+email@email.com without encoding, the request would be received as test email@email.com.

Common Special Characters and Their Encoding #

Common special characters you might encounter when submitting data include:

  • Plus (+): %2B
  • Parentheses ((, )): %28, %29
  • Ampersand (&): %26
  • Percentage (%): %25
  • Space ( ): %20
  • Comma ( , ): %2C
  • Apostrophe ( ‘ ): %27
  • At symbol (@): %40
  • Number sign (#): %23

How to Encode a Special Character in a Request #

Encoding special characters involves converting them to a standardized format (URL Encoding). 

For example:

  • Plus (+) becomes %2B
  • Parentheses ((, )) become %28, %29
  • Ampersand (&) becomes %26

We can use the above email example to illustrate this (test+email@email.com).

Here is a sample URL without encoding: #

https://api.trestleiq.com/1.1/real_contact?email=test+email@email.com&name=Test Name

Here is a sample URL with encoding: #

https://api.trestleiq.com/1.1/real_contact?email=test%2Bemail@email.com&name=Test Name

Here is a Java request without encoding: #

import java.net.HttpURLConnection;
import java.net.URL;

public class JavaUrlWithoutEncoding {
    public static void main(String[] args) throws Exception {
        String urlString = "https://api.trestleiq.com/1.1/real_contact?email=test+email@email.com&name=Test Name";
        URL url = new URL(urlString);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod("GET");
        connection.connect();
        System.out.println("Response Code: " + connection.getResponseCode());
    }
}

Here is a Java request with encoding: #

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;

public class JavaUrlWithEncoding {
    public static void main(String[] args) throws Exception {
        String email = "test+email@email.com";
        String name = "Test Name";

        // URL encode the email and name
        String encodedEmail = URLEncoder.encode(email, "UTF-8");
        String encodedName = URLEncoder.encode(name, "UTF-8");

        String urlString = "https://api.trestleiq.com/1.1/real_contact?email=" + encodedEmail + "&name=" + encodedName;
        URL url = new URL(urlString);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod("GET");
        connection.connect();
        System.out.println("Response Code: " + connection.getResponseCode());
    }
}

Here is a Python request without encoding: #

import requests

url = "https://api.trestleiq.com/1.1/real_contact?email=test+email@email.com&name=Test Name"
response = requests.get(url)
print("Response Code:", response.status_code)

Here is a Python request with encoding: #

import requests
import urllib.parse

email = "test+email@email.com"
name = "Test Name"

# URL encode the email and name
encoded_email = urllib.parse.quote(email)
encoded_name = urllib.parse.quote(name)

url = f"https://api.trestleiq.com/1.1/real_contact?email={encoded_email}&name={encoded_name}"
response = requests.get(url)
print("Response Code:", response.status_code)

You can add a feature in your integration to identify these special characters before you submit a request and swap it out for the encoded version. This will ensure you send us exactly what you want to validate or search.

If you have any additional questions about how to handle URL encoding in your integration, please email us at support@trestleiq.com.