Overview

This describes the resources that make up the official REST API v1. If you have any problems or requests, please contact us.

Schema

All API access is over HTTPS, and accessed from https://ezvenue.app/api. All data is sent and received as JSON.

curl -i https://ezvenue.app/api

Blank fields are included as null instead of being omitted.
All timestamps return in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Authentication

The API uses access_token to authorize. Requests that requires authentication will return 403 Forbidden.

Basic Authentication

curl -u "username:access_token" https://ezvenue.app/api

Sent through header

Passing a base 64 encoded username:access_token through the request header.

curl -H "Authorization: Basic XXXXXX" https://ezvenue.app/api

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

curl -i -H "Authorization: Basic XXXXXX" https://ezvenue.app/api/lookups?since=today

For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of application/json:

curl -i -H "Authorization: Basic XXXXXX" -d '{"ref":"12345","address":"Somewhere in the middle, TX 1234"}' https://ezvenue.app/api/lookups

HTTP verbs

Where possible, API v1 strives to use appropriate HTTP verbs for each action.

Verb	Description
`GET`	Used for retrieving resources.
`POST`	Used for creating resources.
`PATCH`	Used for updating resources with partial JSON data. For instance, an Order resource has `notes` attribute. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept `POST` requests.
`PUT`	Used for replacing resources or collections.
`DELETE`	Used for deleting resources.

Pagination

Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 100 with the ?per_page parameter. Note that for technical reasons not all endpoints respect the ?per_page parameter.

curl 'https://ezvenue.app/api/lookups?page=2&per_page=100'

Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

Link header

Note: It's important to form calls with Link header values instead of constructing your own URLs.

The Link header includes pagination information:

Link: <https://ezvenue.app/lookups?page=3&per_page=100>; rel="next",
  <https://ezvenue.app/lookups?page=50&per_page=100>; rel="last"

The example includes a line break for readability.

This Link response header contains one or more Hypermedia link relations, some of which may require expansion as URI templates.

The possible rel values are:

Name	Description
`next`	The link relation for the immediate next page of results.
`last`	The link relation for the last page of results.
`first`	The link relation for the first page of results.
`prev`	The link relation for the immediate previous page of results.

Rate limiting

For API requests using Basic Authentication, you can make up to 5000 requests per hour, per access_token.

ALL requests are authenticated.

The returned HTTP headers of any API request show your current rate limit status:

curl -i https://ezvenue.app/lookups/:id
HTTP/1.2 200 OK
Date: Mon, 01 Jul 2019 17:27:06 GMT
Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 3200
X-RateLimit-Reset: 1562003273

Header Name	Description
`X-RateLimit-Limit`	The maximum number of requests you're permitted to make per hour.
`X-RateLimit-Remaining`	The number of requests remaining in the current rate limit window.
`X-RateLimit-Reset`	The time at which the current rate limit window resets in UTC epoch seconds.

If you need the time in a different format, any modern programming language can get the job done. For example, if you open up the console on your web browser, you can easily get the reset time as a JavaScript Date object.

new Date(1562003273 * 1000)
// => Mon Jul 01 2019 13:47:53 GMT-0400 (EDT)

If you exceed the rate limit, an error response returns:

HTTP/1.2 403 Forbidden
Date: Tue, 20 Aug 2019 14:50:41 GMT
Status: 403 Forbidden
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1377013266
{
   "message": "API rate limit exceeded",
   "documentation_url": "https://ezvenue.app/docs/developer#rate-limiting"
}

Staying within the rate limit

If you exceed your rate limit using Basic Authentication, you can likely fix the issue by caching API responses and using conditional requests.

User agent required

All API requests MUST include a valid User-Agent header. Requests with no User-Agent header will be rejected. We request that you use your EZ Venue username, or the name of your application, for the User-Agent header value. This allows us to contact you if there are problems.

Here's an example:

User-Agent: My-Awesome-App

cURL sends a valid User-Agent header by default. If you provide an invalid User-Agent header via cURL (or via an alternative client), you will receive a 403 Forbidden response:

