CartoDB::Api

CartoDB::Api is an API library for Ruby which acts as a wrapper for CartoDB's API. All requests are built using a really simple fluid interface.

Installation

Add this line to your application's Gemfile:

gem 'cartodb-api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install cartodb-api

Usage

All requests need a configuration object. The first thing you need is to create one.

configuration = CartoDB::Api::Configuration.new

The configuration defines all the details regarding the API requests.

timeout: The request timeout in seconds (default: 30).
protocol: The protocol that will be used for requests (default: https).
version: The CartoDB API version that is going to be used (default: 1).
domain: The domain or IP where the API can be found (default: cartodb.com).
api_key: The CartoDB API key that will be used for authentication.
account: The CartoDB account from which all requests are going to be made from.

configuration.timeout = 15
configuration.protocol = 'https'
configuration.domain = 'customdomain.com'
configuration.api_key = '<Your API key>'
configuration.account = '<Account>'

If you are trying to use the API available at cartodb.com the only configuration that you need to set is the api_key and account.

To make this configuration the default for all requests:

CartoDB::Api.default_configuration = configuration

For example, you could set the default configuration in an initializer file in your Rails app (config/initializers/cartodb.rb).

configuration = CartoDB::Api:Configuration.new
configuration.api_key = ENV['CARTODB_API_KEY']
configuration.account = '<Account>'

CartoDB::Api.default_configuration = configuration

Making requests

Once you have a configuration object you can create a request:

cartodb = CartoDB::Api::Request.new(configuration)

If you have set a default configuration object there's no need of specifying one during creation:

cartodb = CartoDB::Api::Request.new

Now you can make requests to the API resources specified in CartoDB's API. Resource IDs are specified as arguments and the verbs: create, retrieve, update, and delete initiate the request.

For example to interact with the import resource:

We define the request.

cartodb = CartoDB::Api::Request.new

To get all imports.

cartodb.imports.retrieve

To retrieve a specific import.

cartodb.imports('<import id>').retrieve

You can also specify the params, headers, body and payload when calling a CRUD method. For example:

cartodb.imports.create(
    headers: {
        some_header: 'header_value'
    },
    params: {
        some_param: 'param_value'
    },
    body: body,
    payload: {
        file: Faraday::UploadIO.new('<file>', '<mime type>')
    }
)

All requests can be written inline without the need to create a Request object:

CartoDB::Api.imports.retrieve
CartoDB::Api.imports('<import id>').retrieve

Uploading files

To upload files along the request you need to pass a payload. This library uses the excellent Faraday library, thus files are sent using the Faraday::UploadIO class.

Faraday::UploadIO.new('<file>', '<mime type>')

Please note that the mime type depends on the file you are sending.

For example to create a new import from a csv file.

csv_file = Faraday::UploadIO.new('file.csv', 'text/csv')
CartoDB::Api.imports.create(payload: {file: csv_file})

Handling errors

There are 3 types of errors this gem can raise:

CartoDB::Api::InvalidConfiguration: This error is raised when the configuration object is invalid or incomplete.
CartoDB::Api::Error: This error is raised when there's an error related to the API request.
CartoDB::Api::ParsingError: This error is raised when the request was successful but there was a problem parsing the JSON returned.

To retrieve more information about an error CartoDB::Api::Error and CartoDB::Api::ParsingError provide the following attributes: title, details, body, raw_body and status_code. Some may not be present depending on the nature of the error.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/pablo-co/cartodb-api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

There are also a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. These are detailed in the Contributing guidelines.

License

The gem is available as open source under the terms of the MIT License.