Data from pplapi can be loaded into MASON in several ways:

  1. live samples: retrieve live CSV data from the API.
  2. archival samples: use CSV data that was previously saved to your computer.

Example: Global Distribution of Agents

In the following visualization, n=1500 agents were sampled at random from the world population and their latitude/longitude was plotted. Country outlines were composited to provide context.


Live API Data

If you choose to use live API data, this will result in your simulations using different agent data each time. Presently, it is recommended that you simply download and put it in your MASON project. MASON also requires additional Java libraries from the Apache Foundation In order to function. See Installing Java Libraries for more information.

The following example code is an extension of the MASON SchoolYard tutorial. The example will request 500 agents from pplapi and add them to our simulated world.

import sim.engine.*;
import sim.util.*;
import sim.field.continuous.*;
import sim.field.grid.*;
import org.apache.commons.csv.*;


public class People extends SimState {

    // people occupy a 2d environment
    public Continuous2D world = new Continuous2D(0.1,360,180);

    // use pplapi to recruit agents from Agent Space
    PplApi pplapi = new PplApi();

    public void start() {

        // clear the world

        // add some people to the world
        Iterable<CSVRecord> records = pplapi.getBatchCSV(500);

        if (records != null) {
            for (CSVRecord record : records) {
                Person person = new Person();
                person.country_name = record.get("country_name");
                person.income = Integer.parseInt(record.get("income"));
       = Long.parseLong(record.get("id"));
                person.longitude = Double.parseDouble(record.get("longitude"));
                person.latitude = Double.parseDouble(record.get("latitude"));
                person.age = Integer.parseInt(record.get("age"));
                person.internet = Boolean.parseBoolean(record.get("internet").toLowerCase());

                // put the person on the globe, using latitude/longitude
                Double2D location = new Double2D(180+person.longitude, 90-person.latitude);
                world.setObjectLocation(person, location);


    public People(long seed) {

    public static void main(String[] args) {
        doLoop(People.class, args);

Installing Java Libraries

In order to connect your MASON simulation to the API, it is helpful to make use of the Apache Foundation’s HTTP and CSV libraries. This section provides some information to get you started.

Apache Commons CSV

  1. Download the Apache Commons CSV .jar here. or later is recommended.
  2. Unzip the archive and install it to your CLASSPATH.

Apache HTTP Components

  1. Download the Apache HTTP Components .jar here. or later is recommended.
  2. Unzip the archive and install it to your CLASSPATH.

A note about OS X CLASSPATH

In this author’s experience, it is easiest to copy any .jar files to the OS X default location instead of trying to manually control the CLASSPATH. The following is a brief example:

cp *.jar ~/Library/Java/Extensions


Related Topics