API Reference

The Free Sitemaps API is organized around REST. It has predictable responses based on the input provided. All API routes accept GET requests and only take in URL parameters. The returned response from any request is always an HTTP status code and JSON-encoded data.

Authentication

Free Sitemaps's API uses API keys for authentication. Your API key must be sent with every request or else the request will fail. To generate an API key, visit Generate Key. Your key will be passed as a URL parameter called key. All requests can be run through HTTP or HTTPS however, HTTPS is preferred.

Errors

The Free Sitemaps API uses conventional HTTP status codes to communicate errors. There are four common status codes that you may encounter. These include 200, 400, 403 and 404. The 200 status code indicates that your request was processed successfully and that everything has worked. In addition, the JSON response data will be returned.

The 400 status code represents an error in user input. There are two possible reasons a 400 status code could be returned. The first reason is that the user did not provide all the necessary parameters that the endpoint needs. If this is the case, the following message will be returned, "One or more of the required parameters are missing". The second reason a 400 status code could be returned is that the user entered invalid parameters. Usually, this occurs when the domain provided is invalid. If this is the case, the endpoint will respond with "The domain entered is invalid".

A 403 status code represents an unauthorized request. This occurs when you try making a request with an API key that is invalid or does not exist. You will receive a message saying "Forbidden". Lastly, a 404 status code occurs when you try making a request to a non-existent endpoint. Make sure that you have the correct URL endpoint. In many cases, the endpoint URL will be correct but the request method will not. In that case, always make sure you are making GET requests and not POST requests.

Endpoints

At the moment, the Free Sitemaps API has only two endpoints. One of these endpoints is for crawling a website and getting all the links on that site. The other endpoint is for generating a sitemap given a domain. Both endpoints use GET requests and take in the same parameters.

GET https://free-sitemaps.com/v1/api/crawl
GET https://free-sitemaps.com/v1/api/sitemap

The v1/api/crawl endpoint can be accessed in Node JS as follows:

const axios = require("axios")

axios.get("https://free-sitemaps.com/v1/api/crawl?key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&domain=example.org").then(response => {
  const data = response.data
  console.log(data)
})

In the example above, notice the parameters used. The key and domain parameters are both essential for this endpoint.

Accessing the v1/api/sitemap endpoint is a similar process. The snippet below demonstrates how to access the endpoint.

const axios = require("axios")
            
axios.get("https://free-sitemaps.com/v1/api/sitemap?key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&domain=example.org").then(response => {
  const data = response.data
  console.log(data)
})

Requests

The v1/api/crawl and v1/api/sitemap endpoints take in a key and a domain parameter. Both parameters are required for the endpoint to return a valid response. The v1/api/sitemap endpoint takes an additional optional parameter called file. When set to true, the endpoint will return a string that contains the contents of the sitemap file.

Responses

The v1/api/crawl and v1/api/sitemap endpoints both return encoded JSON responses. The v1/api/crawl endpoint returns a JSON object containing one key value pair. The key is called "links" and is an array of all the links found on the website. Below, is a sample response:

{
  "links": [
    "https://free-sitemaps.com/",
    "https://free-sitemaps.com/email-validator",
    "https://free-sitemaps.com/favicon-generator",
    "https://free-sitemaps.com/about",
    "https://free-sitemaps.com/contact"
  ]
}

The v1/api/sitemap returns one of two responses depending on the file parameter. If file does not equal false (unset or other value), the returned response will be a link to the sitemap file generated. Below is a an example:

{
  "file": "https://free-sitemaps.com/sitemap-4020649692.xml"
}

If file is set to false (file=false), the response returned will be a the text content of the generated sitemap. Refer to the example below:

{
  "sitemap": "<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><!--Created by free-sitemaps.com--><!--Total Links: 8--><url><loc>https://free-sitemaps.com/</loc><priority>1.0</priority><lastmod>2023-10-04</lastmod></url><url><loc>https://free-sitemaps.com/blog</loc><priority>0.80</priority><lastmod>2023-10-04</lastmod></url><url><loc>https://free-sitemaps.com/about</loc><priority>0.80</priority><lastmod>2023-10-04</lastmod></url><url><loc>https://free-sitemaps.com/contact</loc><priority>0.80</priority><lastmod>2023-10-04</lastmod></url><url><loc>https://free-sitemaps.com/email-validator</loc><priority>0.80</priority><lastmod>2023-10-04</lastmod></url><url><loc>https://free-sitemaps.com/favicon-generator</loc><priority>0.80</priority><lastmod>2023-10-04</lastmod></url><url><loc>https://free-sitemaps.com/blog/upload-sitemap</loc><priority>0.80</priority><lastmod>2023-10-04</lastmod></url><url><loc>https://free-sitemaps.com/blog/upload-favicon</loc><priority>0.80</priority><lastmod>2023-10-04</lastmod></url></urlset>"
}

Please note: that the response is not exactly the same as the one shown above. This is because the data is JSON encoded. Charcters such as " will be escaped with \". The response data will also include spaces and new line characters (\n).