@vintr/node-sdk

Installation

Install the SDK with npm:

npm install @vintr/node-sdk


The SDK includes TypeScript type declarations, so you get autocomplete and type checking automatically.

Create a client

Import Vintr and create a client with your secret key:

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

const vintr = new Vintr('YOUR_VINTR_SECRET_KEY');


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

Resolve an alias

Use vintr.alias.resolve() to resolve an alias:

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


The method takes one parameter:

Parameter	Type	Required	Description
alias	string	Yes	The Vintr alias you want to resolve.

The alias should include the full suffix, for example:

apple#vintr
asteik#vintr
sushi#vintr

Response

The response contains the alias, its type, location, and timestamps.

For example:

{
  "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"
}

Working with the response
Address

The address is available under location.address.

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

console.log(result.location.address.line1);
console.log(result.location.address.city);
console.log(result.location.address.state);
console.log(result.location.address.postal_code);
console.log(result.location.address.country);

Coordinates

Coordinates are available under location.geo.

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

console.log(result.location.geo.latitude);
console.log(result.location.geo.longitude);


The response also includes precision_meters, which tells you the precision of the coordinates.

altitude can be null when it isn't available.

Instructions

Location instructions are available under location.instructions.

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

console.log(result.location.instructions.general);
console.log(result.location.instructions.delivery);
console.log(result.location.instructions.autonomous);


These three fields are intended for different kinds of information:

general — general information about accessing the location
delivery — instructions for deliveries
autonomous — instructions for autonomous systems
TypeScript

The SDK includes exported TypeScript types.

You can import them like this:

import type {
  AliasResponse,
  Location,
  Address,
  Geo,
  Instructions
} from '@vintr/node-sdk';


For example:

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'
});


This gives you type checking and autocomplete when working with the response.

Error handling

If an alias cannot be resolved, the API can return an error.

The two main errors are:

400 — Invalid alias

The alias format is invalid.

{
  "error": "Invalid alias format"
}

404 — Alias not found

The alias does not exist.

{
  "error": "Not found"
}


You can handle errors using try/catch:

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

  console.log(result);
} catch (error) {
  console.error('Failed to resolve alias:', error);
}

Complete example

Here's a small Node.js example from start to finish:

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

const vintr = new Vintr('YOUR_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

Your Vintr secret key gives your application access to the API.

Keep it on your backend and load it from an environment variable rather than putting it directly in your source code.

For example:

VINTR_SECRET_KEY=your_secret_key


Then:

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 don't use Node.js, or you prefer making HTTP requests yourself, you can use the Vintr API directly.

See the Quickstart for the API integration guide.

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

The SDK is intentionally minimal. Install it, create a client, and resolve an alias.