nano cURL - a minimalist http(s) client. A session encapsulates a connection, along with all related parameters, and may be used to return data multiple times by repeatedly calling transact, which transacts once over the connection.

ncurl_session(
  url,
  convert = TRUE,
  method = NULL,
  headers = NULL,
  data = NULL,
  response = NULL,
  timeout = NULL,
  tls = NULL
)

transact(session)

Arguments

url

the URL address.

convert

[default TRUE] logical value whether to attempt conversion of the received raw bytes to a character vector. Set to FALSE if downloading non-text data.

method

(optional) the HTTP method (defaults to 'GET' if not specified).

headers

(optional) a named character vector specifying the HTTP request headers, for example:
c(Authorization = "Bearer APIKEY", `Content-Type` = "text/plain")
A non-character or non-named vector will be ignored.

data

(optional) character request data to be submitted.

response

(optional) a character vector specifying the response headers to return e.g. c("date", "server"). These are case-insensitive and will return NULL if not present. A non-character vector will be ignored.

timeout

(optional) integer value in milliseconds after which the connection and subsequent transact attempts time out.

tls

(optional) applicable to secure HTTPS sites only, a client TLS Configuration object created by tls_config. If missing or NULL, certificates are not validated.

session

an 'ncurlSession' object.

Value

For ncurl_session: an 'ncurlSession' object if successful, or else an 'errorValue'.

For transact: a named list of 3 elements:

  • $status - integer HTTP repsonse status code (200 - OK). Use status_code for a translation of the meaning.

  • $headers - named list of response headers (if specified in the session), or NULL otherwise. If the status code is within the 300 range, i.e. a redirect, the response header 'Location' is automatically appended to return the redirect address.

  • $data - the response body as a character string (if 'convert = TRUE' was specified for the session), which may be further parsed as html, json, xml etc. as required, or else a raw byte vector, which may be saved as a file using writeBin.

See also

ncurl_aio for asynchronous http requests.

Examples

