The WellDatabase API enables users to generate large data exports using dedicated endpoints. Here is a look at how to use them.
Export Formats
The WellDatabase API v2 supports generating exports in a variety of formats. If ExportFormat is excluded, or passed as an empty string, the endpoint will generate a CSV. Each export is zipped and returned as an attachment in the response. Export limits, types, and fields are based on authorization level.
To specify the export format specify the ExportFormat property in the request.
Valid Values:
| Value to Send | Result |
|---|---|
| csv | Exports data to a csv file. |
| xls | Exports data to a xls workbook |
| xlsx | Exports data to a xlsx workbook |
| shp | Exports data to a Shapefile |
CSV Exports
curl -i -H "Api-Key: API-KEY" 'https://app.welldatabase.com/api/v2/wells/export' -H 'Content-Type: application/json' -d'{"ExportFormat":"CSV","Filters":{"InfinityIds":["5499514d-2436-42cb-8bef-e681369766b9"]}}'
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/octet-stream
RateLimit-Limit: 10
RateLimit-Remaining: 8
RateLimit-Reset: 1501010038
Content-Length: 676
Content-Disposition: attachment; filename=WellDatabaseExport-20170871309.zip
Date: Sat, 08 Jul 2017 18:10:03 GMT
XLS Exports
curl -i -H "Api-Key: API-KEY" 'https://app.welldatabase.com/api/v2/wells/export' -H 'Content-Type: application/json' -d'{"ExportFormat":"XLS","Filters":{"InfinityIds":["5499514d-2436-42cb-8bef-e681369766b9"]}}'
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/octet-stream
RateLimit-Limit: 10
RateLimit-Remaining: 9
RateLimit-Reset: 1501010038
Content-Length: 1902
Content-Disposition: attachment; filename=WellDatabaseExport-20170871304.zip
Date: Sat, 08 Jul 2017 18:05:30 GMT
Filters
The WellDatabase API v2 supports filtering exports. Each data type may provide filters unique to that data type. All endpoints support a common set of filers:
| Filter Name | Description |
|---|---|
| DateCreated | This will limit the results to records created on or after the min date specified, and before the max specified date. Time can be specified as AM/PM or 24 hour formats. If AM/PM are omitted, 24 hour time is assumed.
{ DateCreated: { Min: '01/01/2017 12:00:00', Max: '03/01/2017 12:00:00'} }
|
| DateLastModified |
This will limit the results to records modified on or after the min date specified, and before the max specified date. Time can be specified using AM/PM or 24 hour formats. If AM/PM are omitted, 24 hour time is assumed. The system sets DateLastModified is set to the DateCreated when a record is created. { DateLastModified: { Min: '01/01/2017 12:00:00', Max: '03/01/2017 12:00:00' } }
|
| DateCatalogued |
This will limit the results to records Catalogued in our export system on or after the min date specified, and before the max specified date. Time can be specified using AM/PM or 24 hour formats. If AM/PM are omitted, 24 hour time is assumed. This is the date that changed, or updated records are loaded to the export system. It is the best field to use to calculate deltas. { DateCatalogued: { Min: '01/01/2017 12:00:00', Max: '03/01/2017 12:00:00' } }
|
| InfinityIds |
This will filter any record to those associated to a specific set of wells using the WellDatabase globally unique identifier. { InfinityIds:[“5499514d-2436-42cb-8bef-e681369766b9”] }
|
| SimpleIds |
This will filter any record to those associated to a specific set of wells using the numeric identifier. { SimpleIds:[100,200,300] }
|
Fields
The WellDatabase API v2 supports exporting a subset of fields. By default the endpoint will include ALL fields for a given data type. Available fields are based on authorization level. If a requested field is not available to the current authorization level, it will be ignored.
Example: Return only Id, and DateCreated from the api.
curl -i -H "Api-Key: API-KEY" 'https://app.welldatabase.com/api/v2/wells/export' -H 'Content-Type: application/json' -d '{"Fields": ["Id","DateCreated"],"Filters":{"InfinityIds":["5499514d-2436-42cb-8bef-e681369766b9"]}}'
Response
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/octet-stream
RateLimit-Limit: 10
RateLimit-Remaining: 7
RateLimit-Reset: 1501010038
Content-Length: 274
Content-Disposition: attachment; filename=WellDatabaseExport-20170871342.zip
Date: Sat, 08 Jul 2017 18:43:10 GMT
Settings
The WellDatabase API v2 supports a few export settings which change how the data in the export is returned.
Date Settings
By default the WellDatabase API v2 will return dates in a mm/dd/yyyy hh:mm:ss format. Using the DateFormat setting you can force it to return ISO 8601 dates.
Example: Set Date format to ISO 8601
curl -i -H "Api-Key: API-KEY" 'https://app.welldatabase.com/api/v2/wells/export' -H 'Content-Type: application/json' -d '{"Filters":{"InfinityIds":["5499514d-2436-42cb-8bef-e681369766b9"]}, "Settings":[{"Key":"DateFormat","Value":"ISO_8601"}]}'
Response
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/octet-stream
RateLimit-Limit: 10
RateLimit-Remaining: 6
RateLimit-Reset: 1501010038
Content-Length: 677
Content-Disposition: attachment; filename=WellDatabaseExport-20170871353.zip
Date: Sat, 08 Jul 2017 18:53:49 GMT
Record Limit Setting
By default the WellDatabase API v2 will return the maximum number of records available at the current authorization level. To reduce the number of results returned in the export use the limit setting. If a limit greater than your authorization level is requested, the server will return an error indicating you need to reduce the requested limit.
Example: Take only the first 10 records
curl -i -H "Api-Key: API-KEY" 'https://app.welldatabase.com/api/v2/wells/export' -H 'Content-Type: application/json' -d '{"Filters":{}, "Settings":[{"Key":"Limit","Value":10}]}'
Response
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/octet-stream
RateLimit-Limit: 10
RateLimit-Remaining: 6
RateLimit-Reset: 1501010038
Content-Length: 1945
Content-Disposition: attachment; filename=WellDatabaseExport-20170871357.zip
Date: Sat, 08 Jul 2017 18:58:17 GMT
Record Paging
By default the WellDatabase API v2 will return records starting from the first result, and continuing until it hits the export limit. Using the skip setting, WellDatabase will skip the first x specified records, and then return the number specified by the export limit. Use Skip, and Limit to implement paging in the exports.
Example: Skip the first 10 records
curl -i -H "Api-Key: API-KEY" 'https://app.welldatabase.com/api/v2/wells/export' -H 'Content-Type: application/json' -d '{"Filters":{}, "Settings":[{"Key":"Skip","Value":10}]}'
Example: Skip the first 10 records, return 10 records
curl -i -H "Api-Key: API-KEY" 'https://app.welldatabase.com/api/v2/wells/export' -H 'Content-Type: application/json' -d '{"Filters":{}, "Settings":[{"Key":"Skip","Value":10},{"Key":"Limit","Value":10}]}'
Line Ending Setting
By default the WellDatabase API v2 will use a standard \r\n line ending for CSVs. Using this setting you can change the new line character used when generating CSVs. The api's only restriction is on string length, the api will truncate the requested line ending to 10 characters max.
Example: Tell the api to CSVs using ^^` as the new line character.
curl -i -H "Api-Key: API-KEY" 'https://app.welldatabase.com/api/v2/wells/export' -H 'Content-Type: application/json' -d '{"Filters":{}, "Settings":[{"Key":"CustomNewLine","Value":"^^`"}]}'
Force Quote All Fields Setting
By default the WellDatabase API v2 will only quote fields when needed during CSV creation. You can force all fields to be quoted using this setting.
Example: Tell the api to export all fields as quoted
curl -i -H "Api-Key: API-KEY" 'https://app.welldatabase.com/api/v2/wells/export' -H 'Content-Type: application/json' -d '{"Filters":{}, "Settings":[{"Key":"QuoteAllFields","Value":"1"}]}'