Retrofit 2 — Adding & Customizing the Gson Converter

In our last Retrofit post we've given you an introduction to converters. In this blog post, we want to dive deeper into the most common format: JSON. After demonstrating the integration of the Gson converter, we'll also show you how to customize Gson's mapping rules.

If you prefer to catch up with other Retrofit topics first, give our outline a look:

Retrofit Series Overview

  1. Callbacks (Coming soon)
  2. Annotations (Coming soon)
  3. Fluent Interface with Builders (Coming soon)

Integrate a JSON Converter

A common representation of the data received from the server is the JavaScript object notation: JSON. HTTP’s response body contains any information and Retrofit parses the data and maps it into a defined Java class. This process can be kind of tricky, especially when working with custom formatted dates, nested objects wrapped in lists, and so on …

As we’ve mentioned in our Upgrade Guide, Retrofit doesn’t ship with an integrated JSON converter anymore. We need to include the converter manually. For those of you, who already worked with Retrofit 2, you’ve probably edited your build.gradle. In case you haven’t done that yet, it’s the time to do it now:

dependencies {  
    // Retrofit & OkHttp
    compile 'com.squareup.retrofit2:retrofit:2.1.0'

    // JSON Converter
    compile 'com.squareup.retrofit2:converter-gson:2.1.0'

Google’s Gson is a very popular JSON converter. Almost every real-world JSON mapping can be done with the help of Gson. Once you’ve added the Gradle dependency to your project you’ve to activate it on your Retrofit instance. Only then Retrofit will consider using the converter.

Retrofit retrofit = new Retrofit.Builder()  

GitHubService service = retrofit.create(GitHubService.class);  

The converter dependency provides a GsonConverterFactory class. Call the created instance of that class (done via create()) to your Retrofit instance with the method addConverterFactory(). After you’ve added the converter to Retrofit, it’ll automatically take care of mapping the JSON data to your Java objects, as you’ve seen in the previous blog post. Of course, this works for both directions: sending and receiving data.

The advantage of Gson is that it usually needs no setup in your Java classes. Nevertheless, there are notations for some edge cases. If your app requires Gson to do something special, head over to the Gson project to look up the details.

Customize Your Gson Configuration

We want you to know that Gson has plenty of configuration options. Please go through the official User Guide, if you want to get an overview over all the options.

The good news is that Retrofit makes it very easy to customize Gson. You don’t even need to implement your own custom converter, which we’ll look at later in another blog post. In the previous section, we’ve explained that you can add the Gson converter like this:

Retrofit retrofit = new Retrofit.Builder()  

We didn’t tell you, that you can pass a Gson instance to the GsonConverterFactory.create() method. Here’s an example with various Gson configurations:

 Gson gson = new GsonBuilder()
     .registerTypeAdapter(Id.class, new IdTypeAdapter())

Retrofit retrofit = new Retrofit.Builder()  

If you pass a Gson instance to the converter factory, Retrofit will respect all of your configurations. This makes it very easy to do the fine-tuning of your JSON mapping with Gson, while keeping the actual code changes to a minimum.


In this blog post, you've learned how to add Gson as a JSON converter to Retrofit 2. Additionally, you've seen how you can utilize the wide array of options of Gson. Retrofit makes it very easy to customize the Gson mapping rules.

Explore the Library

Find interesting tutorials and solutions for your problems.