Metadata-Version: 2.4
Name: salaryfyi
Version: 0.1.1
Summary: Salary comparison and tax calculator API client — salaryfyi.com
Project-URL: Homepage, https://salaryfyi.com
Project-URL: Documentation, https://salaryfyi.com/developers/
Project-URL: Repository, https://github.com/fyipedia/salaryfyi
Project-URL: Issues, https://github.com/fyipedia/salaryfyi/issues
Project-URL: Changelog, https://github.com/fyipedia/salaryfyi/releases
Author: FYIPedia
License-Expression: MIT
License-File: LICENSE
Keywords: compensation,employment,finance,income,payroll,salary,tax,wage
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: typer>=0.15; extra == 'all'
Provides-Extra: api
Requires-Dist: httpx>=0.27; extra == 'api'
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == 'cli'
Requires-Dist: typer>=0.15; extra == 'cli'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# salaryfyi

[![PyPI version](https://agentgif.com/badge/pypi/salaryfyi/version.svg)](https://pypi.org/project/salaryfyi/)
[![Python](https://img.shields.io/pypi/pyversions/salaryfyi)](https://pypi.org/project/salaryfyi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/salaryfyi/)

Python API client for [salaryfyi.com](https://salaryfyi.com/) -- salary comparison and tax calculator platform covering 36 countries with income tax brackets, purchasing power parity data, and compensation benchmarks. Access salary calculators, country-specific tax information, and compensation guides through a free REST API, CLI, or MCP server for AI assistants.

[SalaryFYI](https://salaryfyi.com/) provides structured salary and tax data across 36 countries with calculators for net income, tax liability, and cost-of-living comparisons -- built for developers, HR professionals, and job seekers who need accurate compensation reference data.

> **Compare salaries at [salaryfyi.com](https://salaryfyi.com/)** -- tax calculators, salary benchmarks, and cost-of-living comparisons across 36 countries.

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/salaryfyi/main/demo.gif" alt="salaryfyi demo -- salary comparison and tax calculator API client for Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [Tax Calculators by Country](#tax-calculators-by-country)
  - [Salary Benchmarks and Comparisons](#salary-benchmarks-and-comparisons)
  - [Purchasing Power and Cost of Living](#purchasing-power-and-cost-of-living)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [API Reference](#api-reference)
- [Learn More About Salaries](#learn-more-about-salaries)
- [Guide FYI Family](#guide-fyi-family)
- [FYIPedia Developer Tools](#fyipedia-developer-tools)
- [License](#license)

## Install

```bash
pip install salaryfyi              # Core (zero deps)
pip install "salaryfyi[cli]"       # + Command-line interface
pip install "salaryfyi[mcp]"       # + MCP server for AI assistants
pip install "salaryfyi[api]"       # + HTTP client for salaryfyi.com API
pip install "salaryfyi[all]"       # Everything
```

## Quick Start

```python
from salaryfyi.api import SalaryFYI

with SalaryFYI() as api:
    # List available tax calculators
    calculators = api.list_calculators()

    # Get details for a specific country's tax calculator
    us_tax = api.get_calculator("united-states")

    # Browse countries with salary data
    countries = api.list_countries()
    germany = api.get_country("germany")

    # Search across all salary content
    results = api.search("income tax brackets")
```

## What You Can Do

### Tax Calculators by Country

Income tax systems vary dramatically across countries. Progressive tax systems (used by most OECD nations) apply increasing rates to higher income brackets, while flat tax systems apply a single rate regardless of income. Some countries also levy social security contributions, solidarity surcharges, and local/state taxes on top of federal income tax.

| Country | System | Top Rate | Social Security | Notable Feature |
|---------|--------|----------|----------------|----------------|
| United States | Progressive (7 brackets) | 37% | 7.65% (FICA) | State taxes vary 0-13.3% |
| United Kingdom | Progressive (3 bands) | 45% | 12% (NI) | Personal allowance taper |
| Germany | Progressive (continuous) | 45% | ~20% | Solidarity surcharge 5.5% |
| Japan | Progressive (7 brackets) | 45% | ~15% | Residence tax ~10% |
| Singapore | Progressive (9 brackets) | 22% | 20% (CPF) | No capital gains tax |
| UAE | Flat | 0% | 0% | No personal income tax |

```python
from salaryfyi.api import SalaryFYI

# Explore tax calculators for specific countries
with SalaryFYI() as api:
    calculator = api.get_calculator("united-states")
    print(calculator["name"])  # US tax calculator details

    # Browse available categories (income tax, social security, etc.)
    categories = api.list_categories()
```

Learn more: [Tax Calculators](https://calcfyi.com/) · [Glossary](https://salaryfyi.com/) · [Guides](https://salaryfyi.com/guides/)

### Salary Benchmarks and Comparisons

Salary benchmarking compares compensation packages across roles, industries, and geographies. Total compensation includes base salary, bonuses, equity/stock options, benefits, and retirement contributions. The Big Mac Index (published by The Economist) and purchasing power parity (PPP) adjustments help normalize salaries across countries with different cost levels.

| Metric | Description | Use Case |
|--------|-------------|----------|
| Gross Salary | Total compensation before deductions | Job offer comparison |
| Net Salary | Take-home pay after taxes and social security | Living standard comparison |
| PPP-Adjusted | Salary adjusted for local purchasing power | Cross-country comparison |
| Median Salary | 50th percentile for a role/industry | Market rate benchmarking |
| Total Compensation | Base + bonus + equity + benefits | Full package evaluation |

```python
from salaryfyi.api import SalaryFYI

# Browse country-level salary and tax data
with SalaryFYI() as api:
    countries = api.list_countries()
    south_korea = api.get_country("south-korea")

    # Access guides on salary negotiation and tax planning
    guides = api.list_guides()
    guide = api.get_guide("salary-negotiation")
```

Learn more: [Browse Countries](https://salaryfyi.com/) · [Categories](https://salaryfyi.com/) · [API Docs](https://salaryfyi.com/developers/)

### Purchasing Power and Cost of Living

Purchasing power parity (PPP) measures how much a basket of goods costs in different countries. A salary of $100,000 in San Francisco has different purchasing power than $100,000 in Bangkok. The PPP conversion factor, published by the World Bank, adjusts nominal salaries to reflect real buying power.

| City | Cost Index | $100K USD Equivalent Lifestyle |
|------|-----------|-------------------------------|
| San Francisco | 187 | $100,000 |
| New York | 173 | $108,000 |
| London | 141 | $133,000 |
| Berlin | 107 | $175,000 |
| Seoul | 107 | $175,000 |
| Bangkok | 63 | $297,000 |
| Mexico City | 52 | $360,000 |

```python
from salaryfyi.api import SalaryFYI

# Explore salary FAQs and common questions
with SalaryFYI() as api:
    faqs = api.list_faqs()

    # Search for specific salary topics
    results = api.search("cost of living comparison")
```

Learn more: [Countries](https://salaryfyi.com/) · [FAQs](https://salaryfyi.com/) · [Guides](https://salaryfyi.com/guides/)

## Command-Line Interface

```bash
pip install "salaryfyi[cli]"

# Search for salary data
salaryfyi search "Germany income tax"

# Output is JSON for easy piping
salaryfyi search "tax brackets" | jq '.results[0]'
```

## MCP Server (Claude, Cursor, Windsurf)

Add salary and tax data tools to any AI assistant that supports [Model Context Protocol](https://modelcontextprotocol.io/).

```bash
pip install "salaryfyi[mcp]"
```

Add to your `claude_desktop_config.json`:

```json
{
    "mcpServers": {
        "salaryfyi": {
            "command": "python",
            "args": ["-m", "salaryfyi.mcp_server"]
        }
    }
}
```

**Available tools**: `search_salaryfyi`

## REST API Client

```python
from salaryfyi.api import SalaryFYI

with SalaryFYI() as api:
    # List endpoints
    calculators = api.list_calculators()
    categories = api.list_categories()
    countries = api.list_countries()
    guides = api.list_guides()

    # Detail endpoints
    calculator = api.get_calculator("united-kingdom")
    country = api.get_country("japan")

    # Search
    results = api.search("social security")
```

## API Reference

| Method | Description |
|--------|-------------|
| `list_calculators(**params)` | List all tax calculators |
| `get_calculator(slug)` | Get calculator detail |
| `list_categories(**params)` | List all categories |
| `get_category(slug)` | Get category detail |
| `list_countries(**params)` | List all countries |
| `get_country(slug)` | Get country detail |
| `list_guides(**params)` | List all guides |
| `get_guide(slug)` | Get guide detail |
| `list_faqs(**params)` | List all FAQs |
| `get_faq(slug)` | Get FAQ detail |
| `search(query)` | Search across all content |

Full API documentation at [salaryfyi.com/developers/](https://salaryfyi.com/developers/).

## Learn More About Salaries

- **Browse**: [Tax Calculators](https://salaryfyi.com/) · [Countries](https://salaryfyi.com/) · [Categories](https://salaryfyi.com/)
- **Guides**: [Guides](https://salaryfyi.com/guides/) · [FAQs](https://salaryfyi.com/)
- **API**: [REST API Docs](https://salaryfyi.com/developers/) · [OpenAPI Spec](https://salaryfyi.com/api/openapi.json)

## Guide FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem -- life reference guides, calculators, education, and games.

| Package | PyPI | Description |
|---------|------|-------------|
| calcfyi | [PyPI](https://pypi.org/project/calcfyi/) | 200+ calculators, financial, health, math -- [calcfyi.com](https://calcfyi.com/) |
| **salaryfyi** | [PyPI](https://pypi.org/project/salaryfyi/) | **Salary comparison, tax calculators, 36 countries -- [salaryfyi.com](https://salaryfyi.com/)** |
| univfyi | [PyPI](https://pypi.org/project/univfyi/) | University rankings, programs, admissions -- [univfyi.com](https://univfyi.com/) |
| boardgamefyi | [PyPI](https://pypi.org/project/boardgamefyi/) | Board games, rules, reviews, recommendations -- [boardgamefyi.com](https://boardgamefyi.com/) |

## FYIPedia Developer Tools

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| colorfyi | [PyPI](https://pypi.org/project/colorfyi/) | [npm](https://www.npmjs.com/package/@fyipedia/colorfyi) | Color conversion, WCAG contrast, harmonies -- [colorfyi.com](https://colorfyi.com/) |
| emojifyi | [PyPI](https://pypi.org/project/emojifyi/) | [npm](https://www.npmjs.com/package/emojifyi) | Emoji encoding & metadata -- [emojifyi.com](https://emojifyi.com/) |
| symbolfyi | [PyPI](https://pypi.org/project/symbolfyi/) | [npm](https://www.npmjs.com/package/symbolfyi) | Symbol encoding in 11 formats -- [symbolfyi.com](https://symbolfyi.com/) |
| unicodefyi | [PyPI](https://pypi.org/project/unicodefyi/) | [npm](https://www.npmjs.com/package/unicodefyi) | Unicode lookup with 17 encodings -- [unicodefyi.com](https://unicodefyi.com/) |
| fontfyi | [PyPI](https://pypi.org/project/fontfyi/) | [npm](https://www.npmjs.com/package/fontfyi) | Google Fonts metadata & CSS -- [fontfyi.com](https://fontfyi.com/) |
| distancefyi | [PyPI](https://pypi.org/project/distancefyi/) | [npm](https://www.npmjs.com/package/distancefyi) | Haversine distance & travel times -- [distancefyi.com](https://distancefyi.com/) |
| timefyi | [PyPI](https://pypi.org/project/timefyi/) | [npm](https://www.npmjs.com/package/timefyi) | Timezone ops & business hours -- [timefyi.com](https://timefyi.com/) |
| namefyi | [PyPI](https://pypi.org/project/namefyi/) | [npm](https://www.npmjs.com/package/namefyi) | Korean romanization & Five Elements -- [namefyi.com](https://namefyi.com/) |
| unitfyi | [PyPI](https://pypi.org/project/unitfyi/) | [npm](https://www.npmjs.com/package/unitfyi) | Unit conversion, 220 units -- [unitfyi.com](https://unitfyi.com/) |
| holidayfyi | [PyPI](https://pypi.org/project/holidayfyi/) | [npm](https://www.npmjs.com/package/holidayfyi) | Holiday dates & Easter calculation -- [holidayfyi.com](https://holidayfyi.com/) |
| **salaryfyi** | [PyPI](https://pypi.org/project/salaryfyi/) | -- | **Salary comparison, tax calculators, 36 countries -- [salaryfyi.com](https://salaryfyi.com/)** |
| cocktailfyi | [PyPI](https://pypi.org/project/cocktailfyi/) | -- | Cocktail ABV, calories, flavor -- [cocktailfyi.com](https://cocktailfyi.com/) |
| fyipedia | [PyPI](https://pypi.org/project/fyipedia/) | -- | Unified CLI for all FYI tools -- [fyipedia.com](https://fyipedia.com/) |

## License

MIT
