@lineai/linkedin-api

Professional LinkedIn API client with TypeScript support, entity classes, and developer-friendly features. Implements the LinkedIn Data API from RapidAPI.

Quick Reference

| Operation | Method | Purpose | Key Parameters | Returns | |-----------|--------|---------|----------------|---------| | Profile Search | searchProfiles(params) | Find profiles by criteria | keywords, geo, company, minItems | ProfileSearchResult | | Profile Get | getProfile(username) | Full profile data | username | LinkedInProfile | | Company Search | searchCompanies(params) | Find companies by criteria | keywords, industries, companySizes, minItems | CompanySearchResult | | Company Get | getCompany(username) | Full company data | username | LinkedInCompany | | Post Search | searchPosts(params) | Find posts by criteria | keywords, author, datePosted, minItems | PostSearchResult | | Post Get | getPost(postId) | Full post data | postId | LinkedInPost |

Essential Imports

import LinkedInAPI, { 
  LOCATIONS, 
  INDUSTRIES, 
  COMPANY_SIZES,
  LinkedInError,
  RateLimitError,
  NotFoundError 
} from '@lineai/linkedin-api';

Core Entity Methods

| Entity | Key Methods | Returns | |--------|-------------|---------| | LinkedInProfile | getFullName(), getHeadline(), getCurrentPosition(), getLinkedInUrl() | Formatted strings/objects | | LinkedInCompany | getName(), getFollowerCount(), getEmployeeCount(), getLinkedInUrl() | Company data | | LinkedInPost | getText(), getLikeCount(), getCommentCount(), getAuthor() | Post metrics |

🆕 What's New in v1.3.8

• 🔍 Improved TypeScript Types - Added PostSearchItemAuthorData interface for better type safety when working with post search results
• 🎯 Enhanced IntelliSense - Post search author data now has proper autocompletion and type checking
• 🛠️ Type Safety Fix - Eliminates type mismatches between post search results and full post data author schemas

v1.3.7 Features

• 🔧 Next.js Build Fix - Fixed webpack compilation error by replacing process.env.NODE_ENV manipulation with instance-based debug mode
• ⚡ Better Debug Mode - Debug logging now uses instance property instead of environment variable modification

v1.3.6 Features

• 📦 Package Optimization - Removed examples directory to reduce package size and improve build compatibility
• 🛠️ Build Fixes - Resolved Next.js build issues by streamlining package structure

v1.3.5 Features

• 🧹 Dependency Cleanup - Removed Prettier and related ESLint configurations to reduce package size and simplify development
• ⚡ Streamlined Build - Cleaner development environment with fewer dependencies

v1.3.4 Features

• 🛠️ Data Transformation Fix - Fixed company search universalName → username transformation to occur in CompanySearchResult.items getter for better data consistency
• 🎯 Unified API Experience - Both api.getProfile(item.username) and api.getCompany(item.username) now use the same field name

v1.3.3 Features

• 🔄 Consistent Username Field - Company search results now use username instead of universalName for consistency with profile search

v1.3.2 Features

• 🗑️ Simplified Search Results - Removed ProfileSearchItem, CompanySearchItem, and PostSearchItem wrapper classes for direct data access
• 🎯 Direct Data Access - Search results now return raw data objects with helper methods for cleaner, simpler usage

v1.3.1 Features

• 🔧 Fixed Location Parameter Types - LocationId is now correctly typed as number instead of string
• ✅ API Compatibility - Location constants (LOCATIONS) now properly work with LinkedIn API requirements
• 🎯 Cross-Method Consistency - Both profile search (GET) and company search (POST) handle location arrays correctly

v1.3.0 Features

• ✨ Enhanced Type Safety - Complete TypeScript response type definitions prevent runtime errors
• 🔒 Immutable Parameters - Search parameters are never mutated, ensuring predictable behavior
• 🏎️ Improved Caching - Now works for all get methods with 100% cache hit performance
• 🛠️ Better Error Handling - More specific error types with better debugging information
• 🎯 Unified API - Consistent pagination and parameter handling across all search methods
• 🔍 Enhanced Debugging - Improved debug logs with accurate response structure information

Features

