CubieLookup

Official Node.js wrapper for the CubieLookup REST API.

CubieLookup provides public data lookups for IP geolocation, ASN, BIN/card, Brazilian CEP, DDD, DDI, MAC addresses, CPF, and CNPJ.

Get an API Kky

Installation

Requires Node.js 18+ 

npm install cubie-lookup

Quick Start

const CubieLookup = require("cubie-lookup");

// API key is optional. (Requests can be rate-limited without one)
const cl = CubieLookup("your-api-key");

(async () => {
  // All methods return a Promise that resolves to the raw API JSON object.
  const ip = await cl.ip("8.8.8.8");
  console.log(ip.asn);      // "AS15169"
  console.log(ip.country);  // "United States"
  console.log(ip.city);     // "Mountain View"
})();

API

CubieLookup(apiKey?)

Creates and returns a client instance. apiKey is optional, if omitted, requests are sent without a Authorization header.

const cl = CubieLookup();              // unauthenticated
const cl = CubieLookup("my-api-key"); // authenticated

Methods

All methods return a Promise that resolves to the raw JSON object from the API.

cl.ip(address)

IP geolocation, ASN, and ISP lookup.   Pass "meu-ip" to look up the caller's own IP.

(async () => {
  const ip = await cl.ip("8.8.8.8");
  console.log(ip.ip);         // "8.8.8.8"
  console.log(ip.country);    // "United States"
  console.log(ip.isp);        // "Google LLC"
  console.log(ip.asn);        // "AS15169"
  console.log(ip.asn_info);   // { ... }

  // Access any field directly
  const { city, timezone } = await cl.ip("1.1.1.1");
})();

cl.asn(asnNumber)

ASN routing, country, and organization lookup.

(async () => {
  const asn = await cl.asn(15169);
  // or
  const asn = await cl.asn("AS15169");

  console.log(asn.description);   // "GOOGLE"
  console.log(asn.country);       // "United States"
  console.log(asn.network_role);  // "Transit"
})();

cl.bin(binNumber)

Card issuer lookup by BIN prefix (first 6 digits).

(async () => {
  const bin = await cl.bin(411111);
  console.log(bin.brand);   // "Visa"
  console.log(bin.type);    // "Credit"
  console.log(bin.issuer);  // "JPMorgan Chase Bank"
})();

cl.card(number)

Full card number validation and issuer info (13–19 digits).

(async () => {
  const card = await cl.card("4111111111111111");
  console.log(card.valid);   // true
  console.log(card.brand);   // "Visa"
  console.log(card.issuer);  // "JPMorgan Chase Bank"
})();

cl.cep(cepCode)

Brazilian postal code (CEP) address lookup.

(async () => {
  const cep = await cl.cep("01001000");
  console.log(cep.street);    // "Praça da Sé"
  console.log(cep.cityName);  // "São Paulo"
  console.log(cep.state);     // "SP"
})();

cl.ddd(dddCode)

Brazilian area code (DDD) lookup.

(async () => {
  const ddd = await cl.ddd(81);
  console.log(ddd.state_full); // "Pernambuco"
  console.log(ddd.area);       // "Região Metropolitana do Recife e Agreste"
})();

cl.ddi(ddiCode)

International dialing code (DDI) lookup.

(async () => {
  const ddi = await cl.ddi(55);
  console.log(ddi.country);   // "Brazil"
  console.log(ddi.capital);   // "Brasília"
})();

cl.mac(macAddress)

MAC address OUI/manufacturer lookup.

(async () => {
  const mac = await cl.mac("00-1A-2B-3C-4D-5E");
  console.log(mac.org);      // "Example Inc."
  console.log(mac.registry); // "MA-L"
})();

cl.cpf(cpfNumber)

Brazilian CPF validation and issuing region.

(async () => {
  const cpf = await cl.cpf("12345678909");
  console.log(cpf.valid);   // true
  console.log(cpf.region);  // "Pernambuco, Rio Grande do Norte, Paraiba ou Alagoas"
})();

cl.cnpj(cnpjNumber)

Brazilian CNPJ validation and branch type.

(async () => {
  const cnpj = await cl.cnpj("11222333000181");
  console.log(cnpj.valid);        // true
  console.log(cnpj.branch_type);  // "Matriz"
})();

cl.key()

Returns the status and quota usage for the current API key.   Requires a valid API key to be set.

(async () => {
  const key = await cl.key();
  console.log(key.suspended);     // false
  console.log(key.quota.ip);      // 100
  console.log(key.quota.cep);     // 1000
})();

Error Handling

All methods reject with an Error if the request fails or the response cannot be parsed.   The API itself returns { success: false, ... } for application-level errors.

(async () => {
  try {
    const ip = await cl.ip("8.8.8.8");
    if (!ip.success) {
      console.error("API error:", ip);
    }
  } catch (err) {
    console.error("Request failed:", err.message);
  }
})();

Links

• API Docs: lookup.cubie.com.br/docs
• Website: lookup.cubie.com.br