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.

Sign up to obtain an 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.

PlanLimit
Free200 requests/day
Silver1,000,000 records/day
Gold10,000,000 records/day

Generate API

The Mockaroo Generate API has the following methods:

GET /api/types

GET  https://api.mockaroo.com/api/types?key=(your API key)

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

  • name (string) - The name of the type
  • parameters (Object[]) - Additional options that can be specified. Each object has the following keys:
    • 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

POST  https://api.mockaroo.com/api/datasets/:name?key=(your API key)&filename=(file 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

POST  https://api.mockaroo.com/api/datasets?key=(your API key)&name=(dataset name)&filename=(file 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)

POST  https://api.mockaroo.com/api/generate(.format)?key=(your API key)

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:

FormatURLDescription
jsonhttps://api.mockaroo.com/api/generate.jsonResults are returned as a json object. Results will be returned as an array if the "size" query string parameter is greater than 1.
csvhttps://api.mockaroo.com/api/generate.csvComma separated values. The first row will contain the field names. Subsequent rows will contain the generated data values.
txthttps://api.mockaroo.com/api/generate.txtTab-separated values. The first row will contain the field names. Subsequent rows will contain the generated data values.
customhttps://api.mockaroo.com/api/generate.customSpecify a custom delimiter using the "delimiter" query parameter. Specify a custom quote character using the "quote_char" query parameter. The first row will contain the field names. Subsequent rows will contain the generated data values.
sqlhttps://api.mockaroo.com/api/generate.sqlResults are returned as SQL insert statements.
xmlhttps://api.mockaroo.com/api/generate.xmlResults are returned as an xml document.

Query String Parameters

ParameterTypeDescription
keystring (required)Your api key
callbackstring (optional)The name of a javascript function to call in the response. If specified, the response will be in jsonp format.
countinteger (optional)The number of rows to generate. Defaults to 1, or if a saved schema is used, the number of rows specified on the saved schema. When json format is requested, the result will be an object when size = 1, an array when size > 1. Free accounts are limited to 5000 records per download.
arrayboolean (optional)When generating json data, Mockaroo will return an array when count > 1 and an object when count is 1. To always return an array, specify a value of "true" for this parameter. Defaults to false.
include_nullsboolean (optional)When generating json data, Mockaroo will omit keys with null values if this is set to false.
include_headerboolean (optional)Only relevant for csv format. Set to false to omit the header row. Defaults to true.
schemastring (optional)The name of a saved schema to use. If this parameter is not specified, you must define the fields in the request body as specified below.
root_elementstring (optional, only used when format is xml)The name to give to the root element in the document
record_elementstring (optional, only used when format is xml)The name to give to each element representing a record
delimitercharacter (optional, only used when format is custom)The character to use as a column separator
quote_charcharacter (optional, only used when format is custom)The character to use when enclosing values. Defaults to double-quote.
line_endingstring (optional, only used when format is custom)"unix" or "windows"
bomboolean (optional, only used when format is csv, txt, or custom)true to include the BOM (byte order mark). Defaults to false.
fieldsjson array (optional)A json array of field specifications. See request body below for details. When using JSONP, you must specify fields using this URL parameter as JSONP does not allow the caller to pass data in the body of the request.

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:

ParameterTypeDefaultDescription
namestringThe name of the field. When using json format, you can use "." in field names to generate nested json objects, brackets to generate arrays. More information...
percentBlankinteger0An integer between 0 and 100 that determines what percent of the generated values will be null
formulastring0Alters the generated value using Mockaroo formula syntax. Use this to refer to the value of this field.
typestringThe name of one of Mockaroo's types (see below)

Types

The following values can be used for the type parameter:

Client Libraries

There are several client libraries for the Mockaroo API:

Node.js

C#

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

This example uses the official npm module for Mockaroo.

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"));
    }
}