@jars-lt/sdk

Official Node.js SDK for JARS.LT - Lithuanian Company Registry API

Installation

npm install @jars-lt/sdk
# or
yarn add @jars-lt/sdk
# or
pnpm add @jars-lt/sdk

Quick Start

import { JarsClient } from '@jars-lt/sdk';

// Initialize the client
const client = new JarsClient({
  apiKey: 'your_api_key_here'
});

// Search for companies
const companies = await client.searchCompanies({
  q: 'UAB Maxima',
  limit: 10
});

console.log(companies.results);

API Key

Get your API key at jars.lt. Available plans:

• Free: 300 requests/month
• Starter: 5,000 requests/month
• Professional: 50,000 requests/month
• Enterprise: 1,000,000 requests/month

Usage

Initialize Client

import { JarsClient } from '@jars-lt/sdk';

const client = new JarsClient({
  apiKey: 'your_api_key_here',
  // Optional: custom base URL
  baseURL: 'https://api.jars.lt/api/v1',
  // Optional: request timeout in ms
  timeout: 30000
});

Search Companies

Search for Lithuanian companies by name or code:

const results = await client.searchCompanies({
  q: 'Maxima',
  limit: 10,
  offset: 0
});

console.log(`Found ${results.total} companies`);
results.results.forEach(company => {
  console.log(`${company.name} (${company.code})`);
});

Get Company by Code

Retrieve detailed information about a specific company:

const company = await client.getCompany('111111111');

console.log(company.name);
console.log(company.address);
console.log(company.status);
console.log(company.registrationDate);

Search Addresses

Search for streets, settlements, and municipalities. Supports multi-word search:

const results = await client.searchAddresses({
  q: 'kaunas basanavi',
  limit: 5
});

// Streets
results.streets.forEach(street => {
  console.log(`${street.name} ${street.typeAbbr}`);
  if (street.settlement) {
    console.log(`  ${street.settlement.name}`);
  }
});

// Settlements
results.settlements.forEach(settlement => {
  console.log(`${settlement.name} ${settlement.typeAbbr}`);
});

// Municipalities
results.municipalities.forEach(municipality => {
  console.log(municipality.name);
});

Get Location by Postal Code

Get county, municipality, settlement, and streets for a postal code:

const location = await client.getByPostalCode('54306');
// or with LT- prefix
const location = await client.getByPostalCode('LT-54306');

console.log('County:', location.county.name);
console.log('Municipality:', location.municipality.name);
console.log('Settlement:', location.settlement.name);

// All streets with this postal code
location.streets?.forEach(street => {
  console.log(`${street.name} ${street.typeAbbr}`);
});

Get Usage Statistics

Check your current API usage and limits:

const usage = await client.getUsage();

console.log('Plan:', usage.plan);
console.log('Requests used:', usage.requestCount);
console.log('Requests remaining:', usage.remaining);
console.log('Monthly limit:', usage.limit);
console.log('Resets on:', usage.resetDate);
console.log('Rate limit:', usage.rateLimit, 'requests/minute');

Error Handling

The SDK throws JarsAPIError for API errors:

import { JarsClient, JarsAPIError } from '@jars-lt/sdk';

try {
  const company = await client.getCompany('invalid');
} catch (error) {
  if (error instanceof JarsAPIError) {
    console.error('API Error:', error.message);
    console.error('Status Code:', error.statusCode);
    console.error('Response:', error.response);
  } else {
    console.error('Network Error:', error);
  }
}

Common error codes:

• 400 - Invalid parameters
• 401 - Invalid API key
• 404 - Resource not found
• 429 - Rate limit exceeded
• 500 - Server error

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { JarsClient, Company, SubscriptionPlan } from '@jars-lt/sdk';

const client = new JarsClient({ apiKey: 'key' });

// Fully typed responses
const company: Company = await client.getCompany('111111111');
const usage = await client.getUsage();
const plan: SubscriptionPlan = usage.plan; // 'FREE' | 'STARTER' | 'PROFESSIONAL' | 'ENTERPRISE'

Advanced Usage

Custom Axios Configuration

The SDK uses axios internally. You can access the underlying axios instance if needed:

import { JarsClient } from '@jars-lt/sdk';

const client = new JarsClient({
  apiKey: 'key',
  timeout: 60000, // 60 seconds
  baseURL: 'https://custom-api.example.com/api/v1'
});

Pagination

Handle large result sets with pagination:

async function getAllCompanies(query: string) {
  const pageSize = 100; // Max allowed
  let offset = 0;
  let allCompanies = [];

  while (true) {
    const results = await client.searchCompanies({
      q: query,
      limit: pageSize,
      offset
    });

    allCompanies.push(...results.results);

    if (results.results.length < pageSize) {
      break; // Last page
    }

    offset += pageSize;
  }

  return allCompanies;
}

Examples

Find Company and Its Address

const companies = await client.searchCompanies({ q: 'Maxima' });
if (companies.results.length > 0) {
  const company = await client.getCompany(companies.results[0].code);
  console.log(`${company.name} is located at ${company.address}`);
}

Search Streets in Kaunas

const results = await client.searchAddresses({ q: 'kaunas' });
console.log(`Found ${results.streets.length} streets in Kaunas`);

Check if API Key is Valid

try {
  const usage = await client.getUsage();
  console.log('API key is valid. Plan:', usage.plan);
} catch (error) {
  console.error('Invalid API key');
}

Rate Limits

Respect rate limits based on your plan:

• Free: 30 requests/minute
• Starter: 60 requests/minute
• Professional: 300 requests/minute
• Enterprise: 1000 requests/minute

The API returns 429 Too Many Requests when rate limit is exceeded.

Support

• Documentation: jars.lt/docs
• Contact: jars.lt/contact

License

MIT © UAB Sistemium