Skip to main content
The @neariq/sdk package is the official JavaScript and TypeScript client for the NearIQ API. It wraps every API endpoint in a typed, promise-based interface with zero runtime dependencies beyond the standard fetch API. TypeScript types are bundled with the package — no separate @types/ package is needed.

​
Installation

npm install @neariq/sdk
The SDK requires Node.js 18 or later (for native fetch support), or any modern browser runtime.

​
Initializing the client

Import the NearIQ class and pass your API key. Store the key in an environment variable — never hardcode it. 
import { NearIQ } from '@neariq/sdk'

const client = new NearIQ({ apiKey: process.env.NEARIQ_API_KEY! })

​
Constructor options

​
apiKey
string
required
Your NearIQ API key. Must start with niq_live_. Generate one in Settings → API Keys.
​
baseUrl
string
default:"https://neariq.io"
Override the base URL. Useful for testing against a local proxy or staging environment. Trailing slashes are stripped automatically.
// Custom base URL (e.g., for a local proxy)
const client = new NearIQ({
  apiKey: process.env.NEARIQ_API_KEY!,
  baseUrl: 'https://my-proxy.example.com',
})

​
Making your first request

import { NearIQ } from '@neariq/sdk'

const client = new NearIQ({ apiKey: process.env.NEARIQ_API_KEY! })

const biz = await client.me.get()
console.log(`${biz.name} — ${biz.rating} ★ (${biz.reviewCount} reviews)`)

​
Error handling

When the API returns a non-2xx status, the SDK throws an error that extends the built-in Error class with two additional properties:
  • status (number) — the HTTP status code
  • body (unknown) — the full parsed JSON response body
import { NearIQ } from '@neariq/sdk'

const client = new NearIQ({ apiKey: process.env.NEARIQ_API_KEY! })

try {
  const competitor = await client.competitors.get('does-not-exist')
} catch (err) {
  if (err instanceof Error && 'status' in err) {
    const e = err as import('@neariq/sdk').NearIQError
    console.error(`API error ${e.status}: ${e.message}`)
    // For a 404: "Competitor not found or does not belong to your account."
  }
}
NearIQError is an interface on Error, not a class, so use 'status' in err rather than instanceof NearIQError to detect it.

​
TypeScript

All request parameter types, response types, and error types are exported from the package. Import them directly for use in your own code: 
import type {
  Business,
  Competitor,
  CompetitorDetail,
  Alert,
  Snapshot,
  Review,
  ReviewsResponse,
  GBPHealthResponse,
  WebhookEndpoint,
  UsageResponse,
  ExportResponse,
  NearIQError,
} from '@neariq/sdk'
See the SDK reference for a complete list of all exported types and methods.

​
Next steps