Home » Android » java – Why Retrofit cannot encode properly query string with square brackets?

java – Why Retrofit cannot encode properly query string with square brackets?

Posted by: admin June 15, 2020 Leave a comment


I’m using Retrofit for my network layer in my Android app, but I have a problem with the URL encoding.

I have to call an REST API like that:


as you can see the query string is composed by some different kind of parameters, so I decided to use the @QueryMap annotation in the Retrofit Interface with a Map<String, String> where
q, param[1], param[0], other_param are String keys of the map

What do I expect?
I expect the square brackets in the URL are encoded with %5B for '[' and %5D for '[', but this does not happen.

Why does this happen? The square brackets should be encoded with percent encoding. Is this a bug or I’m doing something wrong? I also tried the @EncodedQueryMap annotation with no differences.

How to&Answers:

Query names are never URL encoded.

The documentation for @QueryMap states:

Values are URL encoded.

And for @EncodedQueryMap:

Values are not URL encoded.

However, I just submitted a pull request to change this behavior a bit. I am adding support for encoding keys by using @Query(value = "..", encodeName = true) or @QueryMap(encodeNames = true).


I just had to deal with @QueryMap encoding everything but {}[]. Most of the time I don’t mind because I rarely send json in the query, and want to push the encoding down as low as possible in my application’s stack, but recently I had to add an endpoint just like Ivan describes. My solution was to add an interceptor that does this:

Request originalRequest = chain.request();
HttpUrl url = originalRequest.url();
String urlFilePath = url.encodedPath();
if(url.encodedQuery() != null) {
    // Because Retrofit doesn't think "{}[]" should be encoded
    // but our API does
    String correctlyEncodedQuery = correctlyEncodeQuery(url);
    urlFilePath += "?" + correctlyEncodedQuery;
URL correctUrl = new URL(url.scheme(), url.host(), url.port(),
Request newRequest = originalRequest.newBuilder()

private String correctlyEncodeQuery(HttpUrl url) throws UnsupportedEncodingException {
    String retVal = "";
    for(String queryKey : url.queryParameterNames()){
        if(retVal.length() > 0){
            retVal += "&";
        String queryValue = url.queryParameter(queryKey);
        retVal += queryKey + "=" + URLEncoder.encode(queryValue, "utf-8");
    return retVal;


Try simple one
and parameters @Query


Moreover, if value contains JSONArray with JSONObject, retrofit doesn’t encode brackets [ ] { }

Map contains element:

key = filter, 
value = [{"field":"some_field","value":"some_value","operator":"="}]

And @QueryMap send


QueryMap used there because of number params in GET request and objects in filter option.