- Batch your requests: Instead of making multiple single-UWI or single-surface
location requests, combine them into one request with multiple terms (up to 25) separated by
the
|character. - URL-encode special characters: Encode slashes (
/) as%2F, pipes (|) as%7C, and spaces as%20. - Handle multiple results: For surface location searches, be prepared to handle multiple well sites in the results array, as multiple wells can exist at the same surface location.
- Monitor your remaining balance: Check the
lookup_balancefield in the response to ensure you have sufficient lookup credits. - Handle errors gracefully: Always check the
successfield and handle any errors appropriately in your application. - Use appropriate search type: Use
uwifor precise, single-well lookups andsurfacefor location-based searches that may return multiple wells. - Normalize surface locations: While the API automatically normalizes surface locations, it's good practice to remove leading zeros and spaces in your requests for consistency.
API Documentation
The Alberta Well Finder API provides access to detailed information about all well sites in Alberta. It allows users to programmatically search for wells by their Unique Well Identifier (UWI) or surface location (LSD) and retrieve comprehensive data about each one, including status, owner, operator, and bottom hole and surface location coordinates.
Overview
Retrieve information for one or more well sites by their UWI(s) or surface location(s) using HTTP GET requests.
GET https://albertawellfinder.com/api/v3/search/API_KEY/SEARCH_TYPE/SEARCH_TERM/
API key
Authentication is required to use the API. You can find your profile's API key on your Account Profile page. To use the API, include API key in the URL path for each request. (See below for code examples.)
Search type
You can specify what part of a well site you are searching for. Currently, there are two search
types:
uwi for Unique Well Identifier searches and surface for surface location
(LSD) searches.
Search term
This is where you specify the well site(s) you are searching for. For both UWI and surface
location searches, you can provide one or more terms separated by the pipe (|)
character. For batch searches, remember to URL-encode the pipe (|) character as (%7C).
Usage
Each API key has a balance of lookup credits, which you can view and purchase more of on your Account Lookups page. One credit is deducted for each successfully retrieved well site. Failed lookups (i.e., non-existent UWIs or surface locations) do not count against your balance.
Quick start
Search by UWI
GET https://albertawellfinder.com/api/v3/search/ API_KEY /uwi/00%2F07-32-082-20W4%2F0
Here the UWI we are searching for is 00/07-32-082-20W4/0. Note that the slashes (/) in the UWI are
URL-encoded
(%2F).
Search by surface location (LSD)
GET https://albertawellfinder.com/api/v3/search/ API_KEY /surface/10-29-82-20W4
Here the surface location (LSD) we are searching for is 10-29-82-20W4. Note that if
the LSD contains spaces, they should be URL-encoded (%20).
Parameters
{uwi} or {surface}: One or
more Unique Well Identifiers or surface locations (LSDs), separated by the pipe (|)
character (required). Remember to URL-encode the pipe (|) character as (%7C) when doing batch searches. For surface locations, spaces should be URL-encoded as
%20.
Response format
The API responds with a JSON object containing the following structure:
{
"success": boolean,
"data": {
"meta": {
"start": number,
"end": number,
"queries": number,
"succeeded": number,
"failed": number,
"err": array,
"elapsed_ms": number,
"qps": number
},
"queries": [
{
"query": string,
"result": object | null // For UWI searches
"results": array // For surface location searches
}
],
"lookup_balance": number
}
} Note: For surface location searches, the response includes a results array instead of
a single result object. This is because multiple well sites can exist at the same surface
location, particularly for directional or horizontal wells.
Response fields
| Name | Description |
|---|---|
success | Indicates if the API call was successful. |
data.meta | Contains metadata about the request and response. |
data.meta.start | Timestamp of when the request processing started. |
data.meta.end | Timestamp of when the request processing ended. |
data.meta.queries | Total number of UWIs or surface locations queried. |
data.meta.succeeded | Number of queries that returned results. |
data.meta.failed | Number of queries that didn't return results. |
data.meta.err | Array of any errors encountered (usually empty). |
data.meta.elapsed_ms | Time taken to process the request in milliseconds. |
data.meta.qps | Queries per second. |
data.queries | Array of objects containing query and result data. |
data.queries[].query | The UWI or surface location that was queried. |
data.queries[].result | The well site data if found, or null if not found (UWI searches only). |
data.queries[].results | Array of well site data if found, or empty array if not found (surface location searches only). |
data.lookup_balance | The number of lookup credits remaining in your account. To view your balance and/or purchase more, visit /account/lookups. |
Well site data fields
When a well site is found, the result object (or each object in the
results array for surface location searches) contains the following fields:
| Field | Description |
|---|---|
id | Internal ID of the well site |
uwi | Unique Well Identifier |
uwi_lat | Latitude of the bottom hole location |
uwi_lng | Longitude of the bottom hole location |
surface_location | Surface location description (e.g., "6-35-1-7W4") |
surface_lat | Latitude of the surface location |
surface_lng | Longitude of the surface location |
name | Name of the well |
field_code | Code identifying the field where the well is located |
field | Name of the field where the well is located |
pool_code | Code identifying the pool associated with the well |
pool | Name of the pool associated with the well |
area_code | Code identifying the area where the well is located |
dep_code | Deposit code associated with the well |
license_number | Well license number |
license_status | Current status of the well license (e.g., "Abandoned", "Amended") |
license_issued | Date when the well license was issued |
licensee | Name of the company holding the well license |
licensee_tel | Telephone number of the licensee |
licensee_addr | Address of the licensee |
agent | Name of the agent associated with the well (if any) |
agent_tel | Telephone number of the agent (if any) |
agent_addr | Address of the agent (if any) |
operator | Name of the company operating the well (if different from licensee) |
operator_tel | Telephone number of the operator (if any) |
operator_addr | Address of the operator (if any) |
final_drill | Date when drilling was completed |
total_depth | Total depth of the well in meters |
status_code | Code representing the current status of the well |
fluid | Numeric code representing the type of fluid in the well |
mode | Numeric code representing the operational mode of the well |
type | Numeric code representing the type of well |
structure | Numeric code representing the well structure |
status_date | Date when the well status was last updated |
dn_licensee_name | Display name of the licensee |
dn_agent_name | Display name of the agent (if any) |
dn_operator_name | Display name of the operator (if any) |
dn_field_name | Display name of the field |
dn_pool_name | Display name of the pool |
dn_geological_name | Display name of the geological formation |
Single UWI search
Request
GET https://albertawellfinder.com/api/v3/search/API_KEY/uwi/00%2F07-32-082-20W4%2F0
Response
{
"success": true,
"data": {
"meta": {
"start": 1723845609901,
"end": 1723845611116,
"queries": 1,
"succeeded": 1,
"failed": 0,
"err": [],
"elapsed_ms": 1215,
"qps": "0.82"
},
"queries": [
{
"query": "00/07-32-082-20W4/0",
"result": {
"id": 774789,
"uwi": "00/07-32-082-20W4/0",
"uwi_lat": 56.149748,
"uwi_lng": -113.095373,
"surface_location": "10-29-82-20W4",
"surface_lat": 56.138909,
"surface_lng": -113.095373,
"name": "CNRES HZP17-15D SANDY 15-32-82-20",
"field_code": "998",
"field": "UNDEFINED",
"pool_code": "0000000",
"pool": null,
"area_code": "A001",
"dep_code": "0000000",
"license_number": "0212697",
"license_status": "Amended",
"license_issued": "1998-01-28",
"licensee": "Canadian Natural Resources Limited",
"licensee_tel": "(403) 517-6700",
"licensee_addr": "2100, 855 - 2 St SW, Calgary AB T2P 4J8",
"agent": null,
"agent_tel": null,
"agent_addr": null,
"operator": null,
"operator_tel": null,
"operator_addr": null,
"final_drill": "1998-02-23",
"total_depth": 1866,
"status_code": "0000000600",
"fluid": 0,
"mode": 0,
"type": 0,
"structure": 6,
"status_date": "1998-02-23",
"dn_licensee_name": "Canadian Natural Resources Limited",
"dn_agent_name": null,
"dn_operator_name": null,
"dn_field_name": "UNDEFINED",
"dn_pool_name": "",
"dn_geological_name": ""
}
}
],
"lookup_balance": 124
}
}
Multiple UWIs search
Request
GET https://albertawellfinder.com/api/v3/search/API_KEY/uwi/00%2F07-32-082-20W4%2F0%7C00%2F06-33-082-20W4%2F0
Response
{
"success": true,
"data": {
"meta": {
"start": 1723845609901,
"end": 1723845611116,
"queries": 2,
"succeeded": 2,
"failed": 0,
"err": [],
"elapsed_ms": 1215,
"qps": "1.65"
},
"queries": [
{
"query": "00/07-32-082-20W4/0",
"result": {
// Well data (same as in single UWI lookup)
}
},
{
"query": "00/06-33-082-20W4/0",
"result": {
// Well data for the second UWI
}
}
],
"lookup_balance": 122
}
}
Single surface location search
Request
GET https://albertawellfinder.com/api/v3/search/API_KEY/surface/10-29-82-20W4
Response
{
"success": true,
"data": {
"meta": {
"start": 1723845612000,
"end": 1723845613500,
"queries": 1,
"succeeded": 1,
"failed": 0,
"err": [],
"elapsed_ms": 1500,
"qps": "0.67"
},
"queries": [
{
"query": "10-29-82-20W4",
"results": [
{
"id": 774789,
"uwi": "00/07-32-082-20W4/0",
"uwi_lat": 56.149748,
"uwi_lng": -113.095373,
"surface_location": "10-29-82-20W4",
"surface_lat": 56.138909,
"surface_lng": -113.095373,
"name": "CNRES HZP17-15D SANDY 15-32-82-20",
// ... other well data fields
},
{
"id": 774790,
"uwi": "02/10-29-082-20W4/0",
"uwi_lat": 56.138909,
"uwi_lng": -113.095373,
"surface_location": "10-29-82-20W4",
"surface_lat": 56.138909,
"surface_lng": -113.095373,
"name": "CNRES VER HZ SANDY 10-29-82-20",
// ... other well data fields
}
]
}
],
"lookup_balance": 123
}
}
Multiple surface locations search
Request
GET https://albertawellfinder.com/api/v3/search/API_KEY/surface/10-29-82-20W4%7C6-35-1-7W4
Response
{
"success": true,
"data": {
"meta": {
"start": 1723845614000,
"end": 1723845616000,
"queries": 2,
"succeeded": 2,
"failed": 0,
"err": [],
"elapsed_ms": 2000,
"qps": "1.00"
},
"queries": [
{
"query": "10-29-82-20W4",
"results": [
// Array of well data for the first surface location (same as in single surface location lookup)
]
},
{
"query": "6-35-1-7W4",
"results": [
{
"id": 254325,
"uwi": "03/06-35-001-07W4/0",
"uwi_lat": 49.077516,
"uwi_lng": -110.84335,
"surface_location": "6-35-1-7W4",
"surface_lat": 49.077516,
"surface_lng": -110.84335,
"name": "PINE CLIFF COMREY 6-35-1-7",
// ... other well data fields
}
]
}
],
"lookup_balance": 121
}
}
Error responses
If an error occurs, the API will return a JSON object with an error field describing the
issue.
{
"error": "Invalid API key or insufficient balance"
} Common error responses
| Status Code | Description |
|---|---|
400 Bad Request | Invalid input parameters |
403 Forbidden | Invalid API key or insufficient balance |
500 Internal Server Error | Unexpected server error |
Best practices
Rate limiting
The API is mildly rate-limited to ensure high availability for all users. The current limit is 25
queries per request. If you exceed this limit, you'll receive a 429 Too Many Requests
response. Please contact us if you require a higher rate limit for your application.
Support and feedback
We’re constantly working to improve our API. If you have any questions, suggestions, or encounter any issues, please don’t hesitate to contact our support team at info@r2creative.ca.