SDK Documentation

Integrate Sitemap.xml's powerful indexing, generation, and monitoring capabilities directly into your application with our official TypeScript/JavaScript SDK.

Overview

The Sitemap.xml SDK provides a type-safe, high-performance client for managing XML/HTML sitemaps, submitting URLs to search engines, and monitoring indexing health. It supports modern JavaScript runtimes including Node.js, Deno, Bun, and browser environments.

Note: The SDK requires Node.js 18+ or a modern browser with native Fetch API support. For legacy environments, use the polyfill adapter.

Installation

Install the package using your preferred package manager:

Terminal

# npm
npm install @sitemap/sdk

# yarn
yarn add @sitemap/sdk

# pnpm
pnpm add @sitemap/sdk

Quick Start

Initialize the client and submit your first sitemap in under 30 seconds:

index.ts

import { SitemapClient } from '@sitemap/sdk';

// 1. Initialize with your API key
const client = new SitemapClient({
  apiKey: process.env.SITEMAP_API_KEY,
  environment: 'production',
});

// 2. Discover and index your website
const result = await client.discoverAndIndex('https://example.com');

console.log(`Indexed ${result.urls} pages in ${result.duration}ms`);

// 3. Generate and submit XML sitemap
await client.submitSitemap({
  format: 'xml',
  includeRobots: true,
  engines: ['google', 'bing']
});

Configuration

The client accepts a comprehensive options object. All fields are optional except apiKey.

Parameter	Type	Default	Description
`apiKey`	string	Required	Your secret API key from dashboard
`environment`	string	'development'	Target environment for logging & analytics
`retryAttempts`	number	3	Max retry attempts for failed requests
`timeout`	number	30000	Request timeout in milliseconds
`baseUrl`	string	'https://api.sitemap.xml'	Override default API endpoint

Initialization

You can instantiate the client globally or per-request depending on your architecture. The SDK automatically handles connection pooling and circuit breaking for high-throughput scenarios.

Advanced Config

const client = new SitemapClient({
  apiKey: process.env.API_KEY,
  retryAttempts: 5,
  timeout: 45000,
  // Enable verbose logging for debugging
  logger: {
    level: 'debug',
    formatter: (msg) => console.log(`[Sitemap] ${msg}`)
  }
});

Methods

client.discoverAndIndex(url, options?)

Performs a recursive crawl of the provided URL, extracts all navigable paths, and queues them for search engine indexing. Returns a promise resolving to crawl metrics.

client.submitSitemap(config)

Generates a compliant XML/HTML sitemap and pushes it to configured search engines. Supports video, image, and news extensions.

client.getHealthStatus()

Returns real-time indexing health, coverage errors, and crawl statistics for the authenticated account.

Error Handling

The SDK throws typed errors that can be caught and handled gracefully. Use the SitemapError base class to inspect failure reasons.

Error Handling

import { SitemapClient, SitemapError } from '@sitemap/sdk';

try {
  await client.submitSitemap({ format: 'xml' });
} catch (error) {
  if (error instanceof SitemapError) {
    console.error(`Sitemap failed: ${error.code} - ${error.message}`);
    if (error.isRetryable) {
      console.log('Scheduling retry...');
    }
  } else {
    throw error;
  }
}

TypeScript Support

The SDK is written in TypeScript and ships with complete type definitions. Intellisense, autocomplete, and compile-time checking work out of the box.

Type Definitions

import { SubmitOptions, CrawlResult } from '@sitemap/sdk';

const options: SubmitOptions = {
  format: 'xml',
  compress: true,
  engines: ['google', 'bing', 'yandex']
};

const result: CrawlResult = await client.submitSitemap(options);