ESP8266: HTTP GET Requests

The objective of this post is to explain how to perform GET Requests using the ESP8266.


Introduction

The objective of this post is to explain how to perform GET Requests using the ESP8266. If you prefer a video explanation, you can check my YouTube channel:

The tests were performed using a NodeMCU board, a very cheap and easy to use ESP8266 board.


Setup

First, we need do include some libraries. Naturally, we need the ESP8266WiFi library, which provides us the methods to connect to a WiFi network.

Then, we need the ESP8266HTTPClient library, which provides methods to send HTTP requests. The header file for the ESP8266HTTPClient library can be seen here.

#include <esp8266wifi.h>
#include <esp8266httpclient.h>

On the setup function, we connect to the WiFi Network. We also start a Serial connection for debugging. More details about how to connect to a WiFi network using the ESP8266 are explained in this previous post.

const char* ssid = "yourNetworkName";
const char* password = "yourNetworkPassword";

void setup () {

Serial.begin(115200);
WiFi.begin(ssid, password);

while (WiFi.status() != WL_CONNECTED) {

delay(1000);
Serial.print("Connecting..");

}

}


The main code

The code for the request will be specified in the main loop function. First, we declare an object of class HTTPClient, which we will simply call http. This class provides the methods to create and send the HTTP request.

HTTPClient http;

After that, we call the begin method on the http object and pass the URL that we want to connect to and make the GET request. The destination website specified here implements a dummy REST API for testing and prototyping.

http.begin("http://jsonplaceholder.typicode.com/users/1");

Then, we send the request by calling the GET method on the http object. This method will return the status of the operation, which is important to store for error handling. If the value is greater than 0, then it’s a standard HTTP code. If the value is less than 0, then it’s a client error, related with the connection. All available error codes for this method are listed here.

int httpCode = http.GET();

So, if the code is greater than 0, we can get and print the response payload, by calling the getString method on the http object.

String payload = http.getString();
Serial.println(payload);

Finally, we call the end method. This is very important to close the TCP connection and thus free the resources.

http.end();

The final complete code is shown bellow. You just need to put your network name and network password.

#include <ESP8266WiFi.h>
#include <ESP8266HTTPClient.h>

const char* ssid = "yourNetworkName";
const char* password = "yourNetworkPassword";

void setup () {

Serial.begin(115200);
WiFi.begin(ssid, password);

while (WiFi.status() != WL_CONNECTED) {

delay(1000);
Serial.print("Connecting..");

}

}

void loop() {

if (WiFi.status() == WL_CONNECTED) { //Check WiFi connection status

HTTPClient http;  //Declare an object of class HTTPClient

http.begin("http://jsonplaceholder.typicode.com/users/1");  //Specify request destination
int httpCode = http.GET();                                                                  //Send the request

if (httpCode > 0) { //Check the returning code

String payload = http.getString();   //Get the request response payload
Serial.println(payload);                     //Print the response payload

}

http.end();   //Close connection

}

delay(30000);    //Send a request every 30 seconds

}

The output of the program is shown in figure 1. The response corresponds to a JSON payload.

ESP8266 GET Request

Figure 1 – Output of the GET Request.

Finally, it’s important to take in consideration that the microcontroller has a limited amount of resources and thus it is not able to handle very large results. So, it is not expected that it will be used to make and process requests to sites that return a lot of information, as a typical browser would do.


Technical details

ESP8266 libraries: v2.3.0

