Topics

Basic Authentication

There is a three step process in identifying who’s making an API request

  1. First tries to identify an account through the domain.
  2. Then tries to match the auth_key in the request to a list of authentication keys enabled for the domain of the account.
  3. Finally, it tries to identify the user of that auth_key. If it cannot identify it, it’ll consider it an anonymous user.

The system has two types of auth_keys: public and private. Private auth_keys are defined and delivered to an authorized customer contact by the Junar team. Public auth keys can be obtained from the /developers path in the Open Data portal. All auth keys are anonymous by default, and are generated on the fly with each request. Anonymous keys have less privileges than identified users.

Authorization

If the domain is not associated to an active account, access is denied

If the auth_key is not recognized or does not belong to the account, access is denied

If the auth_key is public, it checks the referer. If it cannot identify the referer, access is denied. This feature can be configured on a need-to basis by the Junar team

If five (5) requests per seconds limit is surpassed, access is denied for one (1) second

Public auth_keys allow only for read operations

Error Handling

The Junar API uses regular HTTP responses to indicate success or failure of API requests. Following this HTTP standard, codes in the 2XX range indicate success and on the 4XX indicate errors.

  • ParseError: Data parsing error “400 Bad Request”.
  • AuthenticationFailed: Authentication error “401 Unauthenticated”
  • NotAuthenticated: Query does not contain authentication “401 Unauthenticated”
  • PermissionDenied: Access is not allowed “403 Forbidden”.
  • NotFound: Resource is not found “404 Not Found”.
  • MethodNotAllowed: There’s been a request for a method (POST, PUT, ect) that is not allowed “405 Method Not Allowed”.
  • NotAcceptable: An invalid request has been made over a data type “406 Not Acceptable”.
  • UnsupportedMediaType: An invalid file format has been attempted to upload “415 Unsupported Media Type”.
  • Throttled: The access limit has been beaten “429 Too Many Requests”.
  • ValidationError: Invalid parameters “400 Bad Request”.
  • UnexpectedError: An unexpected error. Please contact support@junar.com “500 internal Server”.

Basic Metrics

You can obtain an ordered list of basic metrics related to the performance of your open data site. You can use the order parameter to get one of the following results.

  • viewed: list of most viewed resources (hits on the portal)
  • downloaded: most downloaded resources (including API requests)
  • top: an aggregation of the two previous methods
  • last: ordered by last update.

Metadata Filters

You can retrieve data resources that fits a query parameter over title, description, or tags of the open data resource. You can also filter over a specific category by using the categories parameter, which receives any number of category_name separated by commas.

Resource Type Filtering

You can also retrieve resources of a specific type by using the resources parameter on the request, which can contain any of the following values, separated by commas.

  • dt: Datasets
  • ds: Dataviews
  • vz: Visualizations
  • db: Dashboards

On the response array there’s a type parameter which identifies the resource

GET /api/v2/resources/?auth_key=MI_AUTH_KEY&type=dt

In addition, you can search for words by using the `` query`` parameter

GET /api/v2/resources/?auth_key=MI_AUTH_KEY&query=search term

With the score value, it is possible to sort by ascending :asc or descending :desc results according to the relevance of the searched term. Relevance is defined by calculating how similar the spelling of the word found to the original search term is.

GET /api/v2/resources/?auth_key=MI_AUTH_KEY&query=search term&order=_score:asc

Full catalog queries

You can filter, order, search and paginate over the entire catalog with one query by using the following GET method

GET   /api/v2/resources.json

For instance http://cne.cloudapi.junar.com/api/v2/resources.json?auth_key=MY_AUTH_KEY&limit=2&offset=8&query=balance&order=top returns

{
    "count": 101,
    "next": "http://cne.cloudapi.junar.com/api/v2/resources.json/?auth_key=7a392227077e0efbfdb16f843fd12a09bea78210&limit=2&offset=10&order=top&query=balance",
    "previous": "http://cne.cloudapi.junar.com/api/v2/resources.json/?auth_key=7a392227077e0efbfdb16f843fd12a09bea78210&limit=2&offset=6&order=top&query=balance",
    "results": [
        {
        "result": null,
        "endpoint": "http://dataset.cne.cl/Energia_Abierta/Balances%20Energeticos/bne_2014.xls",
        "description": "Fuente: Elaborado por la División de Prospectiva y Política Energética del Ministerio de Energía ",
        "parameters": [

        ],
        "tags": [
            "consumo",
            "Sector Publico",
            "comercial",
            "residencial",
            "cpr",
            "bne 2014"
                ],
        "timestamp": 1472489817419,
        "created_at": 1449000423,
        "title": "BNE 2014 - Consumo Sector Comercial, Público, Residencial (CPR)",
        "modified_at": 1455897663,
        "category_id": "41209",
        "link": "http://datos.energiaabierta.cne.cl/dataviews/111743/bne-2014-consumo-sector-comercial-publico-residencial-cpr/",
        "user": "cne",
        "guid": "BNE-2014-CONSU-SECTO-COMER",
        "category_name": "Balance Energético",
        "type": "ds"
        },
        {
        "result": null,
        "endpoint": "http://dataset.cne.cl/Energia_Abierta/Balances%20Energeticos/bne_2014.xls",
        "description": "Fuente: Elaborado por la División de Prospectiva y Política Energética del Ministerio de Energía ",
        "parameters": [

        ],
        "tags": [
            "consumo",
            "sector industrial",
            "sector minero",
            "bne 2014"
        ],
        "timestamp": 1472049616033,
        "created_at": 1448996916,
        "title": "BNE 2014 - Consumo Sector Industrial y Minero",
        "modified_at": 1455897663,
        "category_id": "41209",
        "link": "http://datos.energiaabierta.cne.cl/dataviews/111697/bne-2014-consumo-sector-industrial-y-minero/",
        "user": "cne",
            "guid": "BNE-2014-CONSU-SECTO-INDUS",
        "category_name": "Balance Energético",
        "type": "ds"
        }
    ]
}

Version

Current API version is 2.0.

Maintenance and support for APIv1.0 related issues will not be available beginning on September, 2016. While v1.0 requests will continue to work, we strongly recommend to integrate all developments over to the current version of the API.