• 🚀 Easy to use - Simple, intuitive API with high-level methods
• 📘 TypeScript ready - Full type definitions included
• 🎯 Entity classes - Clean data access without dealing with raw JSON
• 🔄 Seamless data loading - Load full profiles/companies/posts from search results
• 🛡️ Safe defaults - Never worry about null/undefined values
• ⚡ Built-in caching - Reduce API calls automatically (v1.3.0+)
• 🎛️ Pagination helpers - Easy navigation through search results
• 🏷️ Helper constants - No more magic strings for locations, industries, etc.
• 🔒 Parameter immutability - Original search params never modified (v1.3.0+)

Installation

npm install @lineai/linkedin-api
# or
yarn add @lineai/linkedin-api

Quick Start

import { LinkedInAPI } from '@lineai/linkedin-api';

const api = new LinkedInAPI('your-rapidapi-key');

// Get a profile
const profile = await api.getProfile('satyanadella');
console.log(profile.getFullName()); // "Satya Nadella"
console.log(profile.getCurrentPosition()?.title); // "CEO"

Usage Examples

Profile Operations

import { LinkedInAPI, LOCATIONS } from '@lineai/linkedin-api';

const api = new LinkedInAPI('your-rapidapi-key');

// Search for profiles
const searchResults = await api.searchProfiles({
  keywords: 'software engineer',
  geo: [LOCATIONS.US.SAN_FRANCISCO, LOCATIONS.US.NEW_YORK], // Auto-joined
  company: 'Google'
});

console.log(`Found ${searchResults.total} profiles`);

// Access search results
searchResults.items.forEach(item => {
  console.log(item.getFullName());
  console.log(item.getHeadline());
  console.log(item.getLinkedInUrl());
});

// Get full profile using username from search result
const firstResult = searchResults.items[0];
const fullProfile = await api.getProfile(firstResult.username);

// Access full profile data
console.log(fullProfile.getFullName());
console.log(fullProfile.getCurrentPosition()?.companyName);
console.log(fullProfile.getEducation()[0]?.schoolName);
console.log(fullProfile.getSkills().length);
console.log(fullProfile.getProfilePictureUrl('large'));

// Direct profile access
const profile = await api.getProfile('billgates');
console.log(profile.getLinkedInUrl()); // https://linkedin.com/in/billgates

Company Operations

import { LinkedInAPI, COMPANY_SIZES, INDUSTRIES, LOCATIONS } from '@lineai/linkedin-api';

const api = new LinkedInAPI('your-rapidapi-key');

// Search companies
const companies = await api.searchCompanies({
  keyword: 'artificial intelligence',
  locations: [LOCATIONS.US.ALL],
  industries: [INDUSTRIES.TECHNOLOGY],
  companySizes: [COMPANY_SIZES.LARGE, COMPANY_SIZES.XLARGE], // 201-1000 employees
  hasJobs: true
});

// Access company data
const company = companies.items[0];
console.log(company.getName());
console.log(company.getTagline());

// Get full company details using username from search result
const fullCompany = await api.getCompany(company.username);
console.log(fullCompany.getEmployeeCount());
console.log(fullCompany.getHeadquarters()?.city);
console.log(fullCompany.getSpecialties());
console.log(fullCompany.getFollowerCount());
console.log(fullCompany.getWebsite());

// Direct company access
const microsoft = await api.getCompany('microsoft');
console.log(microsoft.getName()); // "Microsoft"
console.log(microsoft.getEmployeeCount());
console.log(microsoft.getAllLocations().length);

Post Operations

const api = new LinkedInAPI('your-rapidapi-key');

// Search posts
const posts = await api.searchPosts({
  keyword: 'machine learning',
  sortBy: 'date_posted',
  fromCompany: [1441] // Google's company ID
});

console.log(`Found ${posts.total} posts`);

// Access post data
const post = posts.items[0];
console.log(post.getText());
console.log(post.getAuthorName());
console.log(post.getPostedAt());

// Get full post details using URN from search result
const fullPost = await api.getPost(post.urn);
console.log(fullPost.getTotalEngagement());
console.log(fullPost.getLikeCount());
console.log(fullPost.getCommentsCount());
console.log(fullPost.hasVideo());
console.log(fullPost.getArticle()?.title);

// Direct post access
const specificPost = await api.getPost('7219434359085252608');
console.log(specificPost.getAuthor().firstName);
console.log(specificPost.getTotalEngagement());

Pagination

// Handle pagination easily
const results = await api.searchProfiles({ keywords: 'CEO' });

console.log(`Page 1: ${results.items.length} items`);

