Mockaroo APIs

Overview

Mockaroo offers two different approaches for downloading data programmatically:

Generate API

Mockaroo's Generate API is a single endpoint that you can use to generate data based on a saved schema or fields you define in the post body of the request. Anything you can generate via the website can also be generated via the data API.

Mock APIs

Mock APIs give your full control over URLs, handling request parameters, and simulating errors. Mock APIs are ideal for simulating back ends before they're built so you can start working on your front end code. Configure Mock APIs using the APIs link in the header.

Gaining Access

Both APIs require an API Key to be passed with each request, either as a query string parameter called "key" or as an "X-API-Key" request header.

Here is your API key:

Usage Limits

All API requests are limited to 5000 records. Free plans are limited to 200 requests per day. Silver and Gold plans are limited to a total number of records per day (with no request limit). This allows developers with paid plans to issue many more small requests than would be allowed with a free plan.

Data API

The Mockaroo Data API has the following methods:

GET /api/types

Returns an array of the available types. Each object has the following keys:

• name (string) - The name of the type
• parameters (array) - Additional options that can be specified
  • name (string) - The parameter name
  • type (string) - The parameter type
  • description (string) - A description of the parameter
  • default (any) - The default value of the parameter if not specified

POST /api/datasets/:name

Uploads a dataset. Specify the data in the request body and the mime type as the Content-Type header.Content-Type must be text/csv or text/plain.

• name (required) The name of the dataset to create or update.
• filename (optional) The name of the original file. The file name must have a .csv or .txt extension.
• project (optional) The name of an existing project to add the dataset to.

Example (JavaScript)

const fetch = require('node-fetch')
const fs = require('fs')

function upload(apiKey, name, path) {
  fetch(`https://api.mockaroo.com/api/datasets/${encodeURIComponent(name)}?key=${encodeURIComponent(apiKey)}`, {
    method: 'post',
    body: fs.readFileSync(path),
    headers: {
      "content-type": "text/csv"
    }
  })
  .then(res => res.json())
  .then(result => console.log(result))
}

DELETE /api/datasets/:name

Deletes a dataset by name.

• name (required) The name of the dataset to delete.

Example (JavaScript)

const fetch = require('node-fetch')
const fs = require('fs')

function destroy(apiKey, name, path) {
  fetch(`https://api.mockaroo.com/api/datasets/${encodeURIComponent(name)}?key=${encodeURIComponent(apiKey)}`, {
    method: 'delete'
  })
  .then(res => res.json())
  .then(result => console.log(result))
}

POST /api/generate(.format)

Generates data based on parameters you provide or a saved schema.

Formats

Output format is specified by the file type part of the URL. Two formats are supported:

Query String Parameters

Request Body

If the schema url parameter is not specified, the request body should be a json array of field specifications. Each item in the array should have the following properties:

Type Specific Parameters

The following types have additional parameters:

{last_name}, {first_name}

Client Libraries

There are several client libraries for the Mockaroo API:

• Node.js
  • mockaroo-node (officially supported)
• C#
  • mockaroo.api
  • NMockaroo

Example: jQuery (jsonp)

var fields = [{
    name: "yearsEmployed",
    type: "Number",
    min: 1,
    max: 30,
    decimals: 0
}, {
    name: "department",
    type: "Custom List",
    values: ["R+D", "Marketing", "HR"]
}, {
    name: "dob",
    type: "Date",
    min: "1/1/1950",
    max: "1/1/2000",
    format: "%m/%d/%Y"
}];

var url = 'https://api.mockaroo.com/api/generate.json?key=abcd1234' +
  '&fields=' + encodeURIComponent(JSON.stringify(fields));

$.ajax(url, {
    dataType: 'jsonp',
    contentType: 'application/json',
    success: function(data) {
        console.log('yearsEmployed', data.yearsEmployed);
        console.log('department', data.department);
        console.log('dob', data.dob);
    }
});

Here's a jsFiddle you can play with.

Example: Node.js

var Mockaroo = require('mockaroo'); // npm install mockaroo

var client = new Mockaroo.Client({
    apiKey: // your api key here
})

client.generate({
    count: 10,
    fields: [{
        name: 'id',
        type: 'Row Number'
    }, {
        name: 'transactionType',
        type: 'Custom List',
        values: ['credit', 'debit']
    }]
}).then(function(records) {
    for (var i=0; i<records.length; i++) {
        var record = records[i];
        console.log('record ' + i, 'id:' + record.id + ', transactionType:' + record.transactionType);
    }
});

Example: Java

package com.mockaroo.api.example;

import org.apache.commons.io.IOUtils;
import org.json.JSONArray;
import org.json.JSONObject;

import java.io.IOException;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;

public class Client {
	public static void main(String[] args) throws IOException {
		URL url = new URL("https://api.mockaroo.com/api/generate.json?key=abcd1234");
		HttpURLConnection conn = (HttpURLConnection) url.openConnection();
		conn.setDoOutput(true);
		conn.setRequestMethod("POST");
		conn.setRequestProperty("Content-Type", "application/json");

		JSONObject yearsEmployed = new JSONObject();
		yearsEmployed.put("name", "yearsEmployed");
		yearsEmployed.put("type", "Number");
		yearsEmployed.put("min", 1);
		yearsEmployed.put("max", 30);
		yearsEmployed.put("decimals", 0);

		JSONObject department = new JSONObject();
		department.put("name", "department");
		department.put("type", "Custom List");
		JSONArray values = new JSONArray();
		values.put("R+D");
		values.put("Marketing");
		values.put("HR");
		department.put("values", values);

		JSONObject dob = new JSONObject();
		dob.put("name", "dob");
		dob.put("type", "Date");
		dob.put("min", "1/1/1950");
		dob.put("max", "1/1/2000");
		dob.put("format", "%m/%d/%Y");

		JSONArray fields = new JSONArray();
		fields.put(yearsEmployed);
		fields.put(department);
		fields.put(dob);

		OutputStream os = conn.getOutputStream();
		os.write(fields.toString().getBytes());
		os.flush();

		JSONObject data = new JSONObject(IOUtils.toString(conn.getInputStream()));

		System.out.println(data.getInt("yearsEmployed"));
		System.out.println(data.getString("department"));
		System.out.println(data.getString("dob"));
	}
}