309 Replies to “ESP8266: HTTP GET Requests”

  1. Hi
    on tp link tl-mr6400 in G3/G4 mode, httpCode is -1 (sometimes after reboot first request will succeed), in standard mode everything works OK. unfortunately I have to work in G3/G4 mode :). Any ideas ??

    1. Hi,

      Sorry, never worked with that device, so unfortunately I cannot be of much assistance.

      But, if you try to make the same request to the tp link using a tool such as Postman, do you also have problems or does it work?

      Best regards,
      Nuno Santos

  2. Hi
    on tp link tl-mr6400 in G3/G4 mode, httpCode is -1 (sometimes after reboot first request will succeed), in standard mode everything works OK. unfortunately I have to work in G3/G4 mode :). Any ideas ??

    1. Hi,
      Sorry, never worked with that device, so unfortunately I cannot be of much assistance.
      But, if you try to make the same request to the tp link using a tool such as Postman, do you also have problems or does it work?
      Best regards,
      Nuno Santos

    1. Hi!

      That’s a very broad and generic question πŸ™‚ How do you want to send the data? Via Serial, WiFi or Bluetooth?

      But in general I think it should be possible. For a more optimized solution, you can use timer interrupts to send the data once each second.

      Best regards,
      Nuno Santos

    1. Hi!
      That’s a very broad and generic question πŸ™‚ How do you want to send the data? Via Serial, WiFi or Bluetooth?
      But in general I think it should be possible. For a more optimized solution, you can use timer interrupts to send the data once each second.
      Best regards,
      Nuno Santos

  3. Hello, can you estimate “limited amount of resources”? I try to GET about 20K payload using HTTP Client, but it crashes. Probably it is too much…

    1. Hi!

      Unfortunately I’m not aware of all the implementation details of the HTTP Client library implementation, so I cannot provide you an exact value of how much is a payload too big.

      That sentence I’ve included in the post is for the readers to be aware that it’s expected that the ESP8266 will run into troubles when working with very big payloads, such as trying to fetch complete HTML webpages with a lot of code.

      Nonetheless, the best suggestion I can give you is to ask around the ESP8266 arduino core Github page or forums. Probably someone has already done more extensive tests / analysis to figure out what are the maximum values for the payloads.

      Hope this helps getting you in the right track πŸ™‚

      Best regards,
      Nuno Santos

  4. Hello, can you estimate “limited amount of resources”? I try to GET about 20K payload using HTTP Client, but it crashes. Probably it is too much…

    1. Hi!
      Unfortunately I’m not aware of all the implementation details of the HTTP Client library implementation, so I cannot provide you an exact value of how much is a payload too big.
      That sentence I’ve included in the post is for the readers to be aware that it’s expected that the ESP8266 will run into troubles when working with very big payloads, such as trying to fetch complete HTML webpages with a lot of code.
      Nonetheless, the best suggestion I can give you is to ask around the ESP8266 arduino core Github page or forums. Probably someone has already done more extensive tests / analysis to figure out what are the maximum values for the payloads.
      Hope this helps getting you in the right track πŸ™‚
      Best regards,
      Nuno Santos

    1. Hi!

      Are you using the same exact code from this tutorial or testing against another endpoint?

      Are you using the same baud rate from the Arduino code in your Serial Monitor?

      Let me knows some more details so I can try to help πŸ™‚

      Best regards,
      Nuno Santos

    1. Hi!
      Are you using the same exact code from this tutorial or testing against another endpoint?
      Are you using the same baud rate from the Arduino code in your Serial Monitor?
      Let me knows some more details so I can try to help πŸ™‚
      Best regards,
      Nuno Santos

  5. Hi Nuno, I’ve spent hours trying to retrieve a JSON file from the YouTube API and parse it on an ESP8266. This post has proven the best so far. Thank you.

    When I run the code with the same endpoint as in your article I see the payload printed to the serial monitor. However when I change this endpoint to the YouTube one I see nothing, yet when I paste the address in a browser I get the result I am expecting.

    Please can you offer some advice?

    This is the URL for the JSON file:

    https://www.googleapis.com/youtube/v3/channels?part=statistics&id=UC3jc4X-kEq-dEDYhQ8QoYnQ&key=AIzaSyA5fO-WJ_yFXG5Chz0381sGMCo9Cq8dcow

    Thank you,
    Lewis

    1. Hi!

      Sorry for the delay.

      From what I’m seeing it is probably due to the fact that you are trying to reach a HTTPS (note the S at the end) endpoint, which means it is trying to establish a secure connection.

      I’ve not been using the ESP8266 in a while but at the time I’ve written this tutorial, trying to reach a HTTP Secure endpoint didn’t work.

      At that time there was not much HTTPS support but now it seems that there is an example on how to use it with the HTTP client:
      https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266HTTPClient/examples/BasicHttpsClient/BasicHttpsClient.ino

      I’ve never tested it, so I cannot confirm if it is working fine.

      I’m currently mainly working with the ESP32 (the ESP8266 successor), which handles HTTPS pretty well πŸ™‚

      Hope this helps, let me know if the issue was related.

      Best regards,
      Nuno Santos

    2. i think it has to do with https..
      the json in the example is http, NOT httpS, so in order to use it i guess you have to modify in a way the ESP8266HTTPClient BasicHttpSClient Example..

  6. Hi Nuno, I’ve spent hours trying to retrieve a JSON file from the YouTube API and parse it on an ESP8266. This post has proven the best so far. Thank you.
    When I run the code with the same endpoint as in your article I see the payload printed to the serial monitor. However when I change this endpoint to the YouTube one I see nothing, yet when I paste the address in a browser I get the result I am expecting.
    Please can you offer some advice?
    This is the URL for the JSON file:
    https://www.googleapis.com/youtube/v3/channels?part=statistics&id=UC3jc4X-kEq-dEDYhQ8QoYnQ&key=AIzaSyA5fO-WJ_yFXG5Chz0381sGMCo9Cq8dcow
    Thank you,
    Lewis

    1. Hi!
      Sorry for the delay.
      From what I’m seeing it is probably due to the fact that you are trying to reach a HTTPS (note the S at the end) endpoint, which means it is trying to establish a secure connection.
      I’ve not been using the ESP8266 in a while but at the time I’ve written this tutorial, trying to reach a HTTP Secure endpoint didn’t work.
      At that time there was not much HTTPS support but now it seems that there is an example on how to use it with the HTTP client:
      https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266HTTPClient/examples/BasicHttpsClient/BasicHttpsClient.ino
      I’ve never tested it, so I cannot confirm if it is working fine.
      I’m currently mainly working with the ESP32 (the ESP8266 successor), which handles HTTPS pretty well πŸ™‚
      Hope this helps, let me know if the issue was related.
      Best regards,
      Nuno Santos

    2. i think it has to do with https..
      the json in the example is http, NOT httpS, so in order to use it i guess you have to modify in a way the ESP8266HTTPClient BasicHttpSClient Example..

  7. thank you for the example it works fine!
    Beside the payload I’m interested in the header information too. How to access the header?
    Thank you!

  8. thank you for the example it works fine!
    Beside the payload I’m interested in the header information too. How to access the header?
    Thank you!

  9. Hey, I don’t know if you are still active. I wanted to know how do I connect a temperature sensor to the arduino and publish the results on the web server.

Leave a Reply to Tomasz Bigaj Cancel reply