Transfermarkt API Client

A lightweight and efficient Node.js client designed to interact with the Transfermarkt API.
This project enables fetching detailed data on players, clubs, competitions, matches, referees, coaches, and stadiums, incorporating an integrated caching system to optimize performance and reduce redundant requests.

⚠️ Note: While this API is officially used by Transfermarkt on their website, it is not publicly documented or intended for external use. Because of this, endpoints and responses may change at any time without prior notice.

---

⭐ If you find this project useful, consider giving it a star!

---

📚 Table of Contents

• 📝 Project Overview
• 🌟 Features
• 🚀 Installation
• 💡 Usage
  • Basic Example: Fetching Player Profile
  • Available Services
  • Caching Mechanism
  • Error Handling
• 🌐 API Endpoints
• 🤝 Contribution
• 📄 License
• 👨 Author
• 🔗 References

---

📝 Project Overview

This project serves as a robust client for accessing comprehensive football data from Transfermarkt.
It leverages modern JavaScript features and popular libraries like axios for HTTP requests and node-cache for efficient data caching.

The modular design ensures easy integration and scalability, making it suitable for applications requiring football statistics and information.

---

🌟 Features

• Player Profile Search: Retrieve extensive information about any football player, including biographical data, market value, and club history.
• Club Data: Access detailed information about football clubs, such as squad lists, historical data, and current standings.
• Competition Information: Query data for various leagues and tournaments worldwide.
• Match Details: Obtain information about specific matches, including scores, lineups, and events.
• Referee and Coach Profiles: Get data on professional referees and coaches.
• Stadium Data: Information about football stadiums, including capacity and location.
• Integrated Caching: Utilizes node-cache to store API responses, significantly improving response times and reducing the load on the Transfermarkt servers. Configurable TTL (Time To Live) for cached data.
• Optimized Requests: Built with axios for efficient HTTP requests, including request timeouts and robust error handling.
• Modular Design: Services are organized into separate modules (club.js, player.js, etc.) for better maintainability and ease of use.

---

🚀 Installation

To integrate this API client into your project, follow these steps:

1. Clone the repository (or download the ZIP file and extract it):

   git clone https://github.com/wcarmesini/transfermarkt_api_client.git
   cd transfermarkt_api_client

2. Install dependencies:

   npm install

---

💡 Usage

The API client is modular and straightforward to use.
You can import specific service functions or the tmapi module directly.

Basic Example: Fetching Player Profile

Create a file named example.js (or similar) and add the following code:

import { playerProfile } from './src/services/index.js';
import util from 'node:util';

async function run() {
  // Fetch the profile of the player with ID 28003 (Lionel Messi, example only)
  const result = await playerProfile(28003);

  // Print the result to the console in a readable format
  console.log(util.inspect(result, { showHidden: false, depth: null, colors: true }));
}

run();

To run the example:

node example.js

---

Available Services

All services are centrally exported via src/services/index.js.
You can import them as needed:

import { 
  playerProfile, 
  clubInfo, 
  competitionTable, 
  gameDetails, 
  refereeProfile, 
  coachProfile, 
  stadiumInfo 
} from './src/services/index.js';

// Example of using other services
const club = await clubInfo(4); // FC Barcelona (ID 4)
const competition = await competitionTable(null, 'GB1'); // Premier League

Service Structure

• src/services/club.js: Club-related functions (e.g., clubInfo).
• src/services/coach.js: Coach-related functions (e.g., coachProfile).
• src/services/competition.js: Competition-related functions (e.g., competitionTable).
• src/services/game.js: Match-related functions (e.g., gameDetails).
• src/services/general.js: General utility functions (if any).
• src/services/player.js: Player-related functions (e.g., playerProfile).
• src/services/referee.js: Referee-related functions (e.g., refereeProfile).
• src/services/stadium.js: Stadium-related functions (e.g., stadiumInfo).

---

Caching Mechanism

The client uses node-cache to cache API responses for a default period of 5 minutes (300 seconds).
This means that repeated requests to the same endpoint within this period will return cached data, significantly improving response times and reducing external calls.

You can adjust the TTL (Time To Live) in src/tmapi.js:

// Simple cache (default TTL: 5 minutes)
const cache = new NodeCache({ stdTTL: 300 }); // Change 300 to desired seconds

---

Error Handling

The fetchTm function in src/tmapi.js includes basic error handling.
If an API request fails, it logs the error to the console and returns null.

Example:

try {
  const result = await playerProfile(99999999); // Non-existent player ID
  if (result) {
    console.log(result);
  } else {
    console.log('Player not found or API error occurred.');
  }
} catch (error) {
  console.error('An unexpected error occurred:', error);
}

---

🌐 API Endpoints

The client interacts with the base URL:

https://tmapi-alpha.transfermarkt.technology/

Examples of endpoints:

• player/28003 → Player profile (Lionel Messi)
• club/131 → Club information (FC Barcelona)
• competition/GB1 → Competition details (Premier League)

---

🤝 Contribution

Contributions are welcome!
Feel free to open issues to report bugs, suggest new features, or submit pull requests.

How to Contribute

1. Fork the repository.
2. Create a new branch (git checkout -b feature/your-feature-name).
3. Make your changes and ensure the code runs without errors:

   npm install && node example.js

4. Commit your changes (git commit -m 'Add new feature').
5. Push to the branch (git push origin feature/your-feature-name).
6. Open a Pull Request.

---

📄 License

This project is licensed under the MIT License.
See the LICENSE file for details.

---

👨 Author

Wilson Valentim Carmesini

• GitHub: @wcarmesini

---

🔗 References

• Transfermarkt Official Website
• Axios GitHub Repository
• Node-Cache npm Package