if (results.hasNextPage()) {
  const page2 = await results.getNextPage();
  console.log(`Page 2: ${page2.items.length} items`);
}

// Process all pages
let currentPage = results;
let pageNum = 1;

while (currentPage.items.length > 0) {
  console.log(`Processing page ${pageNum}: ${currentPage.items.length} items`);
  
  // Process items
  for (const item of currentPage.items) {
    console.log(item.getFullName());
  }
  
  if (currentPage.hasNextPage()) {
    currentPage = await currentPage.getNextPage();
    pageNum++;
  } else {
    break;
  }
}

Error Handling

import { LinkedInAPI, NotFoundError, RateLimitError } from '@lineai/linkedin-api';

const api = new LinkedInAPI('your-rapidapi-key');

try {
  const profile = await api.getProfile('invalid-username-xyz');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error('Profile not found');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after: ${error.retryAfter}`);
  } else {
    console.error('Unexpected error:', error.message);
  }
}

TypeScript Support

import { 
  LinkedInAPI, 
  LinkedInProfile, 
  LinkedInCompany,
  ProfileSearchParams,
  LOCATIONS,
  LocationId 
} from '@lineai/linkedin-api';

const api = new LinkedInAPI('your-key');

// Full type safety
const searchParams: ProfileSearchParams = {
  keywords: 'engineer',
  geo: [LOCATIONS.US.SEATTLE] as LocationId[]
};

const results = await api.searchProfiles(searchParams);

// TypeScript knows all available methods
const profile: LinkedInProfile = await api.getProfile('username');
const position = profile.getCurrentPosition(); // Type: Position | null

if (position) {
  console.log(position.title); // TypeScript knows all Position properties
  console.log(position.companyName);
}

Helper Constants

import { LOCATIONS, COMPANY_SIZES, INDUSTRIES } from '@lineai/linkedin-api';

// Use location constants instead of numeric IDs
const usProfiles = await api.searchProfiles({
  geo: [LOCATIONS.US.ALL]
});

const techCompanies = await api.searchCompanies({
  locations: [
    LOCATIONS.US.SAN_FRANCISCO,
    LOCATIONS.US.SEATTLE,
    LOCATIONS.US.AUSTIN
  ],
  industries: [INDUSTRIES.TECHNOLOGY],
  companySizes: COMPANY_SIZES.ALL // All company sizes
});

🆕 Smart Retry with minItems (v1.2.2)

All search methods now support intelligent retry logic to ensure you get the results you need:

Profile Search with minItems

// Get at least 15 profiles - will retry across different pages until found
const profiles = await api.searchProfiles({
  keywords: 'software engineer',
  geo: [LOCATIONS.US.SAN_FRANCISCO],
  minItems: 15,     // Minimum results required
  maxRetries: 5     // Maximum retry attempts
});

console.log(`Found ${profiles.items.length} profiles`); // At least 15

Company Search with minItems

// Get substantial company dataset
const companies = await api.searchCompanies({
  keywords: 'fintech startup',
  industries: [INDUSTRIES.FINANCIAL_SERVICES],
  minItems: 20,     // Keep retrying until 20+ companies found
  maxRetries: 6
});

Post Search with minItems

// Collect many posts for content analysis
const posts = await api.searchPosts({
  keywords: 'artificial intelligence',
  datePosted: 'past-week',
  minItems: 25,     // Need at least 25 posts
  maxRetries: 8
});

Disable Retry Logic

// For exact pagination control, disable retries
const exactPage = await api.searchProfiles({
  keywords: 'manager',
  start: '20',
  minItems: 0       // Disable retries - return exact page results
});

Why use minItems?

• LinkedIn has many private profiles/companies that appear in counts but don't return data
• Results can be sparse across different pages
• Perfect for data collection, analysis, or when you need substantial sample sizes
• Automatically handles pagination gaps and empty result pages

Advanced Usage

// Access raw data when needed
const profile = await api.getProfile('username');
console.log(profile.raw); // Original API response

// Use the low-level endpoint method
const response = await api.callEndpoint('get_profile_posts', {
  username: 'satyanadella',
  start: '0'
});

// Cache management
api.clearCache(); // Clear all cached data
api.enableCache = false; // Disable caching

// Batch operations
const usernames = ['billgates', 'satyanadella', 'sundarpichai'];
const profiles = await Promise.all(
  usernames.map(username => api.getProfile(username))
);

profiles.forEach(profile => {
  console.log(`${profile.getFullName()} - ${profile.getHeadline()}`);
});

API Reference

Main Class: LinkedInAPI

const api = new LinkedInAPI(rapidApiKey, rapidApiHost?)

| Method | Parameters | Returns | Description | |--------|------------|---------|-------------| | searchProfiles(params) | {keywords?, geo?, company?, start?, minItems?, maxRetries?} | ProfileSearchResult | Search LinkedIn profiles with smart retry | | getProfile(username) | string | LinkedInProfile | Get full profile data | | searchCompanies(params) | {keywords?, industries?, companySizes?, minItems?, maxRetries?} | CompanySearchResult | Search LinkedIn companies with smart retry | | getCompany(username) | string | LinkedInCompany | Get full company data | | searchPosts(params) | {keywords?, author?, datePosted?, minItems?, maxRetries?} | PostSearchResult | Search LinkedIn posts with smart retry | | getPost(postId) | string | LinkedInPost | Get full post data | | clearCache() | - | void | Clear all cached data | | validateParameters(endpoint, params) | string, object | ValidationResult | Validate parameters |

Entity Classes

LinkedInProfile

| Method | Returns | Description | |--------|---------|-------------| | getFullName() | string | Combined first + last name | | getHeadline() | string | Professional headline | | getCurrentPosition() | Position \| null | Current job position |
| getAllPositions() | Position[] | All work experience | | getEducation() | Education[] | Education history | | getSkills() | Skill[] | Skills list | | getLinkedInUrl() | string | Full LinkedIn profile URL | | getLocation() | Location | Geographic location | | getProfilePictureUrl(size?) | string | Profile picture URL |

LinkedInCompany

| Method | Returns | Description | |--------|---------|-------------| | getName() | string | Company name | | getFollowerCount() | number | LinkedIn followers | | getEmployeeCount() | number | Employee count | | getLinkedInUrl() | string | Full LinkedIn company URL | | getDescription() | string | Company description | | getSpecialties() | string[] | Company specialties | | getIndustries() | string[] | Industry categories | | getWebsite() | string | Company website |

LinkedInPost

| Method | Returns | Description | |--------|---------|-------------| | getText() | string | Post content text | | getLikeCount() | number | Number of likes |
| getCommentCount() | number | Number of comments | | getShareCount() | number | Number of shares | | getAuthor() | Author | Post author info | | getPostedAt() | Date | Post publication date | | getTotalEngagement() | number | Total engagement count | | hasMedia() | boolean | Contains images/videos |

Search Results Classes

All search result classes support pagination:

| Method | Returns | Description | |--------|---------|-------------| | hasNextPage() | boolean | More results available | | getNextPage() | Promise<SearchResult> | Fetch next page | | items | SearchItem[] | Current page items | | total | number | Total result count |

Search Item Data

Search results return raw data objects. Use the API methods to get full details:

// Get full data from search results
const profiles = await api.searchProfiles({ keywords: 'engineer' });
const fullProfile = await api.getProfile(profiles.items[0].username);

const companies = await api.searchCompanies({ keyword: 'tech' });
const fullCompany = await api.getCompany(companies.items[0].username);

const posts = await api.searchPosts({ keyword: 'AI' });
const fullPost = await api.getPost(posts.items[0].urn);

Error Types

| Error | When Thrown | Properties | Example Handling | |-------|-------------|------------|------------------| | LinkedInError | Base error class | message, code | Generic error handling | | RateLimitError | Rate limit exceeded | retryAfter (Date) | Wait until retry time | | NotFoundError | Resource not found/private | message | Handle missing data | | NetworkError | Connection issues | originalError | Retry logic |

try {
  const profile = await api.getProfile('username');
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Retry after: ${error.retryAfter}`);
  } else if (error instanceof NotFoundError) {
    console.log('Profile not found or private');
  }
}

Helper Constants

LOCATIONS

LOCATIONS.US.NEW_YORK        // 105080838 (number)
LOCATIONS.US.SAN_FRANCISCO   // 102277331 (number)
LOCATIONS.US.LOS_ANGELES     // 102448103 (number)
// ... more cities available

COMPANY_SIZES

COMPANY_SIZES.SELF_EMPLOYED  // 'A' (Self-employed)
COMPANY_SIZES.TINY          // 'B' (1-10 employees)
COMPANY_SIZES.SMALL         // 'C' (11-50 employees)
COMPANY_SIZES.MEDIUM        // 'D' (51-200 employees)
COMPANY_SIZES.LARGE         // 'E' (201-500 employees)
COMPANY_SIZES.XLARGE        // 'F' (501-1000 employees)
COMPANY_SIZES.ENTERPRISE    // 'G' (1001-5000 employees)
COMPANY_SIZES.MASSIVE       // 'H' (5001-10000 employees)
COMPANY_SIZES.MEGA          // 'I' (10000+ employees)

INDUSTRIES

INDUSTRIES.TECHNOLOGY         // 96
INDUSTRIES.FINANCIAL_SERVICES // 43
INDUSTRIES.HEALTHCARE         // 14
INDUSTRIES.RETAIL             // 27
// ... more industries available

Troubleshooting

Common Issues & Solutions

| Problem | Cause | Solution | |---------|-------|----------| | "Invalid username" | Username format incorrect | Use LinkedIn username (from URL) not display name | | "Rate limit exceeded" | Too many requests | Implement delays, use caching, handle RateLimitError | | "Profile not found" | Private profile or invalid username | Handle NotFoundError gracefully | | Empty search results | Overly specific criteria | Broaden search parameters | | Profile search returns 0 items | Private profiles in result set | Enable auto-retry (default) or use debug mode | | Slow performance | Not using caching | Enable caching (default) or clear periodically | | Memory issues | Large dataset processing | Process in batches, clear cache regularly |

Best Practices

| Practice | Why | Example | |----------|-----|---------| | Use helper constants | Avoid magic strings | geo: [LOCATIONS.US.NYC] not geo: ['105080838'] | | Handle errors specifically | Better error recovery | Check for RateLimitError, NotFoundError | | Use entity methods | Safe data access | profile.getFullName() not profile.data.firstName | | Implement delays | Avoid rate limits | await new Promise(r => setTimeout(r, 1000)) | | Load full data smartly | Performance optimization | Search first, then load full data only when needed |

Parameter Validation

// Validate before making requests
const validation = api.validateParameters('search_people', {
  keywords: 'engineer'
});

if (!validation.valid) {
  console.log('Missing:', validation.missingRequired);
  console.log('Extra:', validation.extraParams);
}

Profile Search & Private Profiles

LinkedIn profile searches may show high total counts but return 0 items due to private profiles. The package automatically handles this:

// Automatic retry (default behavior)
const results = await api.searchProfiles({ keywords: 'engineer' });
// Will try different start positions automatically

// Debug what's happening
api.setDebugMode(true);
const debugResults = await api.searchProfiles({ keywords: 'ceo' });
// Logs: "Profile search attempt 1, start=0: itemsCount=0"
//       "Profile search attempt 2, start=10: itemsCount=2" ✅

// Manual control
const exactResults = await api.searchProfiles({
  keywords: 'manager',
  autoRetryForPrivateProfiles: false,  // Get exact page
  start: '20'
});

Configuration

The API client supports several configuration options:

const api = new LinkedInAPI('your-key');

// Disable caching
api.enableCache = false;

// Adjust cache timeout (default: 5 minutes)
api.cacheTimeout = 10 * 60 * 1000; // 10 minutes

// Clear cache
api.clearCache();

// Enable debug mode (helpful for troubleshooting)
api.setDebugMode(true);

Rate Limiting

The API includes rate limit information in responses. Handle rate limits gracefully:

try {
  const profile = await api.getProfile('username');
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited until: ${error.retryAfter}`);
    // Implement retry logic
  }
}

Additional Resources

• AI_USAGE_GUIDE.md - Comprehensive guide optimized for AI coders with advanced patterns
• API_IMPLEMENTATION_GUIDE.md - Implementation details and development patterns
• LinkedIn Data API Documentation - Original RapidAPI documentation

Use Cases

| Scenario | Methods Needed | Pattern | |----------|----------------|---------| | Recruiting | searchProfiles(), getProfile() | Search → Filter → Load Full Data | | Lead Generation | searchCompanies(), getCompany() | Search by Industry → Get Details | | Market Research | searchCompanies(), searchProfiles() | Industry Analysis + Employee Insights | | Content Analysis | searchPosts(), getPost() | Keyword Search → Engagement Analysis | | Competitive Intelligence | getCompany(), searchProfiles() | Company Data + Employee Profiles |

Contributing

See API_IMPLEMENTATION_GUIDE.md for implementation details and patterns.

License

MIT