Skip to content
BranchesTags

Repository files navigation

Entity Enrichment API

A FastAPI service that enriches entity data (people, companies, topics) using multiple external APIs.

Features

  • Company Enrichment - Get company data from Clearbit (logo, domain, metrics)
  • Email Finding - Find email addresses using Hunter.io
  • Topic Context - Retrieve Wikipedia summaries for any topic
  • Batch Processing - Enrich multiple entities in a single request
  • CORS Enabled - Ready for web frontends

Quick Start

1. Clone the Repository

git clone https://github.com/s97472091-pixel/entity-enrichment-api.git
cd entity-enrichment-api

2. Install Dependencies

pip install -r requirements.txt

Or with uv (recommended):

uv sync

3. Configure API Keys

Create a .env file in the project root:

# Clearbit (for company enrichment)
CLEARBIT_API_KEY=your_clearbit_api_key_here

# Hunter.io (for email finding)
HUNTER_API_KEY=your_hunter_api_key_here

# Optional: Wikipedia doesn't require an API key

Where to get API keys:

4. Run the Server

uvicorn main:app --reload

Or with uvicorn directly:

python -m uvicorn main:app --reload

The API will be available at: http://localhost:8000

5. Interactive Documentation

Visit http://localhost:8000/docs to explore the API interactively (Swagger UI).

API Endpoints

GET /api/health

Health check endpoint.

Response:

{
  "status": "healthy",
  "timestamp": "2025-11-28T12:00:00Z"
}

GET /api/enrich/company?domain={domain}

Enrich company information using Clearbit.

Parameters:

  • domain (query, required): Company domain (e.g., "apple.com")

Example Request:

curl "http://localhost:8000/api/enrich/company?domain=apple.com"

Example Response:

{
  "domain": "apple.com",
  "name": "Apple Inc.",
  "logo": "https://logo.clearbit.com/apple.com",
  "category": "Computer Hardware",
  "metrics": {
    "employees": 164000,
    "market_cap": 2800000000000,
    "annual_revenue": 394300000000
  },
  "social": {
    "twitter": "@Apple",
    "linkedin": "apple"
  }
}

GET /api/enrich/email-finder?domain={domain}&full_name={name}

Find email addresses for a person at a company using Hunter.io.

Parameters:

  • domain (query, required): Company domain
  • full_name (query, required): Person's full name (e.g., "Tim Cook")

Example Request:

curl "http://localhost:8000/api/enrich/email-finder?domain=apple.com&full_name=Tim%20Cook"

Example Response:

{
  "domain": "apple.com",
  "full_name": "Tim Cook",
  "emails": [
    {
      "email": "tim.cook@apple.com",
      "confidence": 96,
      "type": "personal",
      "source": "Hunter.io"
    },
    {
      "email": "tcook@apple.com",
      "confidence": 89,
      "type": "work",
      "source": "Hunter.io"
    }
  ],
  "meta": {
    "total_found": 2,
    "disposable_domain": false,
    "webhook": "https://hunter.io/api/v2/..."
  }
}

GET /api/enrich/topic/{topic}

Get Wikipedia summary for any topic.

Path Parameters:

  • topic (path, required): Topic to search for (spaces replaced with underscores)

Example Request:

curl "http://localhost:8000/api/enrich/topic/Artificial%20Intelligence"

Example Response:

{
  "topic": "Artificial Intelligence",
  "extract": "Artificial intelligence (AI) is intelligence demonstrated by machines, as opposed to the natural intelligence displayed by humans...",
  "url": "https://en.wikipedia.org/wiki/Artificial_intelligence"
}

POST /api/enrich/batch

Enrich multiple entities in a single request.

Request Body:

{
  "entities": [
    {
      "type": "company",
      "domain": "apple.com"
    },
    {
      "type": "email_finder",
      "domain": "microsoft.com",
      "full_name": "Satya Nadella"
    },
    {
      "type": "topic",
      "topic": "Machine Learning"
    }
  ]
}

