Gson Example Tutorial Parse JSON

Filed Under: Java

Welcome to Gson Example Tutorial. In last post we looked at the Java JSON API and you can easily tell that it’s not convenient to use it. Whether you have to convert JSON to Java Object or otherwise, you need to write a lot of code that is tightly coupled with the JSON structure.


gson, gson example tutorial, gson parse json

I started looking out for some other JSON parser API that can do the transformation itself and found about Google Gson. Gson is an open source code and it’s used a lot in working with JSON and Java. Gson uses Java Reflection to provide simple methods to convert JSON to java and vice versa.

Gson Maven

You can download Gson jar file from google code website or if you are using maven then all you need is to add it’s dependency like below.

    <!--  Gson dependency -->

Gson is very powerful API and it supports Java Generics. Gson API also supports out of the box JSON to Java Object conversion if the object field names are same as in json. If we want to use different name for java bean and json, then we can use @SerializedName java annotation and map the variables in JSON and Java Class.

Gson Example

Let’s look at a complex Gson example that involves nested object and array in JSON and we will map it to java bean properties of type List, Map, Array etc.


  "empID": 100,
  "name": "David",
  "permanent": false,
  "address": {
    "street": "BTM 1st Stage",
    "city": "Bangalore",
    "zipcode": 560100
  "phoneNumbers": [
  "role": "Manager",
  "cities": [
    "Los Angeles",
    "New York"
  "properties": {
    "age": "28 years",
    "salary": "1000 Rs"

Let’s create the java bean classes to convert JSON to Java Object.

package com.journaldev.json.model;

import java.util.Arrays;
import java.util.List;
import java.util.Map;


public class Employee {

	private int id;
	private String name;
	private boolean permanent;
	private Address address;
	private long[] phoneNumbers;
	private String role;
	private List<String> cities;
	private Map<String, String> properties;
	public int getId() {
		return id;
	public void setId(int id) { = id;
	public String getName() {
		return name;
	public void setName(String name) { = name;
	public boolean isPermanent() {
		return permanent;
	public void setPermanent(boolean permanent) {
		this.permanent = permanent;
	public Address getAddress() {
		return address;
	public void setAddress(Address address) {
		this.address = address;
	public long[] getPhoneNumbers() {
		return phoneNumbers;
	public void setPhoneNumbers(long[] phoneNumbers) {
		this.phoneNumbers = phoneNumbers;
	public String getRole() {
		return role;
	public void setRole(String role) {
		this.role = role;
	public String toString(){
		StringBuilder sb = new StringBuilder();
		sb.append("***** Employee Details *****\n");
		sb.append("Phone Numbers="+Arrays.toString(getPhoneNumbers())+"\n");
		return sb.toString();
	public List<String> getCities() {
		return cities;
	public void setCities(List<String> cities) {
		this.cities = cities;
	public Map<String, String> getProperties() {
		return properties;
	public void setProperties(Map<String, String> properties) { = properties;

package com.journaldev.json.model;

public class Address {
	private String street;
	private String city;
	private int zipcode;
	public String getStreet() {
		return street;
	public void setStreet(String street) {
		this.street = street;
	public String getCity() {
		return city;
	public void setCity(String city) { = city;
	public int getZipcode() {
		return zipcode;
	public void setZipcode(int zipcode) {
		this.zipcode = zipcode;
	public String toString(){
		return getStreet() + ", "+getCity()+", "+getZipcode();

Here is the java program showing Gson example to parse JSON.

package com.journaldev.json.gson;

import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import com.journaldev.json.model.Address;
import com.journaldev.json.model.Employee;

public class EmployeeGsonExample {

	public static void main(String[] args) throws IOException {
		Employee emp = createEmployee();

		// Get Gson object
		Gson gson = new GsonBuilder().setPrettyPrinting().create();

		// read JSON file data as String
		String fileData = new String(Files.readAllBytes(Paths

		// parse json string to object
		Employee emp1 = gson.fromJson(fileData, Employee.class);

		// print object data
		System.out.println("\n\nEmployee Object\n\n" + emp1);

		// create JSON String from Object
		String jsonEmp = gson.toJson(emp);


	public static Employee createEmployee() {

		Employee emp = new Employee();
		emp.setPhoneNumbers(new long[] { 123456, 987654 });

		Address add = new Address();
		add.setStreet("BTM 1st Stage");

		List<String> cities = new ArrayList<String>();
		cities.add("Los Angeles");
		cities.add("New York");

		Map<String, String> props = new HashMap<String, String>();
		props.put("salary", "1000 Rs");
		props.put("age", "28 years");

		return emp;

Gson is the main class that exposes the methods fromJson() and toJson() for conversion. For default implementation, we can create this object directly or we can use GsonBuilder class that provide useful options for conversion such as pretty printing, field naming convention, excluding fields, date format etc.

When you will run above gson example program, we will get following output for java object.

Employee Object

***** Employee Details *****
Phone Numbers=[123456, 987654]
Address=BTM 1st Stage, Bangalore, 560100
Cities=[Los Angeles, New York]
Properties={age=28 years, salary=1000 Rs}

You can see how easy it is to use Gson and that’s why Gson is a very popular java API for JSON parsing.

The above Gson example of JSON parsing is known as Object model because whole JSON is converted to object at once. Most of the times it’s enough for us but if JSON is really huge and we don’t want to have all of it in memory at once, Gson provides Streaming API too.

Gson Example Parse JSON using Streaming API

Let’s see Gson example where we will use Streaming API for json to java object conversion.

package com.journaldev.json.gson;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;

import com.journaldev.json.model.Address;
import com.journaldev.json.model.Employee;

public class EmployeeGsonReader {

	public static void main(String[] args) throws IOException {
		InputStream is = new FileInputStream("employee.txt");
		InputStreamReader isr = new InputStreamReader(is);
		//create JsonReader object
		JsonReader reader = new JsonReader(isr);
		//create objects
		Employee emp = new Employee();
		Address add = new Address();
		List<Long> phoneNums = new ArrayList<Long>();
		emp.setCities(new ArrayList<String>());
		emp.setProperties(new HashMap<String, String>());
		String key = null;
		boolean insidePropertiesObj=false;
		key = parseJSON(reader, emp, phoneNums, key, insidePropertiesObj);
		long[] nums = new long[phoneNums.size()];
		int index = 0;
		for(Long l :phoneNums){
			nums[index++] = l;
		//print employee object
		System.out.println("Employee Object\n\n"+emp);

	private static String parseJSON(JsonReader reader, Employee emp,
			List<Long> phoneNums, String key, boolean insidePropertiesObj) throws IOException {
		//loop to read all tokens
					//get next token
					JsonToken token = reader.peek();
					case BEGIN_OBJECT:
						if("address".equals(key) || "properties".equals(key)){
							parseJSON(reader, emp,phoneNums, key, insidePropertiesObj);
					case END_OBJECT:
						if(insidePropertiesObj) insidePropertiesObj=false;
					case BEGIN_ARRAY:
						if("phoneNumbers".equals(key) || "cities".equals(key)){
								parseJSON(reader, emp,phoneNums, key, insidePropertiesObj);
					case END_ARRAY:
					case NAME:
						key = reader.nextName();
						if("properties".equals(key)) insidePropertiesObj=true;
					case BOOLEAN:
						if("permanent".equals(key)) emp.setPermanent(reader.nextBoolean());
							System.out.println("Unknown item found with key="+key);
							//skip value to ignore it
					case NUMBER:
						if("empID".equals(key)) emp.setId(reader.nextInt());
						else if("phoneNumbers".equals(key)) phoneNums.add(reader.nextLong());
						else if("zipcode".equals(key)) emp.getAddress().setZipcode(reader.nextInt());
						else {
							System.out.println("Unknown item found with key="+key);
							//skip value to ignore it
					case STRING:
						setStringValues(emp, key, reader.nextString(), insidePropertiesObj);
					case NULL:
						System.out.println("Null value for key"+key);
					case END_DOCUMENT:
						System.out.println("End of Document Reached");
						System.out.println("This part will never execute");
				return key;

	private static void setStringValues(Employee emp, String key,
			String value, boolean insidePropertiesObj) {
		if("name".equals(key)) emp.setName(value);
		else if("role".equals(key)) emp.setRole(value);
		else if("cities".equals(key)) emp.getCities().add(value);
		else if ("street".equals(key)) emp.getAddress().setStreet(value);
		else if("city".equals(key)) emp.getAddress().setCity(value);
			//add to emp properties map
				emp.getProperties().put(key, value);
				System.out.println("Unknown data found with key="+key+" value="+value);


Since JSON is a recursive language, we need to call our parsing method recursively for array and nested object. JsonToken is java enum returned by JsonReader next() method that we can use with conditional logic or switch case statements for conversion.

From the code above, you can understand that it’s not an easy implementation and if the JSON is really complex, then this code will become very hard to maintain. Avoid using it until unless there is no way to use Object based model.

Gson Example to Write Object to File

Let’s see how we can write Employee object using Gson Streaming API.

package com.journaldev.json.gson;

import java.util.Set;

import com.journaldev.json.model.Employee;

public class EmployeeGsonWriter {

	public static void main(String[] args) throws IOException {
		Employee emp = EmployeeGsonExample.createEmployee();
		//writing on console, we can initialize with FileOutputStream to write to file
		OutputStreamWriter out = new OutputStreamWriter(System.out);
		JsonWriter writer = new JsonWriter(out);
		//set indentation for pretty print
		//start writing
		writer.beginObject(); //{"id").value(emp.getId()); // "id": 123"name").value(emp.getName()); // "name": "David""permanent").value(emp.isPermanent()); // "permanent": false"address").beginObject(); // "address": {"street").value(emp.getAddress().getStreet()); // "street": "BTM 1st Stage""city").value(emp.getAddress().getCity()); // "city": "Bangalore""zipcode").value(emp.getAddress().getZipcode()); // "zipcode": 560100
			writer.endObject(); // }"phoneNumbers").beginArray(); // "phoneNumbers": [
			for(long num : emp.getPhoneNumbers()) writer.value(num); //123456,987654
			writer.endArray(); // ]"role").value(emp.getRole()); // "role": "Manager""cities").beginArray(); // "cities": [
			for(String c : emp.getCities()) writer.value(c); //"Los Angeles","New York"
			writer.endArray(); // ]"properties").beginObject(); //"properties": {
			Set<String> keySet = emp.getProperties().keySet();
			for(String key : keySet)"key").value(emp.getProperties().get(key));//"age": "28 years","salary": "1000 Rs"
			writer.endObject(); // }
		writer.endObject(); // }
		//close writer


Converting java object to JSON is comparatively easy than parsing with Gson streaming API. By default JsonWriter writes json in compact form but we can set indent for pretty printing.

That’s all for Gson example tutorial, let me know if you face any issues with it. Download project from below link and play around with different options Gson provides.


Google-Gson on Google Code
Gson User Guide


  1. jaimin patel says:

    I am getting this error
    Caused by: java.lang.IllegalArgumentException: class declares multiple JSON fields named isElasticEnabled

  2. json format says:

    Thank for share, it is very much helpful.

  3. Sameer says:

    Nice tutorial.
    But, I have a question : would it be better if we defined Address class as a static inner class in Employee class?

  4. Loved the article and I love json.


  5. Mayur says:

    Nice Article Pankaj but I had few queries & Suggestions as well.

    1. In file createEmployee() function why you have passed the values Statically ?
    2. It would really help new learners to understand easily & will look your article better if you post the screenshots/ video of the working app.

    1. Pankaj says:

      1. createEmployee() is a dummy method to create the employee object. It has no other value to the program.

      2. Usually I provide screenshot where it’s necessary. Here I am parsing JSON to Java Object and vice versa. There is not much benefit of having screenshot of the program output. It would be more beneficial to provide the project itself, so that you can just import it, run it, modify it and learn more. That’s why I have provided project code and not screenshots.

    2. Aaron says:

      I have the same question. It makes the explanation confusing.

  6. Aparajith says:

    Thank you very much for detailed articles, it is very much helpful.

  7. Melodi says:

    I searched for hours and attempted working through gson documentation and finally found this example. This was absolutely the best. Using gson truly is so simple. Thank you so much. It’d be cool to take it one more step to show how to loop through multiple employees using a class based list of objects.

  8. soumya says:

    very good article

  9. Philip Grove says:

    In examples remove Yoda conditions as they are likely to cause more confusion than benefit.

  10. Gibran Castillo says:

    This is really good. Do you have a tutorial similar like this one, with the addition of Hibernate and JTA.

  11. Vinay says:

    Nice article Pankaj! 馃檪

  12. Pranav says:

    Good article. Keep up the good work.

  13. James says:

    Hi Pankaj,
    A good article.


  14. rafiq says:

    Hi Pankaj,

    I am new to Json and looking to create json in java and parse in python could you guide me in any way possible problem description is here
    Thanks for your time.

Comments are closed.

Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors