{"id":14986792,"url":"https://github.com/jfoclpf/autocosts","last_synced_at":"2025-08-12T18:07:57.999Z","repository":{"id":27383822,"uuid":"19325556","full_name":"jfoclpf/autocosts","owner":"jfoclpf","description":"The monorepo for the fully free and open source full-stack Car Costs Calculator for more than 30 countries","archived":false,"fork":false,"pushed_at":"2024-12-06T03:44:05.000Z","size":110579,"stargazers_count":41,"open_issues_count":10,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-09T01:51:42.304Z","etag":null,"topics":["android-application","automobile","automobile-costs","calculator","calculator-application","car","car-costs","cost","expressjs","fuel-efficiency","handlebars","javascript","jquery","nodejs","standardjs","uber","website"],"latest_commit_sha":null,"homepage":"https://autocosts.info","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jfoclpf.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"jfoclpf","liberapay":"joaopimentel1980"}},"created_at":"2014-04-30T20:00:04.000Z","updated_at":"2025-05-27T06:25:01.000Z","dependencies_parsed_at":"2024-06-12T02:22:57.112Z","dependency_job_id":"222cf495-dce0-4c1b-a4de-3827f416c5fe","html_url":"https://github.com/jfoclpf/autocosts","commit_stats":{"total_commits":2428,"total_committers":11,"mean_commits":"220.72727272727272","dds":0.08731466227347606,"last_synced_commit":"ca67300bde4cb6fd7a768262b97bc5825a48327c"},"previous_names":[],"tags_count":160,"template":false,"template_full_name":null,"purl":"pkg:github/jfoclpf/autocosts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfoclpf%2Fautocosts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfoclpf%2Fautocosts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfoclpf%2Fautocosts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfoclpf%2Fautocosts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jfoclpf","download_url":"https://codeload.github.com/jfoclpf/autocosts/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfoclpf%2Fautocosts/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269677801,"owners_count":24457876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android-application","automobile","automobile-costs","calculator","calculator-application","car","car-costs","cost","expressjs","fuel-efficiency","handlebars","javascript","jquery","nodejs","standardjs","uber","website"],"created_at":"2024-09-24T14:13:33.593Z","updated_at":"2025-08-12T18:07:57.954Z","avatar_url":"https://github.com/jfoclpf.png","language":"JavaScript","funding_links":["https://github.com/sponsors/jfoclpf","https://liberapay.com/joaopimentel1980"],"categories":[],"sub_categories":[],"readme":"[![js-standard-style][js-standard-style_img]][js-standard-style_url]\n[![npm module downloads][npm_module_downloads_img]][npm_module_downloads_url]\n\n[js-standard-style_img]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg\n[js-standard-style_url]: https://standardjs.com/\n\n[npm_module_downloads_img]: https://img.shields.io/npm/dt/autocosts.svg\n[npm_module_downloads_url]: https://www.npmjs.com/package/autocosts\n\n# autocosts\n**The fully free and open source full-stack Car Costs Calculator for more than 30 countries**\n\nThis calculator gives users a good estimate of what they really need to spend on car ownership. As car payments and expenses come due throughout the year, it's often difficult to really get a good understanding of total spending on a car. \n\nThis calculator also provides to the user, optionally, the car's full Financial Effort considering the user's income, further providing also optionally the equivalent public transport costs (bus, train, UBER, etc.), considering the user doesn't own a car.\n\n![screenshot](https://github.com/jfoclpf/autocosts/raw/master/src/img/screenshot.png)\n\n## Run it on your machine\n1. Clone the project\u003cbr\u003e\n`git clone https://github.com/jfoclpf/autocosts.git`\n2. Enter in the newly created directory and install dependencies\u003cbr\u003e\n`cd autocosts \u0026\u0026 npm ci --omit=dev`\n3. Start the server\u003cbr\u003e\n`npm start`\n\nit will open a http local server which you can access through `http://localhost:3028`\n\n## Website\nhttps://autocosts.info\n\n### Playground\nhttps://autocosts.info/XX\n\n### The list of available countries\nhttps://autocosts.info/list\n\nThe translations are in corresponding `json` files, namely in the folder `src/countries/`.\u003cbr\u003e\nThe list of available countries is from the file `src/countries/list.json`\n\n### World statistics of Car Costs\nhttps://autocosts.info/worldstats\n\n\n## How does it work?\nAutocosts uses `nodejs`, `expressjs` and `handlebarsjs` to supply a server application that renders a car costs calculator as a webpage loaded by any common browser.\n\nThe project is optimized for a web-based version, and for an APP developped in Apache Cordova. The 2 last letters on the URI stands for the 2-letter ISO country code, and not for the language, since for example United Kingdom and Australia have the same language but different realities concerning the taxes, the terms applied to automobile costs and the units for fuel efficiency. The translations/language files apply therefore only to the selected country.\n\nThe project already considers all the units and fuel efficiency cases, different in many countries. The variations for fuel efficiency are `L/100km`, `km/L`, `mpg(US)`, `mpg(imp)` and for distance are `km`, `miles` and `mil` (Nordic mile=10km). More information can be found in the directory [`src/countries/`](src/countries/).\n\nFor more information regarding how the costs are calculated, you can check the [`src/client/core/`](src/client/core/) which is based on the \u003ca href=\"https://en.wikipedia.org/wiki/Car_costs\"\u003e12 items that form the car costs\u003c/a\u003e for any given country. Namely they are:\n\n* Standing costs\n  * Depreciation\n  * Car taxes\n  * Insurance\n  * Inspection\n  * Car finance\n* Running costs\n  * Fuel\n  * Maintenance\n  * Repairs and Improvements\n  * Parking\n  * Tolls\n  * Fines\n  * Car washes\n\nFor more information see [`contributing.md`](contributing.md)\n\n### Aditional services\nAutocosts supports the following additional services, which can be enabled or disabled (default).\nAfter building with `node build.js`, run `node bin/server.js -h` for more information.\n\n### Database\n\nAutocosts also supports code such that the user inputs might be stored into a `mysql` database. With the data from said database, it is also possible to make several statisitcal analysis, namely the average costs for each country, said statistical analysis having outlier removal techniques, such that such outliers do not distort the average.\n\n### Uber\n\nAutocosts may use the UBER API, such that at the final repport, the user calculations can be compared with the equivalents costs if the user would use just UBER or combined with public transports.\n\n### PDF\n\nAutocosts also allows the final report to be printed into a PDF report. It makes use of `pdfmake` npm package.\n\n### Credentials file\n\nThe credentials for the above services are in the JSON files stored in [`credentials/`](/credentials/)\n\n## API\n\nThe API works normally as any other npm API without the need to install any extra software.\n\nJust install the API\n\n`npm i autocosts`\n\nNow use the autocosts API\n\n```js\nconst autocosts = require('autocosts')\n\n// see https://github.com/jfoclpf/autocosts/blob/master/contributing.md#standards\n// for standard units and time periods\n\nvar userData = {\n  countryCode: 'US',\n  currency: 'USD',\n  depreciation: {\n    dateOfAcquisition: {\n      month: 5,\n      year: 2001,\n      valueOfTheVehicle: 25000\n    },\n    dateOfUserInput: {\n      month: 2,\n      year: 2020,\n      valueOfTheVehicle: 5000\n    }\n  },\n  insurance: {\n    amountPerPeriod: 200,\n    period: 'month'\n  },\n  credit: {\n    creditBool: true,\n    yesCredit: {\n      borrowedAmount: 15000,\n      numberInstallments: 48,\n      amountInstallment: 350,\n      residualValue: 0\n    }\n  },\n  inspection: {\n    averageInspectionCost: 120,\n    numberOfInspections: 15\n  },\n  roadTaxes: {\n    amountPerYear: 120\n  },\n  // Form Part 2\n  fuel: {\n    typeOfCalculation: 'distance', // type string: \"money\" or \"distance\"\n    currencyBased: {\n      amountPerPeriod: null,\n      period: null // type string: \"month\", \"twoMonths\",  \"trimester\", \"semester\", \"year\"\n    },\n    distanceBased: {\n      considerCarToJob: true, // boolean\n      carToJob: {\n        daysPerWeek: 5,\n        distanceBetweenHomeAndJob: 15,\n        distanceDuringWeekends: 30,\n        distanceStandardUnit: 'mi' // standard distance for current country: \"km\", \"mil\" or \"mil(10km)\"\n      },\n      noCarToJob: {\n        distancePerPeriod: null,\n        period: null, // type string: \"month\", \"twoMonths\",  \"trimester\", \"semester\", \"year\"\n        distanceStandardUnit: null // type string: \"km\", \"mil\" or \"mil(10km)\"\n      },\n      fuelEfficiency: 25, // fuel efficiency of the vehicle\n      fuelEfficiencyStandard: 'mpg(US)', // type string; \"L/100km\", \"mpg(US)\", etc.\n      fuelPrice: 2.5, // type number; currency per unit of volume standard. Ex: 1.4, that is 1.4 EUR / L\n      fuelPriceVolumeStandard: 'gal(US)' // type string: 'L', 'gal(imp)', 'gal(US)'\n    }\n  },\n  maintenance: {\n    amountPerYear: 700\n  },\n  repairsImprovements: {\n    amountPerYear: 200\n  },\n  parking: {\n    amountPerMonth: 14\n  },\n  tolls: {\n    calculationBasedOnDay: true, // true or false\n    yesBasedOnDay: {\n      amountPerDay: 2.5,\n      daysPerMonth: 22\n    },\n    noBasedOnDay: {\n      amountPerPeriod: null,\n      period: null // type string: \"month\", \"twoMonths\",  \"trimester\", \"semester\", \"year\"\n    }\n  },\n  fines: {\n    amountPerPeriod: 40,\n    period: 'year' // type string: \"month\", \"twoMonths\",  \"trimester\", \"semester\", \"year\"\n  },\n  washing: {\n    amountPerPeriod: 110,\n    period: 'year' // type string: \"month\", \"twoMonths\",  \"trimester\", \"semester\", \"year\"\n  }\n}\n\nvar results = autocosts.calculate(userData)\nconsole.log(results)\n```\n\nThe object `results` will be the following:\n\n```json\n{\n  \"countryCode\": \"US\",\n  \"currency\": \"USD\",\n  \"costs\": {\n    \"totalPerYear\": 6595.880952380952,\n    \"totalEver\": 123672.76785714286,\n    \"perMonth\": {\n      \"items\": {\n        \"depreciation\": 88.88888888888889,\n        \"insurance\": 200,\n        \"credit\": 8,\n        \"inspection\": 8,\n        \"roadTaxes\": 10,\n        \"fuel\": 78.26785714285715,\n        \"maintenance\": 58.333333333333336,\n        \"repairsImprovements\": 16.666666666666668,\n        \"parking\": 14,\n        \"tolls\": 55,\n        \"fines\": 3.3333333333333335,\n        \"washing\": 9.166666666666666\n      },\n      \"standingCosts\": 344.0555555555556,\n      \"runningCosts\": 205.60119047619048,\n      \"total\": 549.656746031746\n    },\n    \"perUnitDistance\": {}\n  },\n  \"standardUnits\": {\n    \"speed\": \"mi/h\",\n    \"distance\": \"mi\",\n    \"fuelEfficiency\": \"mpg(US)\",\n    \"fuelPriceVolume\": \"gal(US)\"\n  }\n}\n\n```\n\nThe financial effort of the user and alternative costs considering public transports, uber and taxis included, are also optionally calculated. See [the standard `userData` object](/contributing.md#userdata-class) for more information.\n\n## Development\n\n### Extra SW requirements\n\nTo development and fully build the app one further needs:\n\n - `ImageMagick` (to compress images) and \n - `Webdriver Manager` npm package to emulate Chrome and Firefox in the test suite\n\nOn Ubuntu/Debian one can run to install and configure them:\n\n```\nsudo apt install imagemagick -y\nsudo npm i -g webdriver-manager\nsudo webdriver-manager update --out_dir /usr/local/bin\nsudo rm /usr/local/bin/*.zip /usr/local/bin/*.tar.gz\nsudo mv /usr/local/bin/chromedriver* /usr/local/bin/chromedriver\nsudo mv /usr/local/bin/geckodriver* /usr/local/bin/geckodriver\n```\n\n### Build\n\nTo custom build the app resources into the `bin/` directory, use the `build.js` node script at the root of the project. For more information run `node build.js --help`.\nYou have already standard configurations accessible in `package.json` which you can list by executing `npm run`.\n\n### Running\n\nAfter having built the app, to custom run it use the `bin/server.js` node script. For more information run `node bin/server.js --help`.\nSee also standard server configurations by executing `npm run`.\n\n## Android APP\n\nThe \u003ca href=\"https://play.google.com/store/apps/details?id=info.autocosts\"\u003eAndroid APP can be found in Play Store\u003c/a\u003e. It uses Apache Cordova to convert JavaScript built code into APP built files (for example APK files in Android)\n\n## About\n\n### Contributing, data structure, flowcharts and coding rules\n\nSee [contributing](https://github.com/jfoclpf/autocosts/blob/master/contributing.md) and the [wiki pages](https://github.com/jfoclpf/autocosts/wiki)\n\n### License\n\n\u003ca href=\"http://www.gnu.org/licenses/gpl-3.0.en.html\"\u003eGNU GPLv3\u003c/a\u003e\n\n## Privacy\n\nThis calculator is and shall always be completely anonymous, as it doesn't request nor permanently store, any name, email, cookies, IP address nor any other personal information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfoclpf%2Fautocosts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjfoclpf%2Fautocosts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfoclpf%2Fautocosts/lists"}