Example Request:

curl -X POST "http://localhost:8000/api/enrich/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "entities": [
      {"type": "company", "domain": "google.com"},
      {"type": "topic", "topic": "Blockchain"}
    ]
  }'

Response:

{
  "results": [
    {
      "type": "company",
      "status": "success",
      "data": {
        "domain": "google.com",
        "name": "Google LLC",
        "logo": "https://logo.clearbit.com/google.com"
      }
    },
    {
      "type": "topic",
      "status": "success",
      "data": {
        "topic": "Blockchain",
        "extract": "A blockchain is a distributed ledger with growing lists of records (blocks) that are securely linked together via cryptography..."
      }
    }
  ],
  "processed": 2,
  "successful": 2
}

Project Structure

ENTITY_ENRICHMENT_API/
├── main.py              # FastAPI application
├── requirements.txt     # Python dependencies
├── .env                # Environment variables (create this)
├── .gitignore          # Git ignore rules
└── README.md           # This file

Development

Install in editable mode

pip install -e .

Run with auto-reload

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Environment Variables

Variable Required Description
CLEARBIT_API_KEY Yes (for company enrichment) Your Clearbit API key
HUNTER_API_KEY Yes (for email finding) Your Hunter.io API key
LOG_LEVEL No Logging level (default: INFO)

Error Handling

The API returns appropriate HTTP status codes:

  • 200 - Success
  • 400 - Bad request (missing parameters)
  • 401 - Missing or invalid API key
  • 429 - Rate limit exceeded
  • 500 - Internal server error

Example error response:

{
  "status_code": 401,
  "error": "Missing Clearbit API key. Set CLEARBIT_API_KEY in .env"
}

Rate Limits

External API rate limits apply based on your subscription:

  • Clearbit: 100 requests/month (free tier)
  • Hunter.io: 50 searches/month (free tier)

The API does not implement internal rate limiting by default. You may want to add:

  • SlowAPI for rate limiting
  • Redis caching for frequent queries
  • Request batching with async processing

Deploying to Production

Render (easy, free tier)

  1. Push your code to GitHub
  2. Go to https://render.com
  3. Create a Web Service
  4. Connect your repository
  5. Set environment variables in Render dashboard
  6. Deploy!

Docker

Create a Dockerfile:

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Build and run:

docker build -t entity-enrichment-api .
docker run -p 8000:8000 entity-enrichment-api

Testing

Manual testing with cURL

# Company enrichment
curl "http://localhost:8000/api/enrich/company?domain=apple.com"

# Email finder
curl "http://localhost:8000/api/enrich/email-finder?domain=apple.com&full_name=Tim%20Cook"

# Topic search
curl "http://localhost:8000/api/enrich/topic/Python%20programming"

# Batch request
curl -X POST "http://localhost:8000/api/enrich/batch" \
  -H "Content-Type: application/json" \
  -d '{"entities": [{"type": "company", "domain": "google.com"}]}'

Automated tests (future)

pytest tests/ -v

Security Notes

  • API keys are stored in .env (never commit this file!)
  • Use environment variables in production (Render, AWS, etc.)
  • Consider adding:
    • API key authentication for your API
    • Request logging and monitoring
    • HTTPS enforcement
  • The current version exposes no user data, but API keys can incur costs if leaked

License

MIT License - see LICENSE file for details.

Contributing

Want to add more enrichments? Here's how:

  1. Fork the repository
  2. Create a feature branch
  3. Add your enrichment function in main.py
  4. Add a corresponding endpoint
  5. Test it locally
  6. Submit a Pull Request

Example enrichment to add:

  • LinkedIn profile lookup
  • Twitter/X user data
  • Crunchbase company data
  • GitHub repository stats
  • News mentions (GDELT, NewsAPI)

Support

Built with ❤️ using FastAPI

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages