{"id":24698554,"url":"https://github.com/faradayio/earth","last_synced_at":"2025-10-09T06:30:57.031Z","repository":{"id":975823,"uuid":"774777","full_name":"faradayio/earth","owner":"faradayio","description":"Land, sky, and sea","archived":false,"fork":false,"pushed_at":"2021-01-20T04:33:57.000Z","size":3529,"stargazers_count":40,"open_issues_count":3,"forks_count":6,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-01-21T05:36:04.816Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://data.brighterplanet.com","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/faradayio.png","metadata":{"files":{"readme":"README.markdown","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-07-14T15:10:13.000Z","updated_at":"2024-11-15T12:47:16.000Z","dependencies_parsed_at":"2022-08-16T11:40:34.486Z","dependency_job_id":null,"html_url":"https://github.com/faradayio/earth","commit_stats":null,"previous_names":["brighterplanet/earth"],"tags_count":134,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fearth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fearth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fearth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fearth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/faradayio","download_url":"https://codeload.github.com/faradayio/earth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235801792,"owners_count":19047126,"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","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":[],"created_at":"2025-01-27T04:29:18.560Z","updated_at":"2025-10-09T06:30:50.407Z","avatar_url":"https://github.com/faradayio.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# earth\n\nEarth is a collection of *data models* that represent various things found here on Earth, such as countries, automobiles, aircraft, zip codes, and pet breeds.\n\nBy default the data that these models represent is pulled from [Brighter Planet's open reference data site](http://data.brighterplanet.com) using the [taps gem](http://rubygems.org/gems/taps). The data can also be imported directly from preconfigured authoritative sources. \n\n## Usage\n\n``` ruby\nrequire 'earth'\nrequire 'earth/automobile/automobile_fuel'\n\nEarth.init\nft = AutomobileFuel.first\n# ...\n```\n\n`Earth.init` prepares the environment to load and download data for each data model. You can load all data models at once with `Earth.init :all`. There are several other options to `init` that configure data mining sources and database connections. See the [rdocs](http://rdoc.info/github/brighterplanet/earth) for more details on the Earth module.\n\n### Data model categories\n\n\u003ctable\u003e\n  \u003cthead\u003e\n  \u003ctr\u003e\n    \u003cth\u003eCategory\u003c/th\u003e\n    \u003cth\u003eModels\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/brighterplanet/earth/tree/master/lib/earth/air\"\u003e\u003ccode\u003e:air\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eAircraft, Airline, Airport ...\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/brighterplanet/earth/tree/master/lib/earth/automobile\"\u003e\u003ccode\u003e:automobile\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eAutomobileFuel, AutomobileMake, AutomobileModel ...\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/brighterplanet/earth/tree/master/lib/earth/bus\"\u003e\u003ccode\u003e:bus\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eBusClass, BusFuel ...\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/brighterplanet/earth/tree/master/lib/earth/computation\"\u003e\u003ccode\u003e:computation\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eComputationCarrier, ComputationCarrierInstanceClass ...\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/brighterplanet/earth/tree/master/lib/earth/diet\"\u003e\u003ccode\u003e:diet\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eDietClass, FoodGroup ...\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/brighterplanet/earth/tree/master/lib/earth/fuel\"\u003e\u003ccode\u003e:fuel\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eFuel, FuelPrice, GreenhouseGas ...\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/brighterplanet/earth/tree/master/lib/earth/hospitality\"\u003e\u003ccode\u003e:hospitality\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eLodgingClass, CommercialBuildingEnergyConsumptionSurveyResponse ...\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/brighterplanet/earth/tree/master/lib/earth/industry\"\u003e\u003ccode\u003e:industry\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eIndustry, CbecsEnergyIntensity ...\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/brighterplanet/earth/tree/master/lib/earth/locality\"\u003e\u003ccode\u003e:locality\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eCensusDivision, Country, ZipCode ...\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/brighterplanet/earth/tree/master/lib/earth/pet\"\u003e\u003ccode\u003e:pet\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eBreed, Gender, Species ...\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/brighterplanet/earth/tree/master/lib/earth/rail\"\u003e\u003ccode\u003e:rail\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eRailClass, RailFuel, RailCompany ...\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/brighterplanet/earth/tree/master/lib/earth/residence\"\u003e\u003ccode\u003e:residence\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eUrbanity, ResidenceClass, AirConditionerUse\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/brighterplanet/earth/tree/master/lib/earth/shipping\"\u003e\u003ccode\u003e:shipping\u003c/code\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eCarrier, ShipmentMode ...\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n    \n\n### Data storage\n\nYou can store Earth data in any relational database. On your very first run, you will need to create the tables for data each model. You can either use the Rails standard rake tasks (see below) or with a call to `Earth.reset_schemas!`\n\n### Pulling data from data.brighterplanet.com\n\nBy default, Earth will pull data from [data.brighterplanet.com](http://data.brighterplanet.com), which continuously (and transparently) refreshes its data from authoritative sources. Simply call `#run_data_miner!` on whichever data model class you need. If there are any Earth classes that the chosen class depends on, they will be downloaded as well automatically:\n\n``` ruby\nrequire 'earth'\nrequire 'earth/locality/zip_code'\n\nEarth.init\nZipCode.run_data_miner!\n```\n\n### Pulling data from the original sources\n\nIf you'd like to bypass the [data.brighterplanet.com](http://data.brighterplanet.com) proxy and pull data directly from authoritative sources (*e.g.,* automobile data from EPA), simply specify the :mine_original_sources option to `Earth.init`\n\n``` ruby\nrequire 'earth'\nEarth.init :mine_original_sources =\u003e true\n\nrequire 'earth/automobile'\nAutomobileMake.run_data_miner!\n```\n\n### Rake tasks\n\nEarth provides handy rails tasks for creating, migrating, and data mining models whether you're using it from a Rails app or a standalone Ruby app.\n\nIn your Rakefile, add:\n\n    require 'earth/tasks'\n    Earth::Tasks.new\n\nIf you're using Earth outside of Rails, all of the default `rake db:*` tasks will now be available. Within rails, certain tasks are augmented to \nhelp manage your Earth models using data_miner and active_record_inline_schema in addition to standard migrations.\n\nOf note are the following tasks:\n\n* `rake db:migrate` runs `.create_table!` on each Earth resource model.\n* `rake db:seed` runs `.run_data_miner!` on each Earth resource model.\n\n## Collaboration cycle \nBrighter Planet vigorously encourages collaborative improvement.\n\n### You\n1.  Fork the earth repository on GitHub.\n1.  Write a test proving the existing implementation's inadequacy. Ensure that the test fails. Commit the test.\n1.  Improve the code until your new test passes and commit your changes.\n1.  Push your changes to your GitHub fork.\n1.  Submit a pull request to brighterplanet.\n\n### Brighter Planet\n1.  Receive a pull request.\n1.  Pull changes from forked repository.\n1.  Ensure tests pass.\n1.  Review changes for scientific accuracy.\n1.  Merge changes to master repository and publish.\n1.  Direct production environment to use new library version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaradayio%2Fearth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaradayio%2Fearth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaradayio%2Fearth/lists"}