s <- ncurl_session("https://www.r-project.org/", response = "date", timeout = 2000L)
s
#> < ncurlSession > - transact() to return data
if (!is_error_value(s)) transact(s)
#> $status
#> [1] 200
#> 
#> $headers
#> $headers$date
#> [1] "Sat, 02 Mar 2024 23:24:38 GMT"
#> 
#> 
#> $data
#> [1] "<!DOCTYPE html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\">\n    <meta http-equiv=\"X-UA-Compatible\" content=\"IE=edge\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n    <title>R: The R Project for Statistical Computing</title>\n\n    <link rel=\"icon\" type=\"image/png\" href=\"/favicon-32x32.png\" sizes=\"32x32\" />\n    <link rel=\"icon\" type=\"image/png\" href=\"/favicon-16x16.png\" sizes=\"16x16\" />\n\n    <!-- Bootstrap -->\n    <link href=\"/css/bootstrap.min.css\" rel=\"stylesheet\">\n    <link href=\"/css/R.css\" rel=\"stylesheet\">\n\n    <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->\n    <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->\n    <!--[if lt IE 9]>\n      <script src=\"https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js\"></script>\n      <script src=\"https://oss.maxcdn.com/respond/1.4.2/respond.min.js\"></script>\n    <![endif]-->\n  </head>\n  <body>\n    <div class=\"container page\">\n      <div class=\"row\">\n        <div class=\"col-xs-12 col-sm-offset-1 col-sm-2 sidebar\" role=\"navigation\">\n<div class=\"row\">\n<div class=\"col-xs-6 col-sm-12\">\n<p><a href=\"/\"><img src=\"/Rlogo.png\" width=\"100\" height=\"78\" alt = \"R\" /></a></p>\n<p><small><a href=\"/\">[Home]</a></small></p>\n<h2 id=\"download\">Download</h2>\n<p><a href=\"https://cran.r-project.org/mirrors.html\">CRAN</a></p>\n<h2 id=\"r-project\">R Project</h2>\n<ul>\n<li><a href=\"/about.html\">About R</a></li>\n<li><a href=\"/logo/\">Logo</a></li>\n<li><a href=\"/contributors.html\">Contributors</a></li>\n<li><a href=\"/news.html\">What’s New?</a></li>\n<li><a href=\"/bugs.html\">Reporting Bugs</a></li>\n<li><a href=\"/conferences/\">Conferences</a></li>\n<li><a href=\"/search.html\">Search</a></li>\n<li><a href=\"/mail.html\">Get Involved: Mailing Lists</a></li>\n<li><a href=\"https://contributor.r-project.org/\">Get Involved: Contributing</a></li>\n<li><a href=\"https://developer.R-project.org/\">Developer Pages</a></li>\n<li><a href=\"https://blog.r-project.org/\">R Blog</a></li>\n</ul>\n</div>\n<div class=\"col-xs-6 col-sm-12\">\n<h2 id=\"r-foundation\">R Foundation</h2>\n<ul>\n<li><a href=\"/foundation/\">Foundation</a></li>\n<li><a href=\"/foundation/board.html\">Board</a></li>\n<li><a href=\"/foundation/members.html\">Members</a></li>\n<li><a href=\"/foundation/donors.html\">Donors</a></li>\n<li><a href=\"/foundation/donations.html\">Donate</a></li>\n</ul>\n<h2 id=\"help-with-r\">Help With R</h2>\n<ul>\n<li><a href=\"/help.html\">Getting Help</a></li>\n</ul>\n<h2 id=\"documentation\">Documentation</h2>\n<ul>\n<li><a href=\"https://cran.r-project.org/manuals.html\">Manuals</a></li>\n<li><a href=\"https://cran.r-project.org/faqs.html\">FAQs</a></li>\n<li><a href=\"https://journal.r-project.org\">The R Journal</a></li>\n<li><a href=\"/doc/bib/R-books.html\">Books</a></li>\n<li><a href=\"/certification.html\">Certification</a></li>\n<li><a href=\"/other-docs.html\">Other</a></li>\n</ul>\n<h2 id=\"links\">Links</h2>\n<ul>\n<li><a href=\"https://www.bioconductor.org\">Bioconductor</a></li>\n<li><a href=\"https://r-forge.r-project.org/\">R-Forge</a></li>\n<li><a href=\"https://r-hub.github.io/rhub/\">R-Hub</a></li>\n<li><a href=\"/gsoc.html\">GSoC</a></li>\n</ul>\n</div>\n</div>\n        </div>\n        <div class=\"col-xs-12 col-sm-7\">\n        <h1>The R Project for Statistical Computing</h1>\n<h2 id=\"getting-started\">Getting Started</h2>\n<p>R is a free software environment for statistical computing and graphics. It compiles and runs on a wide variety of UNIX platforms, Windows and MacOS. To <strong><a href=\"https://cran.r-project.org/mirrors.html\">download R</a></strong>, please choose your preferred <a href=\"https://cran.r-project.org/mirrors.html\">CRAN mirror</a>.</p>\n<p>If you have questions about R like how to download and install the software, or what the license terms are, please read our <a href=\"https://cran.R-project.org/faqs.html\">answers to frequently asked questions</a> before you send an email.</p>\n<h2 id=\"news\">News</h2>\n<ul>\n<li><a href=\"https://cran.r-project.org/src/base/R-4\"><strong>R version 4.3.3 (Angel Food Cake)</strong></a> has been released on 2024-02-29.</li>\n<li><a href=\"https://events.linuxfoundation.org/user/register/\"><strong>Registration for useR! 2024</strong></a> has opened with early bird deadline March 31 2024.</li>\n<li><a href=\"https://cran.r-project.org/src/base/R-4\"><strong>R version 4.3.2 (Eye Holes)</strong></a> has been released on 2023-10-31.</li>\n<li><a href=\"https://cran.r-project.org/src/base/R-4\"><strong>R version 4.2.3 (Shortstop Beagle)</strong></a> has been released on 2023-03-15.</li>\n<li>You can support the R Foundation with a renewable subscription as a <a href=\"https://www.r-project.org/foundation/donations.html\">supporting member</a>.</li>\n</ul>\n<h2 id=\"news-via-mastodon\">News via Mastodon</h2>\n<!--\nMastodon widget from https://gitlab.com/idotj/mastodon-embed-feed-timeline\nFiles mastodon-feed-timeline.css and mastodon-feed-timeline.js are from this source\n-->\n<link rel=\"stylesheet\" href=\"mastodon-timeline.css\" />\n<script src=\"mastodon-timeline.js\"></script>\n<link rel=\"stylesheet\" href=\"mastodon-timeline.css\" />\n<script src=\"mastodon-timeline.js\"></script>\n<div class=\"mt-timeline\">\n<div id=\"mt-body\" class=\"mt-body\" data-role=\"feed\">\n<pre><code>&lt;div class=&quot;loading-spinner&quot;&gt;&lt;/div&gt;</code></pre>\n</div>\n</div>\n<h2 id=\"social-media\">Social Media</h2>\n<!-- rel=\"me\" required to verify on Mastodon -->\n<p>Follow the R Foundation on <a rel=\"me\" href=\"https://fosstodon.org/@R_Foundation\">Mastodon</a>, <a href=\"https://twitter.com/_R_Foundation\">Twitter</a>, or <a href=\"https://www.linkedin.com/company/the-r-foundation-for-statistical-computing\">LinkedIn</a>.</p>\n<!--- (Boilerplate for release run-in)\n-   [**R version 3.1.3 (Smooth Sidewalk) prerelease versions**](https://cran.r-project.org/src/base-prerelease/) will appear starting February 28. Final release is scheduled for 2015-03-09.\n-->\n        </div>\n      </div>\n      <div class=\"raw footer\">\n        &copy; The R Foundation. For queries about this web site, please contact\n\t<script type='text/javascript'>\n<!--\nvar s=\"=b!isfg>#nbjmup;xfcnbtufsAs.qspkfdu/psh#?uif!xfcnbtufs=0b?\";\nm=\"\"; for (i=0; i<s.length; i++) {if(s.charCodeAt(i) == 28){m+= '&';} else if (s.charCodeAt(i) == 23) {m+= '!';} else {m+=String.fromCharCode(s.charCodeAt(i)-1);}}document.write(m);//-->\n\t</script>;\n        for queries about R itself, please consult the \n        <a href=\"help.html\">Getting Help</a> section.\n      </div>\n    </div>\n    <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->\n    <script src=\"https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js\"></script>\n    <!-- Include all compiled plugins (below), or include individual files as needed -->\n    <script src=\"/js/bootstrap.min.js\"></script>\n  </body>\n</html>\n"
#> 
if (!is_error_value(s)) close(s)