2. Tutorials
  3. Retrofit 2 — Add Multiple Query Parameter With QueryMap

Retrofit 2 — Add Multiple Query Parameter With QueryMap

Adding request parameters can be kind of pain in the a** if your service methods allows multiple query parameters which also can be optional. We’ve published an article describing how to use optional query parameters. Today, we’re going to simplify the handling of multiple query parameters by introducing and using the @QueryMap annotation.

Retrofit Series Overview

  1. Getting Started and Creating an Android Client
  2. Basics of API Description
  3. Creating a Sustainable Android Client
  4. URL Handling, Resolution and Parsing
  5. How to Change API Base Url at Runtime
  6. Multiple Server Environments (Develop, Staging, Production)
  7. Share OkHttp Client and Converters between Retrofit Instances
  8. Upgrade Guide from 1.9
  9. Beyond Android: Retrofit for Java Projects
  10. How to use OkHttp 3 with Retrofit 1
  1. Synchronous and Asynchronous Requests
  2. Send Objects in Request Body
  3. Add Custom Request Header
  4. Manage Request Headers in OkHttp Interceptor
  5. Dynamic Request Headers with @HeaderMap
  6. Multiple Query Parameters of Same Name
  7. Optional Query Parameters
  8. Send Data Form-Urlencoded
  9. Send Data Form-Urlencoded Using FieldMap
  10. How to Add Query Parameters to Every Request
  11. Add Multiple Query Parameter With QueryMap
  12. How to Use Dynamic Urls for Requests
  13. Constant, Default and Logic Values for POST and PUT Requests
  14. Cancel Requests
  15. Reuse and Analyze Requests
  16. Optional Path Parameters
  17. How to Send Plain Text Request Body
  18. Customize Network Timeouts
  19. How to Trust Unsafe SSL certificates (Self-signed, Expired)
  20. Dynamic Endpoint-Dependent Interceptor Actions
  21. How to Update Objects on the Server (PUT vs. PATCH)
  22. How to Delete Objects on the Server
  1. Ignore Response Payload with Call<Void>
  2. Receive Plain-String Responses
  3. Crawl HTML Responses with jspoon (Wikipedia Example)
  4. Loading Data into RecyclerView and CardView
  1. Introduction to (Multiple) Converters
  2. Adding & Customizing the Gson Converter
  3. Implementing Custom Converters
  4. How to Integrate XML Converter
  5. Access Mapped Objects and Raw Response Payload
  6. Supporting JSON and XML Responses Concurrently
  7. Handling of Empty Server Responses with Custom Converter
  8. Send JSON Requests and Receive XML Responses (or vice versa)
  9. Unwrapping Envelope Responses with Custom Converter
  10. Wrapping Requests in Envelope with Custom Converter
  11. Define a Custom Response Converter
  1. Simple Error Handling
  2. Error Handling for Synchronous Requests
  3. Catch Server Errors Globally with Response Interceptor
  4. How to Detect Network and Conversion Errors in onFailure
  1. Log Requests and Responses
  2. Enable Logging for Development Builds Only
  3. Log Network Traffic with Stetho and Chrome Developer Tools
  4. Using the Log Level to Debug Requests
  5. Analyze Network Traffic with Android Studio Profiler
  6. Debug and Compare Requests with RequestBin
  1. Introduction to Call Adapters
  2. Custom Call Adapter to Separate OnResponse Callback
  3. How to Integrate RxJava 1.x Call Adapter
  4. How to Integrate RxJava 2.x Call Adapter
  5. How to Integrate Guava Call Adapter
  6. Custom Call Adapter to Separate Network and Gson Errors
  1. Pagination Using Query Parameter
  2. Pagination Using Link Header and Dynamic Urls (Like GitHub)
  3. Pagination Using Range Header Fields (Like Heroku)
  1. How to Upload Files to Server
  2. How to Upload Multiple Files to Server
  3. How to Upload a Dynamic Amount of Files to Server
  4. Upload Files with Progress
  5. Passing Multiple Parts Along a File with @PartMap
  6. How to Download Files from Server
  7. Download Files with Progress Updates
  8. How to Upload Files to Server
  1. Basic Authentication on Android
  2. Token Authentication on Android
  3. OAuth on Android
  4. Hawk Authentication on Android
  5. How to Refresh an Access Token
  1. Activate Response Caching (Etag, Last-Modified)
  2. Check Response Origin (Network, Cache, or Both)
  3. Force Server Cache Support with Response Interceptor
  4. Support App Offline Mode by Accessing Response Caches
  5. Analyze Cache Files
  1. Basics of Mocking Server Responses
  2. Customizing Network Behavior of Mocked Server Responses
  3. Mock APIs with JsonServer
  1. Callbacks
  2. Annotations
  3. Fluent Interface with Builders

What is @QueryMap in Retrofit?

Retrofit uses annotations to translate defined keys and values into appropriate format. Using the @Query("key") String value annotation will add a query parameter with name key and the respective string value to the request url (of course you can use other types than string :)).

Actually, there are APIs with endpoints allowing you to pass (optionally) multiple query parameters. You want to avoid a service method declaration like the one below with “endless” options for request parameters:

public interface NewsService() {  
    @GET("/news")
    Call<List<News>> getNews(
            @Query("page") int page,
            @Query("order") String order,
            @Query("author") String author,
            @Query("published_at") Date date,
            …
    );
}

You could call the .getNews service method with null values for each of the parameters to make them optional. Retrofit will ignore null values and don’t map them as query parameters. However, there is a better solution to work with complex API endpoints having various options for query parameters. Don’t worry, Retrofit got you covered!

How to Use QueryMap

The @QueryMap annotation expects a Map with key-value-pairs of type String. Each key which has a non-null value will be mapped and you can dynamically add your desired query parameters.

public interface NewsService() {  
    @GET("/news")
    Call<List<News>> getNews(
        @QueryMap Map<String, String> options
    );
}

If you want to request the news from page 2 of author Marcus, you only need to add the map entries for page and author. There’s no need to worry about the other available options.

The following snippet illustrates how to execute the actual request to fetch the news.

private void fetchNews() {  
    Map<String, String> data = new HashMap<>();
    data.put("author", "Marcus");
    data.put("page", String.valueOf(2));

    // simplified call to request the news with already initialized service
    Call<List<News>> call = newsService.getNews(data);
    call.enqueue(…);
}

The resulting url with the assumed example (page 2 of Marcus):

http://your.api.url/news?page=2&author=Marcus

QueryMap Options

The @QueryMap annotation has an option field for encoding:

  • encoded: can be either true or false; default is false

You can set the value for encoding like this:

Call<List<News>> getNews((@QueryMap(encoded=true) Map<String, String> options);

Enabling encoding will encode individual characters before appended to the request url. Using the key author with value marcus-poehls will result in the following encoded url: author=marcus%2Dpoehls.

Setting encoding to false (by default), the url for the example above would be author=marcus-poehls.

Outlook

Retrofit’s @QueryMap annotation is a convenient way to add multiple query parameters to a request without pre-defining their actual names. That gives you more freedom for requests by just passing the map with key-value-pairs to the service method, but doesn’t show you which options are available. It’s up to you to read the API documentation. We hope you’ve having a commendable backend developer :)

Marcus Pöhls

Marcus is a fullstack JS developer. He’s passionate about the hapi framework for Node.js and loves to build web apps and APIs. Creator of Futureflix and the “learn hapi” learning path.

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous