Metaphorsum SDKs & Libraries: Python & JavaScript (2026)

SDKs overview

Metaphorsum offers Software Development Kits (SDKs) to facilitate programmatic interaction with its API for synthetic data generation. These SDKs are designed to abstract away the complexities of direct HTTP requests, allowing developers to integrate Metaphorsum's capabilities into various applications and workflows more efficiently. The primary purpose of these libraries is to simplify tasks such as defining data schemas, generating data, and managing datasets.

The Metaphorsum API itself is RESTful, providing standard HTTP methods for resource manipulation. SDKs translate these RESTful interactions into language-specific function calls and objects, adhering to typical programming paradigms for each language. This approach aims to reduce boilerplate code and potential errors when integrating with the service, as noted in general API client best practices by organizations like Google Developers.

Currently, official SDKs are provided for Python and JavaScript, covering two widely used programming environments in web and backend development. These libraries are maintained by Metaphorsum and are the recommended method for integrating the service.

Official SDKs by language

Metaphorsum provides official SDKs to streamline integration with its API. These libraries are developed and maintained by Metaphorsum, ensuring compatibility and access to the latest features. The table below outlines the available official SDKs, their respective package names, installation commands, and maturity levels.

Each SDK provides idiomatic interfaces for common Metaphorsum operations, including:

• Schema definition and management
• Synthetic data generation based on defined schemas
• Authentication and authorization handling
• Error handling and retry mechanisms

Detailed documentation for each SDK, including API references and usage examples, is available on the Metaphorsum documentation portal.

Installation

To begin using Metaphorsum's official SDKs, developers need to install the respective packages using their language-specific package managers. The following instructions provide the commands for installing the Python and JavaScript SDKs.

Python SDK

The Python SDK can be installed using pip, the standard package installer for Python. It requires Python 3.7 or newer.

pip install metaphorsum-sdk-python

After installation, the library can be imported into Python projects:

import metaphorsum_sdk

JavaScript SDK

The JavaScript SDK is available via npm and yarn, common package managers for Node.js and frontend projects. It is compatible with Node.js environments (version 12+) and modern browser environments.

Using npm:

npm install @metaphorsum/sdk-js

Using yarn:

yarn add @metaphorsum/sdk-js

Once installed, the SDK can be imported using ES modules or CommonJS syntax:

ES Modules:

import { MetaphorsumClient } from '@metaphorsum/sdk-js';

CommonJS:

const { MetaphorsumClient } = require('@metaphorsum/sdk-js');

Quickstart example

This section provides a quickstart example demonstrating how to use the Metaphorsum SDKs to generate synthetic data. The example shows how to initialize the client, define a simple data schema, and fetch generated data using both Python and JavaScript.

Python Quickstart

This Python example generates 5 records of user data, each with a name and email, by defining a schema and then calling the generation endpoint. Before running, ensure you have set your Metaphorsum API key as an environment variable or replace os.getenv('METAPHORSUM_API_KEY') with your actual key.

import metaphorsum_sdk
import os

# Initialize the client with your API key
client = metaphorsum_sdk.MetaphorsumClient(api_key=os.getenv('METAPHORSUM_API_KEY'))

# Define a simple schema for user data
user_schema = {
    "fields": [
        {"name": "id", "type": "uuid"},
        {"name": "name", "type": "full_name"},
        {"name": "email", "type": "email"},
        {"name": "country", "type": "country"}
    ]
}

try:
    # Generate 5 records based on the schema
    generated_data = client.generate_data(schema=user_schema, count=5)
    
    print("Generated Data:")
    for record in generated_data:
        print(record)

except metaphorsum_sdk.MetaphorsumAPIError as e:
    print(f"API Error: {e.message}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

JavaScript Quickstart

This JavaScript example performs the same operation: initializing the client, defining a user schema, and generating 5 synthetic user records. Replace 'YOUR_METAPHORSUM_API_KEY' with your actual API key, or load it from an environment variable (e.g., process.env.METAPHORSUM_API_KEY in Node.js).

import { MetaphorsumClient } from '@metaphorsum/sdk-js';

// Initialize the client with your API key
const client = new MetaphorsumClient('YOUR_METAPHORSUM_API_KEY');

// Define a simple schema for user data
const userSchema = {
  fields: [
    { name: 'id', type: 'uuid' },
    { name: 'name', type: 'full_name' },
    { name: 'email', type: 'email' },
    { name: 'country', type: 'country' }
  ],
};

async function generateUserData() {
  try {
    // Generate 5 records based on the schema
    const generatedData = await client.generateData({
      schema: userSchema,
      count: 5,
    });

    console.log('Generated Data:');
    generatedData.forEach((record) => console.log(record));
  } catch (error) {
    console.error('Error generating data:', error.message);
    if (error.response) {
        console.error('API Response Data:', error.response.data);
    }
  }
}

generateUserData();

These examples demonstrate the basic workflow for generating data. For more advanced features, such as custom data types, data relationships, and larger-scale data generation, refer to the official Metaphorsum documentation.

Community libraries

While Metaphorsum provides official SDKs for Python and JavaScript, the open-source community may develop and maintain additional libraries or integrations. These community-contributed tools can extend Metaphorsum's functionality to other programming languages, frameworks, or specific use cases not covered by the official offerings.

Community libraries are typically found on platforms like GitHub, npm, PyPI, or other language-specific package repositories. Developers interested in using or contributing to community efforts are encouraged to search these platforms for metaphorsum-related projects. It is important to note that community libraries may not offer the same level of support, maintenance, or feature parity as official SDKs.

To discover potential community libraries, developers can:

• Search GitHub for repositories tagged with metaphorsum or synthetic-data.
• Explore package managers like PyPI for Python or npm for JavaScript for packages that reference Metaphorsum.
• Participate in the Metaphorsum developer community forums or chat channels, if available, to inquire about existing community-driven projects.

When considering a community library, it is advisable to review its documentation, last update date, number of contributors, and issue tracker to assess its reliability and ongoing support. The Metaphorsum team encourages community contributions and may feature notable projects on their official channels.