HTTP/1.2 403 Forbidden
Date: Tue, 20 Aug 2019 14:50:41 GMT
Status: 403 Forbidden
{
   "message": "Please make sure your request has a User-Agent header",
   "documentation_url": "https://ezvenue.app/docs/developer#user-agent-required"
}

Lookups

The lookup resource.

List lookups

List the available lookups of the client.

GET /lookups

Parameters

Name	Type	Description
`sort`	`string`	What to sort results by. Can be either `created`, `updated`. Default: `created`
`direction`	`string`	The direction of the sort. Can be either `asc` or `desc`. Default: `desc`
`since`	`string`	Only lookups updated at or after this time are returned. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

Response

HTTP/1.2 200 OK
Link: <https://ezvenue.app/api/lookups?page=2>; rel="next",
    <https://ezvenue.app/api/lookups?page=3>; rel="last"
[
    {
        "id": 3759,
        "batch_id": 159,
        "ref": "11990",
        "result": 0,
        "amount": 0,
        "street_1": "916 Nelson Street",
        "street_2": null,
        "city": "Elrama",
        "state": "IA",
        "zip": "32647",
        "lat": 40.2520683,
        "lng": -79.9249957,
        "notes": null,
        "completed_at": "2019-06-13T16:58:04+0800",
        "created_at": "2019-06-14T00:57:10+0800",
        "formatted_address": "916 Nelson Street, Elrama, IA 32647",
        "results": []
    },
    {
        "id": 3758,
        "batch_id": 159,
        "ref": "11988",
        "result": 1,
        "amount": 0,
        "street_1": "139 Miami Court",
        "street_2": null,
        "city": "Allamuchy",
        "state": "UT",
        "zip": "46560",
        "lat": 25.7746226,
        "lng": -80.1949355,
        "notes": null,
        "completed_at": "2019-06-13T16:58:04+0800",
        "created_at": "2019-06-14T00:57:10+0800",
        "formatted_address": "139 Miami Court, Allamuchy, UT 46560",
        "results": [
            {
                "id": 1357,
                "venue_id": 17233,
                "area_id": 1798,
                "venue_county": "Miami-Dade",
                "venue_precinct": "Small Claims",
                "venue_efile": 0,
                "created_at": "2019-06-14T00:58:04+0800"
            }
        ]
    }
    ...
]

Get a single lookup

Get a single lookup by if you secured an id.

GET /lookups/:id

Response

Status: 200 OK
{
    "id": 3738,
    "batch_id": 159,
    "ref": "11965",
    "result": 1,
    "amount": 0,
    "street_1": "9617 E Veum Plains Squares",
    "street_2": null,
    "city": "South Nolanburgh",
    "state": "TX",
    "zip": "64039",
    "lat": 31.9685988,
    "lng": -99.9018131,
    "notes": null,
    "completed_at": "2019-06-13T16:57:11+0800",
    "created_at": "2019-06-14T00:57:10+0800",
    "formatted_address": "9617 E Veum Plains Squares, South Nolanburgh, TX 64039",
    "results": [
        {
            "id": 1352,
            "venue_id": 2642,
            "area_id": 2025,
            "venue_county": "Runnels",
            "venue_precinct": "2",
            "venue_efile": 0,
            "created_at": "2019-06-14T00:57:11+0800"
        }
    ]
}

Create a single lookup

Create a lookup through a POST request with the required fields.

The address parameter can either be an object or a string. For the object type, street_1, city, state and zip fields are required. You can provide the latitude and the longitude value to the address parameter if available. For string type, pass the formatted address.

POST /lookups

Parameters

Name	Type	Description
`ref`	`string`	Client custom reference number.
`address`	`object` `string`	The address to search for.
`amount`	`int`	The suit amount for the lookup.
`mapper_key`	`string`	The key used to access the associated court venue mappings.

Response

Status: 201 Created
Location: https://ezvenue.app/api/lookups/3739
{
    "id": 3739,
    "batch_id": null,
    "ref": "11966",
    "result": 0,
    "amount": 0,
    "street_1": "7586 W Howe Spur Alley",
    "street_2": null,
    "city": "New Aglae",
    "state": "DE",
    "zip": "27855",
    "lat": 36.4306716,
    "lng": -77.067959,
    "notes": null,
    "completed_at": "2019-06-13T16:57:18+0800",
    "created_at": "2019-06-14T00:57:10+0800",
    "formatted_address": "7586 W Howe Spur Alley, New Aglae, DE 27855",
    "results": []
}

Batch lookup

Lookups created by batch are subject to Address Cleansing. To skip this step, you can supply the latitude and longitude for each address row.

Batch lookup requires the form data content type header:

Content-Type: multipart/form-data

The API supports comma/pipe delimited files (.csv), .xlsx or similar data files.

You can also supply the mapping parameter to map the columns. The API will try to detect the correct mappings if not supplied.

POST /lookups/batches

Parameters

Name	Type	Description
`mapping`	`object`	The mapping object
`file`	`@file`	The uploaded file.
`mapper_key`	`string`	The key used to access the associated court venue mappings.

Response

Status: 201 Created
Location: https://ezvenue.app/api/lookups/batches/161
{
    "id": 161,
    "processed": 2,
    "exceptions": [],
    "filename": "BATCH_bg9ylFQ777GYLdnk.csv",
    "mapping": "",
    "completed_at": null,
    "created_at": "2019-06-15T16:23:28+0800"
}

Get a single batch

You can retrieve a single batch that was previously created.

GET /lookups/batches/:id

Response

Status: 200 OK
{
    "id": 159,
    "token": "b83d308c7b23c8b8bd407892d3d230b67cbd68ffaa9e5bccd9b0379b71728d9a",
    "filename": "REQUEST_20190614_zPo3m02bFPA8ZSYw.csv",
    "completed_at": "2019-06-13T16:58:04+0800",
    "created_at": "2019-06-14T00:57:10+0800",
    "actor_user": {
        "id": 1,
        "username": "lodev09",
        "created_at": "2019-01-29T01:11:56+0800",
        "name": "Jovanni Lo",
        "avatar_url": "https://www.gravatar.com/avatar/b6b307d6680bb64cb6f1fd99a9fe43fc?s=48&d=identicon&r=g"
    },
    "mapping": null
}

List items from batch

List the items that were created for a batch.

GET /lookups/batches/:id/items

Response

Status: 200 OK
[
    {
        "id": 3737,
        "batch_id": 159,
        "ref": "11964",
        "result": 0,
        "amount": 0,
        "street_1": "742 Varet Street",
        "street_2": null,
        "city": "Garnet",
        "state": "KS",
        "zip": "40373",
        "lat": 40.703372,
        "lng": -73.937648,
        "notes": null,
        "completed_at": "2019-06-13T16:57:11+0800",
        "created_at": "2019-06-14T00:57:10+0800",
        "formatted_address": "742 Varet Street, Garnet, KS 40373",
        "results": []
    },
    {
        "id": 3738,
        "batch_id": 159,
        "ref": "11965",
        "result": 1,
        "amount": 0,
        "street_1": "9617 E Veum Plains Squares",
        "street_2": null,
        "city": "South Nolanburgh",
        "state": "TX",
        "zip": "64039",
        "lat": 31.9685988,
        "lng": -99.9018131,
        "notes": null,
        "completed_at": "2019-06-13T16:57:11+0800",
        "created_at": "2019-06-14T00:57:10+0800",
        "formatted_address": "9617 E Veum Plains Squares, South Nolanburgh, TX 64039",
        "results": [
            {
                "id": 1352,
                "venue_id": 2642,
                "area_id": 2025,
                "venue_county": "Runnels",
                "venue_precinct": "2",
                "venue_efile": 0,
                "created_at": "2019-06-14T00:57:11+0800"
            }
        ]
    }
    ...
]

PHP SDK

EZ Venue API v1 is also available in PHP. You can download it here.

Developer / API docs

Overview

Schema

Authentication

Basic Authentication

Sent through header

Parameters

HTTP verbs

Pagination

Link header

Rate limiting

Staying within the rate limit

User agent required

Lookups

List lookups

Get a single lookup

Create a single lookup

Batch lookup

Get a single batch

List items from batch

PHP SDK