Skip to content

Reading Responses

The core of ESP32-HTTP-Client is the response binding system. Instead of parsing a JSON string yourself, you register bindings that tell the library exactly which variables to populate.


Basic Binding with getBody()

getBody() is overloaded for each supported C type. It registers a binding between a JSON key path and a target variable pointer.

int count;
float temperature;
bool active;
char name[64];
long timestamp;

client.get("/sensor")
      .getBody("count",       &count)
      .getBody("temperature", &temperature)
      .getBody("active",      &active)
      .getBody("name",        name, sizeof(name))
      .getBody("timestamp",   &timestamp);

Supported Types

Method signature JSON type matched Notes
getBody(key, int* target) number Integer truncation applied
getBody(key, float* target) number Up to 5 significant digits. Supports scientific notation (e.g. 6.02e+2, -2.5E-3)
getBody(key, double* target) number Up to 9 significant digits. Supports scientific notation (e.g. 6.02e+2, -2.5E-3)
getBody(key, long* target) number Use for Unix timestamps
getBody(key, bool* target) boolean Matches true / false
getBody(key, char* target, size_t maxLen) string Copies up to maxLen-1 bytes
getBody(key, String* target) string / object / array Arduino String, see below

Scientific Notation Support

Numbers formatted in scientific / exponential notation are parsed directly into float and double targets:

float  positiveExp;
double negativeExp;

// Response: { "positive_exp": 6.02e+2, "negative_exp": -2.5E-3 }
client.get("/sensor")
      .getBody("positive_exp", &positiveExp) // 602.0
      .getBody("negative_exp", &negativeExp); // -0.0025

Both lowercase e and uppercase E, with optional positive (+) or negative (-) exponents, are supported.


Dot Notation for Nested Fields

Use . as a path separator to reach nested JSON objects:

// Response: { "address": { "city": "Gwenborough", "geo": { "lat": "-37.3159" } } }

char city[64];
char lat[32];

client.get("/users/1")
      .getBody("address.city",    city, sizeof(city))
      .getBody("address.geo.lat", lat,  sizeof(lat));

There is no practical limit on nesting depth.


Numeric Indices for Arrays

Use an integer as a path segment to address a specific element of a JSON array:

// Response: [{ "name": "Alice" }, { "name": "Bob" }]

char first[32], second[32];

client.get("/users")
      .getBody("0.name", first,  sizeof(first))   // first element
      .getBody("1.name", second, sizeof(second));  // second element

You can combine array indices with dot notation freely:

// Response: [{ "address": { "city": "Gwenborough" } }, ...]
char city[64];
client.get("/users")
      .getBody("1.address.city", city, sizeof(city));

Capturing Raw JSON with String

Bind a String* to capture an entire JSON object or array as a raw string for manual processing:

String entireResponse;
String secondUser;

client.get("/users")
      .getBody("",  &entireResponse) // captures the root array
      .getBody("1", &secondUser);    // captures the second user object

Memory warning

Pulling complete objects or arrays into an Arduino String causes dynamic heap allocation. Avoid this pattern with large payloads, as it can fragment or exhaust the device heap. Use typed bindings where possible.


Reading Response Headers with getHeader()

In addition to JSON body fields, you can extract HTTP response headers directly using getHeader().

String token;
char contentType[64];
int contentLength;

client.get("/auth")
      .getHeader("token",          &token)
      .getHeader("Content-Type",   contentType)
      .getHeader("Content-Length", &contentLength)
      .getBody("id", &id);

Header lookups are case-insensitive, so "token", "TOKEN", and "Token" all work identically.


Reading JSON-RPC 2.0 Responses with getResult()

When working with JSON-RPC 2.0 requests, the result payload is extracted using .getResult() rather than .getBody(). This supports root primitives, nested fields, mapped structs, and raw JSON extraction directly:

// 1. Primitive binding to root "result"
int sum = 0;
client.jsonRpc("/rpc").method("add").param(10).param(20).getResult(&sum);

// 2. Nested field inside "result" object
char city[32] = {0};
client.jsonRpc("/rpc").method("getUser").param("id", 1).getResult("address.city", city, sizeof(city));

// 3. Mapped struct binding
User profile;
client.jsonRpc("/rpc").method("getUser").param("id", 1).getResult(&profile);

// 4. Raw JSON result string
String rawResult;
client.jsonRpc("/rpc").method("getMetrics").getRawResult(&rawResult);

Inspecting JSON-RPC Errors

If the server returns a JSON-RPC 2.0 error object ({"error": {"code": -32601, "message": "Method not found"}}), standard HTTP status codes might still be 200 OK. You can detect and inspect JSON-RPC errors using .getError() or .onJsonRpcError():

JsonRpcError error;
client.jsonRpc("/rpc")
      .method("unknownMethod")
      .getError(&error)
      .onJsonRpcError([](const JsonRpcError& err) {
          Serial.printf("Error code: %d, Message: %s\n", err.code, err.message.c_str());
      });

if (error.code != 0) {
    Serial.printf("JSON-RPC error encountered: %s\n", error.message.c_str());
}

Safety Guarantees

Missing keys and headers are safe

If a JSON key path or response header does not exist in the response, is misspelled, or the type doesn't match, the target variable is left unchanged. No exception is thrown, no crash occurs, and the library continues parsing the rest of the response.

This makes it safe to add optional fields or optional headers to your bindings without defensive checks:

int optionalField = -1; // default value
String optionalToken = "";

client.get("/data")
      .getHeader("token",         &optionalToken)
      .getBody("requiredField",   &myVar)
      .getBody("optionalField",   &optionalField); // unchanged if missing

Next Step

→ Advanced Usage