Node.js SDK

The Vintr Node.js SDK is a small wrapper around the Vintr. API — a simple way to resolve aliases from Node.js or TypeScript, with built-in type declarations for autocomplete and type checking.

Installation

npm install @vintr/node-sdk

Create a client

import { Vintr } from '@vintr/node-sdk';

const vintr = new Vintr('YOUR_VINTR_SECRET_KEY');

Keep your secret key on your server. Never expose it in browser or client-side code.

Resolve an alias

const location = await vintr.alias.resolve({
  alias: 'apple#vintr'
});

Parameter	Type	Required	Description
`alias`	string	Yes	The Vintr alias to resolve, including its suffix (e.g. `apple#vintr`, `sushi#vintr`)

Response

{
  "alias": "apple#vintr",
  "type": "business",
  "location": {
    "address": {
      "line1": "1 Apple Park Way",
      "line2": "",
      "line3": "",
      "city": "Cupertino",
      "state": "California",
      "postal_code": "95014",
      "country": "US"
    },
    "geo": {
      "latitude": 37.335,
      "longitude": -122.0092,
      "altitude": null,
      "precision_meters": 5
    },
    "instructions": {
      "general": "Enter through the main visitor entrance.",
      "delivery": "Use the designated delivery entrance.",
      "autonomous": "Approach from the east access road."
    }
  },
  "createdAt": "2026-08-18T20:39:52.671Z",
  "updatedAt": "2026-08-18T20:39:52.671Z"
}

Address — available under location.address
Coordinates — available under location.geo, including precision_meters. altitude can be null when unavailable.
Instructions — available under location.instructions:
- general — accessing the location
- delivery — for deliveries
- autonomous — for autonomous systems

TypeScript

import { Vintr } from '@vintr/node-sdk';
import type { AliasResponse } from '@vintr/node-sdk';

const vintr = new Vintr('YOUR_VINTR_SECRET_KEY');

const result: AliasResponse = await vintr.alias.resolve({
  alias: 'apple#vintr'
});

Other exported types: Location, Address, Geo, Instructions.

Error handling

Code	Meaning	Example
`400`	Invalid alias format	`{ "error": "Invalid alias format" }`
`404`	Alias not found	`{ "error": "Not found" }`

try {
  const result = await vintr.alias.resolve({ alias: 'apple#vintr' });
  console.log(result);
} catch (error) {
  console.error('Failed to resolve alias:', error);
}

Complete example

import { Vintr } from '@vintr/node-sdk';

const vintr = new Vintr(process.env.VINTR_SECRET_KEY!);

async function main() {
  try {
    const result = await vintr.alias.resolve({ alias: 'apple#vintr' });

    console.log('Alias:', result.alias);
    console.log('Type:', result.type);
    console.log('Address:', result.location.address.line1, result.location.address.city);
    console.log('Coordinates:', result.location.geo.latitude, result.location.geo.longitude);
    console.log('Delivery instructions:', result.location.instructions.delivery);
  } catch (error) {
    console.error('Failed to resolve alias:', error);
  }
}

main();

Keep your API key private

Load your secret key from an environment variable rather than hardcoding it:

VINTR_SECRET_KEY=your_secret_key

import { Vintr } from '@vintr/node-sdk';

const vintr = new Vintr(process.env.VINTR_SECRET_KEY!);

Never commit your secret key to a public repository or expose it to users.

API alternative

The SDK is optional. If you’re not using Node.js, or prefer raw HTTP requests, see the Quickstart for the API integration guide.


Package	`@vintr/node-sdk`
Version	1.0.0
Language	TypeScript / JavaScript
Runtime	Node.js

The SDK is intentionally minimal: install it, create a client, resolve an alias.

Getting Started

API Reference

Installation

Create a client

Resolve an alias

Response

TypeScript

Error handling

Complete example

Keep your API key private

API alternative

​Installation

​Create a client

​Resolve an alias

​Response

​TypeScript

​Error handling

​Complete example

​Keep your API key private

​API alternative

Installation

Create a client

Resolve an alias

Response

TypeScript

Error handling

Complete example

Keep your API key private

API alternative