Comment envoyer des requêtes GET avec cURLparamètres, en-têtes, redirections et JSON

cURL est l'outil en ligne de commande de référence pour déplacer des données sur le réseau. Il parle HTTP, HTTPS et une longue liste d'autres protocoles, et il est installé sur presque toutes les machines que vous croiserez, c'est donc le premier réflexe de la plupart des ingénieurs lorsqu'ils doivent inspecter un point de terminaison, tester une API ou récupérer une page. La méthode GET est au cœur de tout cela : c'est ainsi que vous demandez une ressource à un serveur et que vous lisez ce qui revient.

Ce guide est une présentation ciblée de la façon d'envoyer des requêtes GET avec cURL. Vous partirez de la commande nue, puis vous ajouterez des paramètres de requête, des en-têtes, des redirections, la gestion du JSON et les options qui vous laissent voir exactement ce que le serveur a envoyé. À la fin, vous saurez piloter cURL suffisamment bien pour du débogage réel et de petits travaux de scraping, et vous saurez où une simple requête GET cesse de suffire.

Ce que fait réellement une requête GET

GET est la méthode HTTP la plus simple et la plus courante. Lorsque vous ouvrez une URL dans un navigateur, celui-ci envoie une requête GET au serveur, et le serveur répond avec la ressource : du HTML, une image, une charge utile JSON, quoi que ce soit qui réside à cette adresse. GET ne fait que lire. Il n'envoie pas de corps pour créer ou modifier quoi que ce soit comme le font POST ou PUT, ce qui en fait la bonne méthode pour récupérer des pages, appeler des points de terminaison d'API en lecture seule et télécharger des ressources statiques.

cURL utilise GET par défaut, vous n'avez donc jamais à nommer la méthode pour une simple récupération. La requête la plus courte possible est le nom du programme suivi d'une URL :

curl https://httpbin.org/get

Cela affiche le corps de la réponse dans votre terminal. httpbin.org est un service gratuit d'inspection de requêtes qui renvoie tout ce qu'il reçoit, ce qui le rend idéal pour apprendre : chaque exemple ci-dessous l'utilise, afin que vous puissiez exécuter les commandes et voir exactement ce que cURL a envoyé. Si vous souhaitez à un moment être explicite sur la méthode, -X GET ou --request GET l'indique noir sur blanc, mais pour un GET normal c'est redondant.

Passer des paramètres de chaîne de requête

La plupart des points de terminaison réels attendent des paramètres. Une chaîne de requête est la partie d'une URL située après le ?, écrite sous forme de paires key=value jointes par &. La façon la plus directe de les envoyer est de les placer directement dans l'URL, entre guillemets pour que votre shell n'essaie pas d'interpréter le & comme une tâche en arrière-plan :

curl 'https://httpbin.org/get?city=Berlin&page=2'

Les guillemets simples comptent. Sans eux, le shell voit le & et coupe la commande, alors mettez toujours entre guillemets toute URL qui contient &, ? ou des espaces.

cURL peut aussi assembler la chaîne de requête pour vous avec -G et -d. L'option -d construit normalement un corps de requête POST, mais ajouter -G indique à cURL de prendre ces données et de les ajouter à l'URL sous forme de chaîne de requête GET :

curl -G \
  -d "city=Berlin" \
  -d "page=2" \
  https://httpbin.org/get

Les deux commandes produisent la même requête. La forme -G se lit mieux lorsque vous avez plusieurs paramètres ou que vous les générez dans un script, puisque chaque paire est sa propre option et que vous n'avez pas à construire à la main la chaîne ?key=value&key=value.

Encoder en URL les valeurs des paramètres

Un simple -d n'encode rien, donc une valeur contenant un espace, une esperluette ou une barre oblique cassera la chaîne de requête. Lorsque la valeur n'est pas déjà sûre, utilisez --data-urlencode conjointement avec -G. cURL encode la valeur pour vous et l'ajoute quand même comme paramètre de requête :

curl -G \
  --data-urlencode "q=web scraping & data" \
  --data-urlencode "sort=date desc" \
  https://httpbin.org/get

Dans la réponse renvoyée, vous verrez les espaces transformés en %20 et l'esperluette en %26, ce qui est exactement ce qu'un serveur attend. Utilisez --data-urlencode dès qu'une valeur provient d'une saisie utilisateur ou contient autre chose que des lettres, des chiffres et de la ponctuation de base. Cela vous épargne la chasse plus tard à des bugs d'encodage subtils et difficiles à repérer.

Ajouter des en-têtes de requête

Les en-têtes transportent des métadonnées sur votre requête : quel type de contenu vous acceptez, quel agent utilisateur vous prétendez être, un jeton d'autorisation, et plus encore. L'option -H définit un en-tête par utilisation, et vous pouvez la répéter autant de fois que nécessaire :

curl \
  -H "Accept: application/json" \
  -H "User-Agent: my-script/1.0" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://httpbin.org/headers

Le point de terminaison /headers renvoie chaque en-tête qu'il a reçu, vous pouvez donc confirmer que cURL a envoyé exactement ce que vous vouliez. Définir un User-Agent réaliste et un en-tête Accept explicite est aussi le premier petit pas pour que les requêtes automatisées ressemblent moins à un script cURL par défaut, ce qui compte une fois que vous commencez à récupérer de vrais sites. Pour un traitement plus approfondi de la gestion des en-têtes, voir comment envoyer des en-têtes HTTP avec cURL.

Enregistrer le corps dans un fichier

Par défaut, cURL diffuse la réponse vers la sortie standard. Pour l'écrire dans un fichier à la place, utilisez -o avec un nom de fichier de votre choix, ou -O pour réutiliser le nom de fichier distant tiré de l'URL :

# write to a name you pick
curl -o page.html https://httpbin.org/html

# keep the remote filename
curl -O https://httpbin.org/image/png

Utilisez -O pour les téléchargements où le serveur nomme déjà le fichier de manière sensée, et -o quand vous voulez contrôler où les octets atterrissent. Ajoutez -s (silencieux) pour supprimer la barre de progression lorsque vous scriptez, et -f (fail) pour que cURL renvoie un code de sortie non nul en cas d'erreurs HTTP au lieu d'enregistrer joyeusement une page d'erreur.

Voir les en-têtes et le statut, pas seulement le corps

Lorsque vous déboguez, le corps est souvent la partie la moins intéressante. cURL vous offre plusieurs façons d'inspecter les métadonnées de la réponse. -i ajoute les en-têtes de réponse en tête du corps, -I envoie une requête HEAD et n'affiche que les en-têtes, et -D - déverse les en-têtes vers une destination (ici - désigne la sortie standard) tandis que le corps va là où -o l'envoie :

# body with headers on top
curl -i https://httpbin.org/get

# headers only (HEAD request)
curl -I https://httpbin.org/get

# headers to stdout, body to a file
curl -D - -o body.html https://httpbin.org/html

Utilisez -I quand seules les métadonnées vous intéressent, comme le type de contenu, la longueur du contenu, les en-têtes de cache ou la ligne de statut, sans télécharger toute la charge utile. C'est le moyen rapide de vérifier si une ressource existe ou de quel type elle est avant de vous engager à la récupérer.

Suivre les redirections

Les serveurs répondent fréquemment à un GET par une redirection 301 ou 302 pointant ailleurs. cURL ne suit pas les redirections de lui-même, donc une simple requête contre une URL qui redirige renvoie la courte réponse de redirection, pas la page finale. Ajoutez -L (location) pour que cURL poursuive la redirection jusqu'à sa destination :

curl -L "https://httpbin.org/redirect-to?url=https://httpbin.org/get"

Sans -L vous obtenez la redirection elle-même ; avec, vous obtenez le contenu à l'URL finale. Si vous voulez plafonner le nombre de sauts que cURL suivra, ajoutez --max-redirs avec un nombre pour qu'une boucle de redirection ne puisse pas tourner indéfiniment.

Afficher le code de statut et le chronométrage

Pour les vérifications d'état et les scripts, vous voulez souvent un seul fait, comme le code de statut HTTP ou la durée de la requête, plutôt que toute la réponse. L'option -w (write-out) affiche les variables choisies après le transfert. Associez-la à -o /dev/null pour jeter le corps et à -s pour rester discret :

# just the status code
curl -s -o /dev/null -w "%{http_code}\n" https://httpbin.org/get

# status plus total time in seconds
curl -s -o /dev/null \
  -w "status=%{http_code} time=%{time_total}s\n" \
  https://httpbin.org/get

La première commande affiche quelque chose comme 200 et rien d'autre, ce qui est parfait pour une condition de shell ou une tâche cron de surveillance. D'autres variables -w utiles incluent %{size_download}, %{num_redirects} et %{url_effective}, cette dernière étant pratique pour voir où une chaîne de redirections a réellement abouti.

Gérer les réponses d'API JSON

De nombreux points de terminaison GET renvoient du JSON. Pour signaler que vous voulez du JSON, définissez l'en-tête Accept, et pour lire le résultat confortablement, redirigez la sortie de cURL vers jq, le processeur JSON en ligne de commande. jq met en forme la charge utile et vous laisse sélectionner des champs avec un petit langage de requête :

# pretty-print the whole JSON response
curl -s -H "Accept: application/json" https://httpbin.org/get | jq .

# pull a single field out of the response
curl -s https://httpbin.org/get | jq '.headers["User-Agent"]'

L'option -s est importante lors du pipe : elle retire la barre de progression pour que seul du JSON propre atteigne jq. À partir de là, vous pouvez extraire exactement les valeurs dont vous avez besoin, ce qui transforme cURL plus jq en un client d'API rapide et scriptable sans écrire une ligne de code de programme.

Mode verbeux pour le débogage

Quand une requête se comporte d'une manière que vous ne pouvez pas expliquer, -v (verbose) montre toute la conversation : la configuration DNS et TLS, la ligne de requête exacte et les en-têtes que cURL a envoyés (préfixés par >), ainsi que le statut et les en-têtes de réponse qu'il a reçus (préfixés par <) :

curl -v https://httpbin.org/get

La sortie verbeuse est le moyen le plus rapide de répondre à des questions comme "mon en-tête a-t-il vraiment été envoyé ?" ou "où va cette redirection ?" Si vous devez capturer les octets bruts pour un rapport de bug, --trace-ascii trace.txt écrit un journal encore plus détaillé dans un fichier.

Là où une simple requête GET cesse de suffire

Une requête GET est le fondement du web scraping : récupérer une page, c'est au fond envoyer un GET et lire le HTML qui revient. Pour les pages statiques et les API conviviales, cURL seul fait le travail. Les murs se dressent dès que vous le pointez vers des sites commerciaux modernes. Deux limites apparaissent vite.

Premièrement, cURL récupère le HTML brut et rien de plus. Il n'exécute pas JavaScript, donc toute page qui construit son contenu dans le navigateur ne livre à cURL qu'une coquille presque vide. Deuxièmement, les sites qui ne veulent pas de bots surveillent le trafic en forme de scraper : un User-Agent par défaut, une IP de centre de données et une rafale de requêtes depuis une seule adresse se font défier ou bloquer, souvent avec un CAPTCHA, bien avant que vous n'ayez collecté quoi que ce soit d'utile. Vous pouvez masquer une partie de cela en faisant tourner les IP et en rendant les pages vous-même. Voir cURL pour le web scraping et comment utiliser cURL avec un proxy pour ces techniques, mais entretenir une flotte de navigateurs sans interface et un pool de proxys sain devient vite l'essentiel du travail.

Comme l'API accepte un GET normal, vos connaissances cURL existantes s'y appliquent directement. Vous appelez son point de terminaison avec deux paramètres de requête, votre token et l'URL que vous voulez, et le HTML rendu revient dans le corps de la réponse :

curl -G https://api.crawlbase.com/ \
  --data-urlencode "token=YOUR_CRAWLBASE_TOKEN" \
  --data-urlencode "url=https://www.example.com"

C'est le même schéma -G plus --data-urlencode vu plus tôt, ce qui explique pourquoi il importe de bien gérer l'encodage : l'URL cible est elle-même une valeur à l'intérieur de la chaîne de requête, elle doit donc être encodée proprement. Remplacez le token normal par le token JavaScript quand la cible se rend côté client, et l'API exécute la page dans un vrai navigateur avant de renvoyer le HTML.

Foire aux questions

Dois-je spécifier la méthode pour envoyer une requête GET avec cURL ?

Non. cURL utilise GET par défaut, donc curl https://example.com envoie déjà une requête GET. Vous pouvez l'écrire explicitement sous la forme curl -X GET https://example.com si vous voulez être explicite, mais cela ne change rien pour une récupération normale. Vous n'avez besoin de -X que lorsque vous voulez une méthode différente, comme -X POST ou -X DELETE.

Comment passer des paramètres de requête dans une requête GET cURL ?

De deux façons. Mettez-les directement dans l'URL entre guillemets, comme curl 'https://example.com/data?a=1&b=2', ou laissez cURL construire la chaîne de requête avec curl -G -d "a=1" -d "b=2" https://example.com/data. Les deux envoient la même requête. Si une valeur contient des espaces, des esperluettes ou d'autres caractères spéciaux, remplacez les options -d par --data-urlencode pour que cURL les encode correctement.

Comment voir uniquement le code de statut HTTP ?

Utilisez l'option write-out tout en jetant le corps : curl -s -o /dev/null -w "%{http_code}\n" https://example.com. Le -s masque la barre de progression, -o /dev/null jette le corps de la réponse, et -w "%{http_code}\n" affiche uniquement le statut numérique. C'est la formule standard en une ligne pour les vérifications d'état et les conditions de shell.

Pourquoi cURL ne suit-il pas une redirection ?

cURL ne suit pas les redirections sauf si vous le lui demandez. Lorsqu'un serveur renvoie un 301 ou un 302, une simple requête vous montre cette courte réponse de redirection plutôt que la destination. Ajoutez -L (ou --location) et cURL suivra la redirection jusqu'à l'URL finale. Utilisez --max-redirs pour limiter le nombre de sauts qu'il poursuivra.

Comment récupérer et lire du JSON depuis une API avec cURL ?

Définissez l'en-tête Accept et redirigez la sortie vers jq. Par exemple, curl -s -H "Accept: application/json" https://example.com/api | jq . met en forme la charge utile, et jq '.field' extrait une valeur précise. L'option -s garde la barre de progression hors du pipe pour que seul du JSON propre atteigne jq.

Puis-je scraper un site riche en JavaScript avec une requête GET cURL ?

Pas directement. cURL récupère le HTML brut mais n'exécute pas JavaScript, donc les pages qui rendent leur contenu dans le navigateur reviennent presque vides, et les systèmes anti-bot bloquent vite le trafic cURL par défaut. Pour gérer ces cibles, envoyez le GET via un service de rendu comme la Crawling API, qui exécute la page dans un vrai navigateur derrière une IP résidentielle tournante et renvoie le HTML fini que vous pouvez analyser.

HR

Hassan Rehan

Ingénieur logiciel · Crawlbase

Ingénieur logiciel chez Crawlbase, il rédige des guides pratiques sur les proxys rotatifs, le scraping et les détails concrets de l'intégration de proxys dans du vrai code.