WOLFRAM

Wolfram Language & System Documentation Center
Wolfram Language Home Page »

HTTPRequest
✖
HTTPRequest

✖

represents an HTTP request for the specified URL.

✖
HTTPRequest[assoc]

represents an HTTP request built from the components in the association assoc.

✖
HTTPRequest[url,assoc]

represents an HTTP request for the specified URL with additional elements such as headers given by assoc.

Details and Options

  • HTTPRequest gives a symbolic representation of an HTTP request; it does not execute the request.
  • In HTTPRequest[url], url can be a string, a URL object, or a cloud object.
  • The URL can also be specified by giving the following components in an association:
  • "Scheme"URL scheme
    "User"user information
    "Domain"domain name or host
    "Port"port number (as an integer)
    "Path"path list or string
    "Query"query string or list of parameter-value pairs
  • The following additional entries can also be given in the association:
  • Method"GET"method to use for the HTTP request
    "Body"""contents of message body to be sent
    "ContentType"Automaticcontent-type header for the request
    "Username"""username to use for the request
    "Password"""password to use for the request
    "Cookies"Automaticcookies to send to the server
    "UserAgent"Automaticuser agent string to send
    "Headers"{}list of headers to be sent to the server
  • The setting for "Body" can have the following forms:
  • "string"string to be sent literally
    ByteArray[…]byte array to be sent literally
    {b1,b2,b3,…}list of bytes to be sent literally
    {"par1""val1","par2""val2",…}list of parameters and values to be sent URL encoded
    {"par1"{"val11",…},…}list with multiple values associated with a single parameter
    <|"key1"val1,"key2"val2,…|>alternative form for list of parameters and values
    {"par1"File[…],"par2"File[…],…}files to be sent with multipart encoding
    {"par1"assoc1,…}multipart encoding with detailed specifications for each part
  • Detailed specifications for each part in a multipart encoding are given as an association with the following elements:
  • "Content"the content, as a string, byte array, file object, etc.
    "Name"the name to assign to the part
    "MIMEType"the MIME type to assign to the part
  • The setting "Cookies"->Automatic specifies that cookies from $Cookies for the domain corresponding to url should be sent. "Cookies" can also give an explicit list of associations representing cookies.
  • The setting for "Headers" can be a list of rules or an association.
  • The default "UserAgent" is typically "Wolfram HTTPClient xxxx", where xxxx is a version number.
  • HTTPRequest supports the following options:
  • CharacterEncodingAutomaticcharacter encoding for strings sent
    CookieFunction Automaticfunction to apply to each cookie received
    FollowRedirects Truewhether to follow HTTP redirects
    InteractiveTruewhether to allow interactive authentication dialogs
    TimeConstraint Infinitytime to wait for a response
    VerifySecurityCertificates Truewhether to verify SSL security certificates
  • The setting CharacterEncoding->"enc" specifies that all strings that appear in the request should be encoded using the encoding enc before being sent to the server.
  • The setting CharacterEncoding->None specifies that no change should be made to strings before sending them to the server.
  • With CharacterEncoding->Automatic, the encoding is taken from the "ContentType" element if this is specified; otherwise the encoding is "UTF8".
  • TimeConstraint->t allows a maximum of t seconds for connection to the URL specified in the HTTP request, and reading from it.
  • TimeConstraint-><|"Connecting"->tc,"Reading"->tr|> specifies separate timeouts for connecting to the URL, and reading from it.
  • HTTPRequest[…]["prop"] extracts the value for the property prop of the HTTP request.
  • Possible properties include all components and additional elements, as well as:
  • "Body"body of the request as a string
    "BodyByteArray"raw body of the request as a ByteArray object
    "BodyBytes"raw body of the request as a list of byte values
    "FormRules"rules for all form elements in the request
    "PathString"complete path as a string
    "QueryString"complete query string
    "AbsolutePath"complete path as a string, including scheme and domain
    "AbsoluteDomain"complete domain as a string, including scheme
    "Properties"list of all possible properties
    "PropertyAssociation"association giving values of all properties

Examples

open allclose all

Basic Examples  (1)Summary of the most common use cases

Define an HTTPRequest:

In[5]:=5
✖
https://wolfram.com/xid/0fq9ogksbh9eu-utvbs5
Out[5]=5

Get an HTTPResponse using URLRead:

In[6]:=6
✖
https://wolfram.com/xid/0fq9ogksbh9eu-pcjdx9
Out[6]=6

Extract metadata from the request:

In[7]:=7
✖
https://wolfram.com/xid/0fq9ogksbh9eu-2rrm4y
Out[7]=7

Scope  (2)Survey of the scope of standard use cases

Build a URL from components:

In[1]:=1
✖
https://wolfram.com/xid/0fq9ogksbh9eu-q51c5w
Out[1]=1

Changing query parameters and scheme for a given URL:

In[2]:=2
✖
https://wolfram.com/xid/0fq9ogksbh9eu-shlh3x
Out[2]=2

To specify parameters with the same name, you can use a list of rules:

In[3]:=3
✖
https://wolfram.com/xid/0fq9ogksbh9eu-2poj5u
Out[3]=3

Or they can be grouped in a list:

In[4]:=4
✖
https://wolfram.com/xid/0fq9ogksbh9eu-62ytwy
Out[4]=4

Grouping parameters in a list is useful when working with associations, since they do not allow repeated keys:

In[5]:=5
✖
https://wolfram.com/xid/0fq9ogksbh9eu-l05lsc
Out[5]=5

If no Method is specified, "GET" is used automatically:

In[1]:=1
✖
https://wolfram.com/xid/0fq9ogksbh9eu-7cw58r
In[2]:=2
✖
https://wolfram.com/xid/0fq9ogksbh9eu-qlffac
Out[2]=2

