OpenOil API

The OpenOil API allows automated access to some of the data we have collected about the extractives industry. For example, you can use it to answer questions like “What concession blocks exist in Uganda?“, or “who holds exploration licenses in Brazil?“.

Currently, the API contains our data on Concession Areas. We plan to add more data in the future.

API Key

To use the API, you will need an API key. This is free; enter your email address in the form below, and we will send you an API key by email.

You should include your key as a GET parameter in all requests — for example building URLs like http://api.openoil.net/concession/search?apikey=oo_xxxxxxxxxxxx

Features common to all requests

The root url is http://api.openoil.net/. You can optionally specify a version number in the URL — http://api.openoil.net/v0.1. Requests which do not specify a version number will be redirected to the latest version.

You can control paging in any request:

  • page: page number of results to show. First page is 1
  • per_page: number of results to fetch

All requests should include the apikey parameter, as described above.

All responses are in JSON format.

Concessions

A Concession is the smallest area of land treated as a unit by a government, when allocating rights around natural resources.

We have collected data on concessions from 69 countries around the world, and provide it in an open format.

You can find a description of this dataset here

Naming Concessions

There is no rigorously-defined global naming scheme for concession areas. We refer to them using two elements, combined by a forward slash:

  • The country code for the country where they are located
  • The name by which the government of that country refers to the concession

For example, the ES-M-525 concession within Brazil (BR) will be referred to as BR/ES-M-525. You can find our information about it at http://api.openoil.net/concession/BR/ES-M-525?apikey=oo_xxxxxxxxxxxx.

Country codes are generally 2-letter ISO-3166 codes, which you can find listed here. However, there are exceptions, when concessions are not controlled by a globally-recognised government. For these exceptions, we use ad-hoc three-letter codes. Currently this applies only to KRG for the Kurdistan Regional Government.

Identifiers are our best understanding of how the national government refers to a concession. This is not always consistent across all our source documents. In future we may update identifiers in our API to better reflect government names. If we do so, we will retain the old names as aliases, except in the (unlikely) case of a conflict between two block names.

Getting details of a concession

To get details of a single concession, request an url like:

http://api.openoil.net/concession/BR/ES-M-525?apikey=oo_xxxxxxxxxxxxxxx

The response will look like:

{
    "api_version": 0.1,
    "result": {
        "country": "BR",
        "details": {
            "Concession\u00e1rios": "*Petrobras - 65%, Inpex - 15%, PTTEP Brasil - 20%",
            "Contrato": "BM-ES-23",
            "Observacao": "",
            "Operador": "Petrobras",
            "Vencimento1\u00ba": "20.01.2012"
        },
        "identifier": "BR/ES-M-525",
        "licensees": [
            "Petrobras",
            "PTTEP Brasil",
            "Inpex"
        ],
        "name": "ES-M-525",
        "retrieved_date": "2014-08-12",
        "source_date": "2014-01-12",
        "source_document": "http://www.anp.gov.br/?pg=57559",
        "status": "",
        "type": "",
        "url_api": "http://api.openoil.net/concession/BR/ES-M-525",
        "url_wiki": "http://repository.openoil.net/wiki/Brazil"
    }
}

Data provided here includes:

  • identifier: our primary way of referring to this concession
  • url_api: the URL at which to get our most detailed structured information about this concession
  • url_wiki: A link to a page on the openoil wiki with information on the concession. This may be a page specific to this concession area, or a general page covering the country it is in
  • details: A dictionary of all other information we have about the concession. This will vary wildly depending on our data source
  • type: Broad geographical classification of the concession area. e.g. ‘offshore’
  • status: Condition of extractive activity in the concession area. e.g. ‘exploration’.

Searching Concessions

To get data on all concessions, send a request to:

http://api.openoil.net/v0.1/concession/search?apikey=oo_xxxxxxxxx

Which results in

   { "api_version": 0.1, "page": 1, "per_page": 100, "result_count": 18038, "results": [ { "country": "NZ", "further_info": "Release Area: 15GSC-R1, Block Offer Year: 2015", "licensees": "", "name": "169E49/6", "retrieved_date": "2015-02-11", "source_date": "", "source_document": "http://data.nzpam.govt.nz/permitwebmaps?commodity=petroleum", "status": "", "type": "" }, { "country": "NZ", "further_info": "Release Area: 15GSC-R1, Block Offer Year: 2015", "licensees": "", "name": "169E49/7", "retrieved_date": "2015-02-11", "source_date": "", "source_document": "http://data.nzpam.govt.nz/permitwebmaps?commodity=petroleum", "status": "", "type": "" }, ......]} 

You can limit the results by any of:

  • country: 2-letter country code
  • licensee: Limit to concessions where this company is among the licensees
  • type: one of offshore, onshore
  • status: one of licensed, unlicensed

For example, you can find all licensed concession areas in Australia with:


http://api.openoil.net/concession/search?status=licensed&country=AU&apikey=oo_xxxxxxxxx

Which results in:

   { "api_version": 0.1, "page": 1, "per_page": 100, "result_count": 8408, "results": [ { "country": "AU", "further_info": "Title Number: WA-420-P, Title Type: Exploration Permit, Status: Active, Offshore Area: Western Australia, Basin: Bonaparte Basin", "licensees": "Goldsborough Energy Pty Ltd", "name": "1", "retrieved_date": "2014-08-12", "source_date": "2014-01-12", "source_document": "http://www.nopta.gov.au/_documents/neats/blocks-report-20141201.xlsx", "status": "licensed", "type": "" }, { "country": "AU", "further_info": "Title Number: WA-466-P, Title Type: Exploration Permit, Status: Active, Offshore Area: Western Australia, Basin: Roebuck Basin", "licensees": "Woodside Energy Ltd.", "name": "1", "retrieved_date": "2014-08-12", "source_date": "2014-01-12", "source_document": "http://www.nopta.gov.au/_documents/neats/blocks-report-20141201.xlsx", "status": "licensed", "type": "" }, ...... }] 

Data Sources

The data, and its sources, are described in detail on the OpenOil wiki.

License

This data is provided under a Creative Commons Attribution-ShareAlike license. This means you are free to adapt and share our data, but only if you credit OpenOil and distribute your modifications under a compatible license.

Comments are closed.