#### `llmrefs` is maintained by [LLMrefs](https://llmrefs.com/) - AI SEO brand visibility & LLM rank tracker.
---
## **✅ Open source AI search analytics & LLM visibility Javascript SDK**
---
- Track your brand's visibility across AI search engines (LLMs)
- Monitor keyword rankings and share of voice
- Analyze AI-generated responses and brand mentions
- Get detailed analytics for AI SEO performance
- Full TypeScript support with detailed type definitions
## Installation
```bash
npm install llmrefs
```
## Quick Start
```typescript
import { LLMrefs } from 'llmrefs';
// Initialize the client
const llmrefs = new LLMrefs({
apiKey: 'your_api_key', // or set LLMREFS_API_KEY env variable
});
// List organizations
const organizations = await llmrefs.organizations.list();
// List projects for an organization
const projects = await llmrefs.projects.list({
organizationId: 'org-123',
});
// List keywords for a project
const keywords = await llmrefs.keywords.list({
projectId: 'proj-456',
organizationId: 'org-123',
});
// Get detailed keyword analytics
const keywordData = await llmrefs.keywords.get({
keywordId: 'kw-789',
projectId: 'proj-456',
organizationId: 'org-123',
});
```
## API Reference
### Authentication
Sign up for a free API key at 👉 [llmrefs.com/signup](https://llmrefs.com/signup).
You can provide your API key in two ways:
**1. Pass it when initializing the client:**
```typescript
const llmrefs = new LLMrefs({ apiKey: 'your_api_key' });
```
**2. Set it as an environment variable:**
```bash
export LLMREFS_API_KEY=your_api_key
const llmrefs = new LLMrefs(); // Will use LLMREFS_API_KEY env variable
```
### Listing Organizations
Get all organizations you have access to:
```typescript
const organizations = await llmrefs.organizations.list();
console.log(organizations);
// => [
// { id: 'org-1', name: 'My Organization' },
// { id: 'org-2', name: 'Another Organization' },
// ...
// ]
```
### Listing Projects
Get all projects for a specific organization:
```typescript
const projects = await llmrefs.projects.list({
organizationId: 'org-123',
});
console.log(projects);
// => [
// { id: 'proj-1', name: 'My Project', domain: 'example.com' },
// { id: 'proj-2', name: 'Another Project', domain: 'test.com' },
// ...
// ]
```
### Listing Keywords
Get all active keywords for a project:
```typescript
const keywords = await llmrefs.keywords.list({
organizationId: 'org-123',
projectId: 'proj-456',
});
console.log(keywords);
// => [
// {
// id: 'kw-1',
// value: 'artificial intelligence',
// location: 'US',
// searchVolume: 10000
// },
// ...
// ]
```
### Listing Search Engines
Get all available AI search engines (LLMs) tracked by LLMrefs:
```typescript
const searchEngines = await llmrefs.keywords.searchEngines();
console.log(searchEngines);
// => [
// { value: 'openai_chatgpt', name: 'OpenAI ChatGPT' },
// { value: 'google_ai_mode', name: 'Google AI Mode' },
// ...
// ]
```
### Listing Locations
Get all available locations tracked by LLMrefs:
```typescript
const locations = await llmrefs.keywords.locations();
console.log(locations);
// => [
// { value: 'united_states', name: 'United States' },
// { value: 'united_kingdom', name: 'United Kingdom' },
// ...
// ]
```
### Getting Keyword Analytics
Get detailed AI SEO analytics for a specific keyword:
```typescript
const keywordData = await llmrefs.keywords.get({
keywordId: 'kw-789',
organizationId: 'org-123',
projectId: 'proj-456',
filters: {
searchEngines: ['openai_chatgpt', 'google_ai_mode'], // Optional: filter by specific AI search engines
},
});
console.log(keywordData);
// => {
// id: 'kw-789',
// value: 'artificial intelligence',
// location: 'US',
// searchVolume: 10000,
// rankings: [
// {
// rank: 1,
// brandId: 'brand-1',
// shareOfVoice: '50%',
// averagePosition: '1.5',
// sources: ['source1', 'source2']
// },
// ...
// ],
// sources: [
// {
// source: 'source1',
// mentionRate: '30%',
// averagePosition: '2.0',
// brandIds: ['brand-1']
// },
// ...
// ],
// responses: [
// {
// prompt: 'What is artificial intelligence?',
// searchEngine: 'openai_chatgpt',
// text: 'AI response text...',
// brandsIds: ['brand-1'],
// sources: ['source1']
// },
// ...
// ],
// brands: [
// { id: 'brand-1', name: 'My Brand', domain: 'mybrand.com' },
// ...
// ]
// }
```
## Features in Detail
### AI Search Analytics
- Track your brand's visibility across multiple AI search engines (LLMs)
- Monitor keyword rankings and share of voice metrics
- Analyze how AI models respond to prompts surrounding your keywords topics
- View search volume for keywords across AI search engines
- Get insights into brand mentions and positioning
### Keyword Tracking
- Monitor keyword performance across different AI platforms
- Track rankings, average positions, and share of voice
- Filter results by specific AI search engines
- Access historical and real-time analytics data
## Error Handling
The SDK throws descriptive errors for invalid API keys, failed requests, and API errors:
```typescript
try {
const organizations = await llmrefs.organizations.list({});
} catch (error) {
console.error('Error listing organizations:', error.message);
}
```
## TypeScript Support
The SDK is written in TypeScript and provides comprehensive type definitions:
```typescript
import {
LLMrefs,
LLMrefsOptions,
ListOrganizationsOptions,
ListProjectsOptions,
ListKeywordsOptions,
GetKeywordOptions,
} from 'llmrefs';
// All options are fully typed
const options: GetKeywordOptions = {
keywordId: 'kw-789',
projectId: 'proj-456',
organizationId: 'org-123',
};
```
## Types
### LLMrefsOptions
| Property | Type | Description | Required |
| -------- | -------- | -------------------- | ---------------------------- |
| `apiKey` | `string` | Your LLMrefs API key | `false` (if set via env var) |
### ListOrganizationsOptions
No properties required. Pass an empty object `{}`.
### ListProjectsOptions
| Property | Type | Description | Required |
| ---------------- | -------- | --------------- | -------- |
| `organizationId` | `string` | Organization ID | `true` |
### ListKeywordsOptions
| Property | Type | Description | Required |
| ---------------- | -------- | --------------- | -------- |
| `organizationId` | `string` | Organization ID | `true` |
| `projectId` | `string` | Project ID | `true` |
### GetKeywordOptions
| Property | Type | Description | Required |
| ----------------------- | ---------- | --------------------------------- | -------- |
| `keywordId` | `string` | Keyword ID | `true` |
| `organizationId` | `string` | Organization ID | `true` |
| `projectId` | `string` | Project ID | `true` |
| `filters` | `object` | Optional filters | `false` |
| `filters.searchEngines` | `string[]` | Filter by AI search engine values | `false` |
## License
Distributed under the MIT License. See LICENSE for more information.
## Links
If you need support please contact us at 👉 [hello@llmrefs.com](mailto:hello@llmrefs.com)
- [LLMrefs Website](https://llmrefs.com/)
- [API Documentation](https://llmrefs.com/ai-seo-api)
- [OpenAPI Schema](https://llmrefs.com/api/openapi.json)
---
Built by [LLMrefs](https://llmrefs.com/) with ❤️, AI search analytics.
