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 list or character vector specifying the HTTP request headers e.g. list(`Content-Type` = "text/plain") or c(Authorization = "Bearer APIKEY"). Supplying a non-named list or vector will error.

data

(optional) the request data to be submitted.

response

(optional) a character vector or list specifying the response headers to return e.g. c("date", "server") or list("Date", "Server"). These are case-insensitive and will return NULL if not present.

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 >
#>  - use transact() to return data
if (!is_error_value(s)) transact(s)
#> $status
#> [1] 200
#> 
#> $headers
#> $headers$date
#> [1] "Tue, 26 Sep 2023 15:31:41 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\ngraphics. It compiles and runs on a wide variety of UNIX platforms,\nWindows and MacOS. To <strong><a\nhref=\"https://cran.r-project.org/mirrors.html\">download R</a></strong>,\nplease choose your preferred <a\nhref=\"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\nsoftware, or what the license terms are, please read our <a\nhref=\"https://cran.R-project.org/faqs.html\">answers to frequently asked\nquestions</a> before you send an email.</p>\n<h2 id=\"news\">News</h2>\n<ul>\n<li>useR! 2024 will be a hybrid conference, taking place 8-11 July 2024\nin Salzburg, Austria.</li>\n<li><a href=\"https://cran.r-project.org/src/base/R-4\"><strong>R version\n4.3.1 (Beagle Scouts)</strong></a> has been released on 2023-06-16.</li>\n<li><a href=\"https://cran.r-project.org/src/base/R-4\"><strong>R version\n4.2.3 (Shortstop Beagle)</strong></a> has been released on\n2023-03-15.</li>\n<li>You can support the R Foundation with a renewable subscription as a\n<a href=\"https://www.r-project.org/foundation/donations.html\">supporting\nmember</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\" 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\n<a rel=\"me\" href=\"https://fosstodon.org/@R_Foundation\">Mastodon</a>,\n<a href=\"https://twitter.com/_R_Foundation\">Twitter</a>, or\n<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)