Parse ISO 8601 Dates from JSON to LocalDateTime in Java

When working with APIs or other systems that return JSON responses, you’ll often encounter date-time values in ISO 8601 format — like "2022-03-25T00:00:00.000Z". In Java, converting these strings into a usable LocalDateTime, OffsetDateTime, or ZonedDateTime object is a common task, especially when using libraries like org.json.

In this article, we’ll show you:

• How to extract an ISO 8601 date string from a JSONObject
• How to parse it into a LocalDateTime
• When to use OffsetDateTime instead
• Multiple full examples for Java 8 and later

📦 Dependencies

We’ll be using the standard Java 8+ time API (java.time) and the popular org.json library:

Maven:

<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20231013</version>
</dependency>

📄 Example JSON with Date Fields

Here’s a sample JSON response:

{
  "securitiesAccount": {
    "iban": "DE2310010010123456788"
  },
  "reportDateTime": "2022-03-25T00:00:00.000Z",
  "balances": [
    {
      "balanceAmount": {
        "currency": "EUR",
        "amount": "22901.00"
      },
      "balanceType": "closingBooked"
    },
    {
      "balanceAmount": {
        "currency": "EUR",
        "amount": "22910.00"
      },
      "balanceType": "interimAvailable",
      "referenceDateTime": "2020-10-29T14:00:00.011Z"
    }
  ]
}

🧪 Parsing reportDateTime as LocalDateTime

If you don’t need timezone info, you can convert the Z offset to a LocalDateTime:

import org.json.JSONObject;
import java.time.LocalDateTime;
import java.time.OffsetDateTime;
import java.time.format.DateTimeFormatter;

public class JsonDateParser {
    public static void main(String[] args) {
        String jsonString = "{\n" +
                "  \"reportDateTime\": \"2022-03-25T00:00:00.000Z\"\n" +
                "}";

        JSONObject jsonObject = new JSONObject(jsonString);
        String dateString = jsonObject.getString("reportDateTime");

        // Parse as OffsetDateTime and convert to LocalDateTime
        OffsetDateTime offsetDateTime = OffsetDateTime.parse(dateString);
        LocalDateTime localDateTime = offsetDateTime.toLocalDateTime();

        System.out.println("LocalDateTime: " + localDateTime);
    }
}

Output:

LocalDateTime: 2022-03-25T00:00

🌍 Keep Timezone Info? Use OffsetDateTime or ZonedDateTime

If your application needs the timezone offset (Z = UTC), use OffsetDateTime:

OffsetDateTime offsetDateTime = OffsetDateTime.parse(dateString);
System.out.println("OffsetDateTime: " + offsetDateTime);

For timezone-specific handling, use ZonedDateTime:

ZonedDateTime zoned = ZonedDateTime.parse(dateString);
System.out.println("ZonedDateTime: " + zoned);

🔁 Parse Nested Dates (e.g., referenceDateTime in balances)

Let’s extract and parse a nested field:

JSONArray balances = jsonObject.getJSONArray("balances");
for (int i = 0; i < balances.length(); i++) {
    JSONObject balance = balances.getJSONObject(i);
    if (balance.has("referenceDateTime")) {
        String refDate = balance.getString("referenceDateTime");
        OffsetDateTime parsedRef = OffsetDateTime.parse(refDate);
        System.out.println("Reference Date: " + parsedRef);
    }
}

⚠️ Common Pitfalls

1. “Z” is not supported by LocalDateTime.parse()
   • You must parse using OffsetDateTime or strip the Z manually.

   LocalDateTime.parse("2022-03-25T00:00:00.000") // works
   LocalDateTime.parse("2022-03-25T00:00:00.000Z") // throws exception
   

2. Different format? Use a custom DateTimeFormatter:

   DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSSX");
   OffsetDateTime dateTime = OffsetDateTime.parse(dateString, formatter);
   

✅ Summary

📚 Related Java Topics

• java.time vs java.util.Date — modern date-time API is better
• Using Gson or Jackson for JSON parsing with custom deserializers
• Validating ISO 8601 date formats in Java

🧩 Final Thoughts

Parsing ISO 8601 date-time strings from a JSON response is a common but critical task in Java. With the power of OffsetDateTime and the simplicity of org.json, you can handle both flat and nested date fields efficiently and safely.

Make sure you choose the right date-time class (LocalDateTime, OffsetDateTime, or ZonedDateTime) based on whether your application needs to store or manipulate timezone information.