employercosts

package module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: MIT Imports: 9 Imported by: 0

README

employercosts

Dependency-free Go package that embeds the EOR Scope dataset of statutory employer costs, as typed, read-only records.

  • 76 countries: employer cost in % and USD per month at an example salary, local currency, exchange rate and review date
  • 543 employer contribution and statutory extra lines, each with rate, base, floor/ceiling, source URL and date
  • 108 declared assumptions (the case each country's total holds for)
import "github.com/eorscope/employercosts"

de, ok := employercosts.Country("DE")
lines := employercosts.Contributions("DE")
europe := employercosts.CountriesInRegion("Europe")

The package is a lookup library: it returns the figures as exported and computes nothing. Countries flagged TotalDeclaredFloor publish an "at least" figure, not a total; under TotalDeclaredCeiling the modelled contribution base is the highest the law allows and lines with InTotal false come on top. For a cost at another salary, use the EOR cost calculator. Sources and method: methodology.

Cost comparison, not legal or tax advice.

Updating the data

sync.sh copies the three CSV files and the data licence from ../../dataset/eorscope-employer-costs/ (or the directory given as first argument) into data/. Then run go vet ./... && go test ./....

Licence

Code: MIT, see LICENSE.

Data (data/): CC BY 4.0, see data/LICENSE. Attribution: EOR Scope, published by Trésor Kaya EI (Les Créavores), France.

Documentation

Overview

Package employercosts embeds the EOR Scope dataset of statutory employer costs (76 countries) and exposes it as typed, read-only records. It has no dependencies and makes no network calls.

The package is a lookup library: it returns the figures as exported and computes nothing. Employer cost totals are the ones published in the dataset; the package does not recompute them. For a cost at another salary, use the calculator at https://eorscope.com/eor-cost-calculator/.

  • Countries, Country and CountriesInRegion return one record per country.
  • Contributions returns the employer contributions and statutory extras of a country.
  • Assumptions returns the case each country's lines and total hold for.

A country flagged TotalDeclaredFloor publishes an "at least" figure, not a total. Under TotalDeclaredCeiling the modelled contribution base is the highest the law allows, and lines with InTotal false come on top. A contribution's Rate applies to its Base times BaseFactor (1 unless the law builds the base from more than the salary, as Mexico's integrated base does), before BaseFloorAnnualLocal and BaseCapAnnualLocal.

Sources and method are described at https://eorscope.com/methodology/ and each country has a page under https://eorscope.com/employer-of-record/ with its sources. The figures are a cost comparison, not legal or tax advice.

Data licence: the embedded dataset is licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Attribution: EOR Scope, published by Trésor Kaya EI (Les Créavores), France. The Go code is MIT licensed.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Regions

func Regions() []string

Regions returns the distinct regions, sorted.

Types

type Assumption

type Assumption struct {
	ISO   string
	ID    string // unique within the country
	Label string
	Value float64 // a share, a rate, a threshold, or 1 for a stated condition
	Notes string
}

Assumption is one row of country_assumptions.csv: the case a country's lines and total are priced for.

func Assumptions

func Assumptions(iso string) []Assumption

Assumptions returns the declared assumptions of a country, in dataset order.

type Contribution

type Contribution struct {
	ISO                  string
	Country              string
	Currency             string
	LineType             string // contribution | statutory_extra
	LineID               string // unique within the country and line type
	LineName             string
	Rate                 *float64 // decimal (0.12 = 12%); nil for statutory extras
	Base                 string   // gross | basic | flat | band | "" (statutory extras)
	BaseFactor           *float64 // multiplier on the base, applied before floor and cap (1 = the salary itself); nil for flat lines and statutory extras
	BaseFloorAnnualLocal *float64 // yearly floor on the base, local currency
	BaseCapAnnualLocal   *float64 // yearly ceiling on the base, local currency
	FlatAnnualLocal      *float64 // fixed yearly amount when Base is "flat"
	MinGrossAnnualLocal  *float64 // line applies only when annual gross is at least this
	MaxGrossAnnualLocal  *float64 // line applies only when annual gross is at most this
	ExtraKind            string   // percent | months | days | "" (contributions)
	ExtraValue           *float64 // value in the unit given by ExtraKind
	SecondarySource      bool     // the line rests, in whole or in part, on a non-official source
	ThirteenthMonth      bool     // the country mandates a 13th-month salary
	TotalDeclaredFloor   bool     // the country's employer cost is an "at least" figure
	TotalDeclaredCeiling bool     // the modelled base is the highest the law allows
	InTotal              bool     // the line is included in the employer cost total
	Applies              string   // condition in plain words
	Notes                string
	SourceName           string
	SourceURL            string
	SourceCheckedAt      time.Time
}

Contribution is one row of country_contributions.csv: an employer contribution (LineType "contribution") or a statutory extra (LineType "statutory_extra").

func Contributions

func Contributions(iso string) []Contribution

Contributions returns the contribution and statutory extra lines of a country, in dataset order.

type CountrySummary

type CountrySummary struct {
	ISO                    string   // ISO 3166-1 alpha-2
	Name                   string   // country name
	Region                 string   // region, see Regions
	Currency               string   // ISO 4217 local currency
	ExampleSalaryUSD       int      // illustrative gross annual salary in USD (an example, not a median)
	ExampleRole            string   // illustrative role
	ExamplePlace           string   // state, province or city the lines are priced for, when not national
	BasicShareOfGross      *float64 // share of gross taken as basic pay by lines with Base "basic"
	EmployerCostPct        float64  // statutory employer cost, percent of gross at the example salary
	EmployerCostPctPrinted float64  // the same percent as printed on eorscope.com (1 decimal)
	// TotalDeclaredFloor: the employer cost is an "at least" figure, not a total.
	TotalDeclaredFloor bool
	// TotalDeclaredCeiling: the modelled contribution base is the highest the
	// law allows; lines with InTotal false come on top.
	TotalDeclaredCeiling bool
	EmployerCostUSDMonth float64   // statutory employer cost per month in USD at the example salary
	TotalExcludes        string    // a cost the total leaves out
	FXLocalPerUSD        float64   // local currency units per 1 USD used for the conversion
	FXDate               time.Time // date of the exchange rate (zero for USD)
	LastReviewed         time.Time // date the country data was last verified
}

CountrySummary is one row of country_summary.csv. Optional numbers are nil when the dataset leaves them empty; dates are zero when empty.

func Countries

func Countries() []CountrySummary

Countries returns every country, sorted by ISO code.

func CountriesInRegion

func CountriesInRegion(region string) []CountrySummary

CountriesInRegion returns the countries of a region (case-insensitive), sorted by ISO code.

func Country

func Country(iso string) (CountrySummary, bool)

Country returns the country with the given ISO 3166-1 alpha-2 code (case-insensitive).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL