How do I use the WellDatabase API?

This describes the resources that make up the official WellDatabase REST API v2. If you have any problems or requests please contact support.

Additional Resources: 

Generate Exports

Export Documents

Data Definitions

API Help

Current Version

By default, all requests to https://app.welldatabase.com/api receive the v2 version of the REST API. We encourage you to explicitly request this version by placing it in the URL.

https://app.welldatabase.com/api/v2

Schema

All API access is over HTTPS, and accessed from https://app.welldatabase.com/api/v2. All data is sent and received as JSON, with the exception of Exports.

curl -i https://app.welldatabase.com/api/v2/wells/5499514d-2436-42cb-8bef-e681369766b9

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Content-Encoding: gzip
RateLimit-Limit: 10
RateLimit-Remaining: 9
RateLimit-Reset: 1499610155
Content-Length: 4916
Date: Sat, 01 Jul 2017 14:22:35 GMT

Blank fields are included as null instead of being omitted.

All date timestamps return in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Summary Representations

When you fetch a list of resources, the response includes a subset of the attributes for that resource. This is the “summary” representation of the resource. (Some attributes are computationally expensive for the API to provide. For performance reasons, the summary representation excludes those attributes. To obtain those attributes, fetch the “detailed” representation.)

Example: When you get a list of wells, you get the summary representation of each well. Here, we fetch a list of wells:

curl -X POST "https://app.welldatabase.com/api/v2/wells/search" -H Content-Type:application/json -H "Api-Key:YOUR API KEY" -d '{"Filters":{}}'

Detailed Representations

When you fetch an individual resource, the response typically includes all attributes for that resource. This is the “detailed” representation of the resource. (Note that authorization sometimes influences the amount of detail included in the representation.)

Example: When you get an individual well, you get the detailed representation of the well. Here, we fetch a well:

GET /wells/f530333a-ad6a-437f-a386-fd594347eb03

The documentation provides an example response for each API method. The example response illustrates all attributes that are returned by that method.

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 "https://app.welldatabase.com/api/v2/wells/5499514d-2436-42cb-8bef-e681369766b9/production?pageOffset=0&pageSize=20"

In this example, the ‘5499514d-2436-42cb-8bef-e681369766b9‘ and ‘production‘ values are provided for the id and sectionparameters in the path while pageOffset and pageSize are passed in the query string.

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 -d '{"Filters":"DateLastModified":{"Min":"1/1/2017"}},"PageOffset":"0","PageSize":"20"}' https://app.welldatabase.com/api/v2/wells/search

Client Errors

There are three possible types of client errors on API calls that receive request bodies:

1. Sending invalid JSON will result in a 400 Bad Request response. HTTP/1.1 400 Bad Request Content-Length: 20

HTTP Redirects

API v2 uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests.

Status Code	Description
301	Permanent redirection. The URI you used to make the request has been superseded by the one specified in the Location header field. This and all future requests to this resource should be directed to the new URI.
302, 307	Temporary redirection. The request should be repeated verbatim to the URI specified in the Location header field but clients should continue to use the original URI for future requests.

Other redirection status codes may be used in accordance with the HTTP 1.1 spec.

HTTP Verbs

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

Verb	Description
HEAD	Can be issued against any resource to get just the HTTP header info.
GET	Used for retrieving resources.
POST	Used for creating resources.
PATCH	Not supported
PUT	Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETE	Used for deleting resources.

Authentication

There is one way to authenticate through WellDatabase API v2. Requests that require authentication will return 404 Not Found, instead of 403 Forbidden, in some places. This is to prevent the accidental leakage of private information to unauthorized users.

API Key (sent in a header)

curl -H "Api-Key: API-KEY" https://app.welldatabase.com/api/v2/wells/5499514d-2436-42cb-8bef-e681369766b9

Failed login limit

Authenticating with invalid credentials will return 401 Unauthorized:

curl -i https://app.welldatabase.com/api/v2/wells/search
HTTP/1.1 401 Unauthorized

{
  "message": "Please login, or provide a valid api key"
}

Pagination

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

curl "Api-Key: API-KEY" 'https://app.welldatabase.com/api/v2/wells/5499514d-2436-42cb-8bef-e681369766b9/production?pageOffset=0&pageSize=20' 

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

Rate Limit

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

curl -i -H "Api-Key: API-KEY" "https://app.welldatabase.com/api/v2/wells/5499514d-2436-42cb-8bef-e681369766b9"
HTTP/1.1 200 OK
Date: Sat, 08 Jul 2017 15:13:35 GMT
RateLimit-Limit: 109
RateLimit-Remaining: 5
RateLimit-Reset: 1501941818

Header Name	Description
RateLimit-Limit	The maximum number of requests you’re permitted to make per hour.
RateLimit-Remaining	The number of requests remaining in the current rate limit window.
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(1501941818 * 1000)
// => Sat Aug 05 2017 09:03:38 GMT-0500 (Central Daylight Time)

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

HTTP/1.1 429 Too Many requests
Date: Sat, 08 Jul 2017 15:13:35 GMT
RateLimit-Limit: 10
RateLimit-Remaining: 0
RateLimit-Reset: 1501941818

{
   "message": "No Requests Available For Specified Token. API access will reset to 10 at: 8/5/2017 9:03:38 AM"
}

Concurrent Rate Limit

To protect the quality of service on WellDatabase, additional rate limits may apply to some actions. For example: rapidly creating content, polling aggressively instead of using webhooks, making API calls with a high concurrency, or repeatedly requesting data that is computationally expensive may result in abuse rate limiting. Requests are limited to 1 per second

Abuse rate limits are not intended to interfere with legitimate use of the API. Your normal rate limits should be the only limit you target.

If your application triggers this rate limit, you’ll receive an informative response:

HTTP/1.1 429 Too Many requests
Content-Type: application/json; charset=utf-8
Connection: close

{
  "message": "Request Rate Limit Hit, Please Reduce the Number of Requests Per Second."
}

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 WellDatabase 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: Cool-WellDatabase-App

If you provide an invalid User-Agent header, you will receive a 403 Forbidden response:

curl -iH 'User-Agent: ' https://app.welldatabase.com/api/v2/wells/5499514d-2436-42cb-8bef-e681369766b9
HTTP/1.0 403 Forbidden
Content-Type: application/json; charset=utf-8
Connection: close

{
  "message": "User-Agent Required."
}

Cross Origin Resource Sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. You can read the CORS W3C Recommendation, or this intro from the HTML 5 Security Guide.

Here’s a sample request sent from a browser hitting http://example.com:

curl -i -H "Api-Key: API-KEY" https://app.welldatabase.com/api/v2/wells/5499514d-2436-42cb-8bef-e681369766b9 -H "Origin: http://example.com"
HTTP/1.1 302 Found
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, X-WellDatabase-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval

This is what the CORS preflight request looks like:

curl -i https://app.welldatabase.com/api/v2 -H "Origin: http://example.com" -X OPTIONS
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Credentials: true