NAV Navigation
Logo
shell php

Introduction

Welcome to the Erin's List API! You can use our API to access API endpoints, which allows you to submit and search incidents electronically.

We have language bindings in Shell, PHP, and Javascript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Schema

All API access is over HTTPS, and accessed from the https://www.erinslist.us/api. All data is sent and received as JSON.

A sample request to GET incidents from a given address would look something like this:

GET https://www.erinslist.us/api/incidents

Authentication

# With shell, you can also pass the key pair directly using the -u switch
curl "https://www.erinslist.us/api/incidents?address=some+address+TX+1234"
  -u client_key:secret_key
// create a new instance of the API client given the api_key and secret_key
$client = new ERLClient($api_key, $secret_key);
$incidents = $client->get_incidents('some address TX 1234');

We use API keys and a Secret Key to allow access to the API. Register an account and request for an API key here. Follow instructions on how to secure your own access.

The API expects an Authorization header with base64 encoded api_key:secret_key pair to be included in all API requests. It should look something like this:

Authorization: Basic enlZQkdxcEdyMU1BbjVYSWIyeg==

Endpoints

Get Incidents

curl "https://www.erinslist.us/api/incidents?address=some+address+TX+1234"
  -u client_key:secret_key
$client = new ERLClient($api_key, $secret_key);
$incidents = $client->get_incidents('some address TX 1234');

Status: 200 OK

[
  {
      "id": 787,
      "address": "3239 110th St, East Elmhurst, NY, 11369",
      "lat": 3239,
      "lng": 10000,
      "notes": "Someone with a gun is pointing at me while attempting :(",
      "reported_by": "Jovanni",
      "reported_at": "2017-06-23T09:57:31Z"
  },
  {
      "id": 789,
      "address": "123 something address 1234, TX, 39349",
      "lat": 3239,
      "lng": 10000,
      "notes": "Something happened here as well.",
      "reported_by": "Jovanni",
      "reported_at": "2017-06-23T09:57:31Z"
  }
]

Get incidents based on the given address and radius.

GET https://www.erinslist.us/api/incidents

Parameters

Parameter Type Description
address string Required. the base address that we are getting incidents from. Can be a lat, long format e.g. 126.2030, -2.030344
radius string the radius in foot. Default: 1000
sort string What to sort results by. Can be either created, radius, reporter. Default: created
direction string The direction of the sort. Can be either asc or desc. Default: desc
since string Only incidents created at or after this time are returned. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

Get Single Incident

curl "https://www.erinslist.us/api/incidents/1293"
  -u client_key:secret_key
$client = new ERLClient($api_key, $secret_key);
$incidents = $client->get_incident(1293);

Status: 200 OK

{
    "id": 1293,
    "address": "1293 Address somewhere in the road, OK, 21442",
    "lat": 3239,
    "lng": 10000,
    "notes": "Something happened here as well.",
    "reported_by": "Jovanni",
    "reported_at": "2017-06-23T09:57:31Z"
}

Get a single incident by identifier

GET https://www.erinslist.us/api/incidents/:id

Parameters

Parameter Type Description
id string Required. The incident identifier

Report Incident

# Passing -d in shell will post a request
curl "https://www.erinslist.us/api/incidents"
  -d '{"address":"3239 110th St, East Elmhurst, NY, 11369","notes":"Something happened here as well.","reporter":"Jovanni","reporter_email":"jovanni.lo@ezmessenger.com"}'
  -u client_key:secret_key
$client = new ERLClient($api_key, $secret_key);

$data = array(
  'address' => '3239 110th St, East Elmhurst, NY, 11369',
  'notes' => 'Something happened here as well.',
  'reporter' => 'Jovanni'
  'reporter_email' => 'jovanni.lo@ezmessenger.com'
);
$incidents = $client->report_incident($data);

Status: 201 Created

{
    "id": 787,
    "address": "3239 110th St, East Elmhurst, NY, 11369",
    "lat": 3239,
    "lng": 10000,
    "notes": "Something happened here as well.",
    "reported_by": "Jovanni",
    "reported_at": "2017-06-23T09:57:31Z"
}

Report an incident to Erin's List

POST https://www.erinslist.us/api/incidents

Parameters

Parameter Type Description
address string Required. the base address that we are getting incidents from. Can be a lat, long format e.g. 126.2030, -2.030344
notes string Required. Incident notes/description
lat float Lattitude. If omitted, API will try to geocode the given address
lng float Longitude. If omitted, API will try to geocode the given address
reporter string The name of the reporter
reporter_email string The email of the report and will receive the verification email sent by erinslist

Evaluate an Address

# Passing -d in shell will post a request
curl "https://www.erinslist.us/api/evaluate"
  -d '{"address":"3239 110th St, East Elmhurst, NY, 11369"}'
  -u client_key:secret_key
$client = new ERLClient($api_key, $secret_key);

$data = array(
  'address' => '3239 110th St, East Elmhurst, NY, 11369'
);
$incidents = $client->evaluate($data);

Status: 200 OK

{
    "radius": 1000,
    "address": "3239 110th St, East Elmhurst, NY, 11369",
    "evaluation": "No incidents found from within 0.9mi radius. Please report if you find this inaccurate.",
    "incidents": []
}

Auatomatically evaluates a given address - dangarous or safe.

POST https://www.erinslist.us/api/evaluate

Parameters

Parameter Type Description
address string Required. the base address that we are getting incidents from. Can be a lat, long format e.g. 126.2030, -2.030344
lat float Lattitude. If omitted, API will try to geocode the given address
lng float Longitude. If omitted, API will try to geocode the given address
radius string the radius in foot. Default: 1000

Errors

The Erin's List API uses the following error codes:

Code Meaning
400 Bad Request -- Your request is malformed or not valid
401 Unauthorized -- Your API key is wrong
403 Forbidden -- The request is hidden for administrators only
404 Not Found -- The request could not be found
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.