The body can be a raw string:

In[3]:=3
✖
https://wolfram.com/xid/0fq9ogksbh9eu-07dez0
Out[3]=3

To send an HTTP request where the body is URL encoded, you can just send a list of values. If no Method is specified, "POST" is used automatically:

In[4]:=4
✖
https://wolfram.com/xid/0fq9ogksbh9eu-e4qu0y
Out[4]=4

To send files, just use the file object:

In[5]:=5
✖
https://wolfram.com/xid/0fq9ogksbh9eu-5ndxs1
Out[5]=5

To send a more complex file specification, you can use Association:

In[6]:=6
✖
https://wolfram.com/xid/0fq9ogksbh9eu-jevsjp
Out[6]=6

Content in the Association can be a string, a ByteArray, or a File:

In[7]:=7
✖
https://wolfram.com/xid/0fq9ogksbh9eu-b7fwp2
Out[7]=7

Options  (4)Common values & functionality for each option

VerifySecurityCertificates  (1)

Verify that the SSL certificate used by the server is valid:

In[1]:=1
✖
https://wolfram.com/xid/0fq9ogksbh9eu-bb63uq
Out[1]=1

CookieFunction  (1)

Print each cookie that is returned in the HTTP response:

In[1]:=1
✖
https://wolfram.com/xid/0fq9ogksbh9eu-da9j62
Out[1]=1

TimeConstraint  (1)

Specify the maximum allotted time in seconds to finish downloading data from the server:

In[1]:=1
✖
https://wolfram.com/xid/0fq9ogksbh9eu-l2rf5q
In[2]:=2
✖
https://wolfram.com/xid/0fq9ogksbh9eu-wbzpug
Out[2]=2

FollowRedirects  (1)

Specify whether to follow HTTP redirects when retrieving a URL:

In[1]:=1
✖
https://wolfram.com/xid/0fq9ogksbh9eu-64kmq
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0fq9ogksbh9eu-48eqmb
Out[2]=2
In[3]:=3
✖
https://wolfram.com/xid/0fq9ogksbh9eu-hyx2wk
Out[3]=3

Properties & Relations  (2)Properties of the function, and connections to other functions

File and CloudObject are fully supported:

In[1]:=1
✖
https://wolfram.com/xid/0fq9ogksbh9eu-f48c8p
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0fq9ogksbh9eu-i541q7
Out[2]=2

Use URLDownload to store output in a file:

In[3]:=3
✖
https://wolfram.com/xid/0fq9ogksbh9eu-o4ap4
Out[3]=3

Import the request by using Import or URLExecute:

In[1]:=1
✖
https://wolfram.com/xid/0fq9ogksbh9eu-vijtc7
In[2]:=2
✖
https://wolfram.com/xid/0fq9ogksbh9eu-r6tewc
In[3]:=3
✖
https://wolfram.com/xid/0fq9ogksbh9eu-nb5lmg
Out[3]=3
In[4]:=4
✖
https://wolfram.com/xid/0fq9ogksbh9eu-mz0qa0
Out[4]=4

Possible Issues  (1)Common pitfalls and unexpected behavior

Network requests can go wrong for several reasons; messages are sent to help you debug possible causes, and a Failure object is returned:

In[1]:=1
✖
https://wolfram.com/xid/0fq9ogksbh9eu-dsyyqy
Out[1]=1

The Failure object contains the HTTPRequest object:

In[2]:=2
✖
https://wolfram.com/xid/0fq9ogksbh9eu-37fmie
Out[2]=2

Neat Examples  (1)Surprising or curious use cases

Import an APIFunction:

In[1]:=1
✖
https://wolfram.com/xid/0fq9ogksbh9eu-cfqwn
Out[3]=3
Wolfram Research (2016), HTTPRequest, Wolfram Language function, https://reference.wolfram.com/language/ref/HTTPRequest.html.
✖
Wolfram Research (2016), HTTPRequest, Wolfram Language function, https://reference.wolfram.com/language/ref/HTTPRequest.html.

Text

Wolfram Research (2016), HTTPRequest, Wolfram Language function, https://reference.wolfram.com/language/ref/HTTPRequest.html.

✖
Wolfram Research (2016), HTTPRequest, Wolfram Language function, https://reference.wolfram.com/language/ref/HTTPRequest.html.

CMS

Wolfram Language. 2016. "HTTPRequest." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/HTTPRequest.html.

✖
Wolfram Language. 2016. "HTTPRequest." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/HTTPRequest.html.

APA

Wolfram Language. (2016). HTTPRequest. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/HTTPRequest.html

✖
Wolfram Language. (2016). HTTPRequest. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/HTTPRequest.html

BibTeX

@misc{reference.wolfram_2025_httprequest, author="Wolfram Research", title="{HTTPRequest}", year="2016", howpublished="\url{https://reference.wolfram.com/language/ref/HTTPRequest.html}", note=[Accessed: 29-March-2025 ]}

✖
@misc{reference.wolfram_2025_httprequest, author="Wolfram Research", title="{HTTPRequest}", year="2016", howpublished="\url{https://reference.wolfram.com/language/ref/HTTPRequest.html}", note=[Accessed: 29-March-2025 ]}

BibLaTeX

@online{reference.wolfram_2025_httprequest, organization={Wolfram Research}, title={HTTPRequest}, year={2016}, url={https://reference.wolfram.com/language/ref/HTTPRequest.html}, note=[Accessed: 29-March-2025 ]}

✖
@online{reference.wolfram_2025_httprequest, organization={Wolfram Research}, title={HTTPRequest}, year={2016}, url={https://reference.wolfram.com/language/ref/HTTPRequest.html}, note=[Accessed: 29-March-2025 ]}