Earth is a collection of data models that represent various things found here on Earth, such as pet breeds, kinds of rail travel, zip codes, and Petroleum Administration for Defense Districts.
The data that these models represent can be pulled from preconfigured authoritative sources.
require 'earth' Earth.init :automobile, :locality ft = AutomobileFuel.first # ...
Earth.init loads desired "data domains" as well as any supporting classes and plugins that each data model needs. A "data domain" is a grouping of related data models. For instance, all automobile-related data is in the
||Aircraft, Airline, Airport ...|
||AutomobileFuel, AutomobileMake, AutomobileModel ...|
||BusClass, BusFuel ...|
||ComputationCarrier, ComputationCarrierInstanceClass ...|
||DietClass, FoodGroup ...|
||Fuel, FuelPrice, GreenhouseGas ...|
||LodgingClass, CommercialBuildingEnergyConsumptionSurveyResponse ...|
||Industry, CbecsEnergyIntensity ...|
||CensusDivision, Country, ZipCode ...|
||Breed, Gender, Species ...|
||RailClass, RailFuel, RailCompany ...|
||Urbanity, ResidenceClass, AirConditionerUse|
||Carrier, ShipmentMode ...|
You can store Earth data in any relational database. On your very first run, you will need to create the tables for data each model. This is done using minirecord with the
require 'activerecord' ActiveRecord::Base.establish_connection :adapter => ... # Not needed if using Rails require 'earth' Earth.init :all, :apply_schemas => true
Pulling data from data.brighterplanet.com
By default, Earth will pull data from 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:
require 'earth' Earth.init :locality ZipCode.run_data_miner!
Pulling data from the original sources
If you'd like to bypass the data.brighterplanet.com proxy and pull data directly from authoritative sources (e.g., automobile data from EPA), simply require the
data\_miner file for the desired domain:
require 'earth' Earth.init :automobile require 'earth/automobile/data_miner' AutomobileMake.run_data_miner!
Brighter Planet vigorously encourages collaborative improvement.
- Fork the earth repository on GitHub.
- Write a test proving the existing implementation's inadequacy. Ensure that the test fails. Commit the test.
- Improve the code until your new test passes and commit your changes.
- Push your changes to your GitHub fork.
- Submit a pull request to brighterplanet.
- Receive a pull request.
- Pull changes from forked repository.
- Ensure tests pass.
- Review changes for scientific accuracy.
- Merge changes to master repository and publish.
- Direct production environment to use new library version.