ESP8266: HTTP GET Requests

Introduction

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

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

The setup

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

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

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

To be able to connect to the WiFi network, we will need its credentials. So, we will define two global variables containing the network name (SSID) and password. Note that you should replace the placeholders in the code snippet below by the credentials of your network.

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

On the setup function, we will connect to the WiFi Network. This is done with a call to the begin method on the WiFi extern variable and providing the previously defined network credentials. More details about how to connect to a WiFi network using the ESP8266 are explained in this previous post.

We will also start a Serial connection to print the results of our program.

The complete Arduino setup function code can be seen below.

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 Arduino 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 will call the begin method on the http object and pass the URL that we want to connect to and make the HTTP GET request. The destination website specified here implements a dummy REST API for testing and prototyping.

Note that the particular endpoint we are reaching will return a JSON payload as response, simulating a possible “user” data structure. You can directly access the URL and check the result in a web browser. Later, when testing the ESP8266 code, we should receive the same response.

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 is a standard HTTP code. If the value is lesser than 0, then it is 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 the response payload by calling the getString method on the http object. The response is returned as a String, which we can directly print to the serial port.

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

Finally, we will 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. Note that we have added a small delay of 30 seconds between each iteration of the Arduino main loop, to avoid constantly polling the server.

#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
}

Testing the code

To test the code, simply compile it and upload it to your device using the Arduino IDE.

After the upload procedure finishes, open the IDE serial monitor and wait for the WiFi connection to be established. Once this procedure is done, the ESP8266 should start sending the HTTP GET requests to the server periodically.

The expected output of the program is shown in figure 1. The response printed to the serial monitor corresponds to the JSON payload returned by the server. The ESP8266 should keep doing a HTTP GET request every 30 seconds.

Output of the ESP8266 GET Request program, on the Arduino IDE serial monitor
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.

Related Posts

Technical details

  • ESP8266 libraries: v2.3.0
  • Operating system: Windows 8.1

314 thoughts on “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

      1. Hi, just change https to http. Or use another library “HTTPSRedirect” for https requests. That is required e.g. for host “script.google.com”. Other problem can be if you are using free version of thinkspeak.com – you can send data only every 15 sec, more often causes return http code 200 but no zero result 🙂

  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. Pingback: ESP8266 Arduino: HTTP PUT request – techtutorialsx

  10. Pingback: ESP8266 Arduino: HTTP PUT request – techtutorialsx

  11. Saurabh Srivastava

    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.

  12. I keep getting a load store alignment cause exception

    Full exception decode is:

    Exception 9: LoadStoreAlignmentCause: Load or store to an unaligned address

    PC: 0x40206f88: HTTPClient::connected() at C:\Users\Russe\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.7.4\libraries\ESP8266HTTPClient\src\ESP8266HTTPClient.cpp line 475
    EXCVADDR: 0x000000ed

    Decoding stack results
    0x40203a34: HardwareSerial::write(unsigned char const*, unsigned int) at C:\Users\Russe\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.7.4\cores\esp8266/HardwareSerial.h line 164
    0x40203d15: Print::write(char const*) at C:\Users\Russe\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.7.4\cores\esp8266/Print.h line 62
    0x40202880: HTTPClient::disconnect(bool) at C:\Users\Russe\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.7.4\libraries\ESP8266HTTPClient\src\ESP8266HTTPClient.cpp line 434
    0x40203624: HTTPClient::end() at C:\Users\Russe\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.7.4\libraries\ESP8266HTTPClient\src\ESP8266HTTPClient.cpp line 425
    0x402010f2: loop() at C:\Users\Russe\OneDrive\Documents\Arduino\Wifing\wifi1/wifi1.ino line 37
    0x40201074: setup() at C:\Users\Russe\OneDrive\Documents\Arduino\Wifing\wifi1/wifi1.ino line 12
    0x402050cc: loop_wrapper() at C:\Users\Russe\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.7.4\cores\esp8266\core_esp8266_main.cpp line 197

    My Code is

    #include
    #include

    const char* ssid = “DukeOpen”;
    const char* password = “Password”;

    void setup () {

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

    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

    }

Leave a Reply to gary Cancel reply

%d bloggers like this: