Run DNS lookup (dig) with HTTP using the Globalping API

Need to run a DNS lookup from your web app, serverless function, or edge app? While the traditional dig command may not be available in these environments, we've got great news for you: you can run dig with HTTP using our API.

In this blog post, we'll show how you can use the Globalping API to run dig with HTTP from anywhere you can make an HTTP request.

Why you may not be able to run dig or other DNS tools

dig (domain information groper) is a handy tool for querying DNS name servers to get information about a host. It's an essential part of any good network troubleshooting toolbox, allowing you to get a host's IP address, mail servers, and other DNS records.

However, depending on your environment, you may not be able to run dig:

Environmental restrictions: dig or network access over UDP may simply not be supported in the environment in which you need to run it. This is the case, for example, in your web app's JavaScript frontend, serverless functions, and edge applications, where you don't have access to shell commands and are limited to HTTP connections.
Security restrictions: In some high-security regulated environments, networking utilities like dig are disabled to prevent unauthorized access or actions.

So, what can you do if you find yourself in a situation where you need to perform DNS lookups but are unable to? While the standard dig command can't help you here, running dig with HTTP through an API could be a great solution for you.

Running dig with HTTP using the Globalping API

Globalping is an open-source network measurement platform that allows you to run useful network tests like ping, traceroute, mtr, dig, and curl from virtually anywhere in the world. It offers various tools and integrations, so you can perform network measurements directly from places like Slack, your browser, your terminal, or your AI assistant.

All these integrations are powered by the Globalping API, which can also be queried directly. This is especially useful if you're building tools that need network measurements.

In environments where running dig isn't possible because of environmental or security restrictions, the Globalping API provides a solution by allowing DNS lookups through simple HTTP requests. This means you don't need to worry about whether your environment supports dig because all you need is the ability to make an HTTP request.

How to use the Globalping API

Let's explore how you can use the Globalping API to run dig with HTTP. For this, we'll use the "Try" feature in our API reference, so head over there to create your first network measurement.

Before we start, we have some points for you to consider:

Authentication: While authentication isn't required, we recommend you sign up for a free Globalping Dashboard account and then authenticate your API calls to get increased API limits. Check the Globalping API reference for more information on how authentication works.
API limits: Be aware that limits apply to the number of tests, not API calls. This means, if you run four DNS tests in one API call, it counts as four tests against your limit. Also, if you're not authenticated, the limits apply per IP address.

We'll be using two API endpoints to create a DNS lookup and get its results:

POST /measurements: Creates a new measurement.
GET /measurements/{id}: Retrieves the measurement results.

💡

Note: In the Globalping API (and all tools and integrations), the "dig" command is called "dns". This is because it works differently from the traditional dig tool. Our version has its own set of flags and features designed to give you a straightforward experience for DNS lookups. To see all the options you can use, check out the API reference.

Running a basic DNS lookup with HTTP

Step 1: Create a new measurement

To create and run the test, you'll need to send a POST request to the /measurements endpoint with a JSON body containing your DNS test details.

Let's say we want to run a dig test against globalping.io from a probe in Germany and another in New York:

The respective curl command:

curl -X POST https://api.globalping.io/v1/measurements \
  --header 'Content-Type: application/json' \
  --data '{
    "target": "globalping.io",
    "type": "dns",
    "locations": [
      {"country": "DE"},
      {"city": "New York"}
    ]
  }'

When successful, the API will return the measurement ID, which you'll need to fetch the results in the next step.

Step 2: Retrieve the DNS results

Network measurements can take a few moments to finish. Check the status in the response: if it's anything other than in-progress, the final results are ready.

❗

Important: Follow our polling best practices to avoid exceeding your API limits!

Provide the measurement ID you received earlier to fetch the results:

The respective curl:

curl -X GET https://api.globalping.io/v1/measurements/your-measurement-id-goes-here

Let's break down the most important data in the JSON response body:

results.probe: Information about the probe that ran the test, including the geographical location, ASN, and DNS resolvers.
results.result: This is where you can find the DNS results.
- rawOutput: The raw text output, just as you'd see it from a terminal.
- statusCode: The DNS response code.
- resolver: The hostname or IP of the resolver that answered the query.
- answers: Lists the resource records received, including the record domain name, record type, TTL, and the record's value.
- timings.total: The total query times in milliseconds.

Creating advanced dig tests with Globalping

Now let's explore some more complex examples to show the different results you can get by changing the data in your request body.

Use the "magic" location field

Instead of manually specifying location attributes like country, network, or tags, you can use the magic field to simplify selecting a test location. The magic field lets you provide location data as a simple string, and the API will find probes that best match your input. You can also use the + operator to create filters that let you define more precise locations. For example, US+Comcast will target a probe within the Comcast network in the US.

Here are some examples:

{
    "target": "globalping.io",
    "type": "dns",
    "locations": [
        {
            "magic": "US+Comcast"
        },
        {
            "magic": "AS13335"
        },
        {
            "magic": "JP+Google"
        }
    ]
}

💡

Tip: If you don't provide any location data, the API will pick random probes for you.

Use command-specific options

Under measurementOptions, you can define a couple of DNS-specific options:

query: The type of DNS query to perform (for example, MX, AAAA, SRV), defaulting to A.
resolver: The DNS resolver you want to use for the query. You can define a hostname, IPv4, or IPv6 (experimental) address.
protocol: Use either UDP (default) or TCP.
port: The port number to send your query to.
ipVersion: Use IP version 4 (default) or 6 (experimental).
trace: Enables tracing of the delegation path from the root servers down to the target domain name.

This example performs an MX (Mail Exchange) record lookup using the public resolver 8.8.8.8 and the TCP protocol:

{
  "type": "dns",
  "target": "example.com",
  "measurementOptions": {
    "query": {
      "type": "MX"
    },
    "resolver": "8.8.8.8",
    "protocol": "TCP"
  }
}

Enable DNS tracing

By setting the trace option to true under measurementOptions, you can perform a complete DNS resolution path lookup. This starts at the root nameservers and follows the referral down to the authoritative nameserver for the requested domain. This can be useful if you need to pinpoint resolution issues or understand DNS hierarchy.

For example:

{
  "type": "dns",
  "target": "globalping.io",
  "measurementOptions": {
    "trace": true
  }
}

💡

Note: The JSON result for a traced DNS query looks slightly different from the standard DNS query. It includes a hops array that represents each step in the DNS resolution process. For each hop, you get the details on the resolver, the received answers, and query timings. Take a look at the respective schemas to see the differences.

Conclusion

In this guide, we showed you how you can run dig tests with HTTP using the Globalping API. You should now be able to get DNS test results, whether you're working with a JavaScript app or a serverless function.

Tip: If you're looking to integrate this functionality more thoroughly into your projects, particularly in Node.js environments such as edge computing workloads, consider using our TypeScript library.

Otherwise, visit the Globalping API and use the "Try" feature to play around with some DNS tests for free.