Skip to content

Latest commit

 

History

History
324 lines (202 loc) · 7.38 KB

README.markdown

File metadata and controls

324 lines (202 loc) · 7.38 KB
Raw

cartoDB Ruby Client

cartoDB ruby client that allows an easy and simple interaction with the cartoDB API.

Requirements

The only requirement is an Internet connection and a working version of the Ruby language interpreter. Current ruby versions supported are 1.8.7 and 1.9.2

Setup

  1. Install the client gem:

     gem install cartodb-rb-client

    or if you are using bundler, put this line in your Gemfile:

     gem 'cartodb-rb-client'

  2. Log into http://cartodb.com, get your OAUTH credentials and put them in a YAML file:

    cartodb_config.yml:

     host: 'YOUR_CARTODB_DOMAIN'
 oauth_key: 'YOUR_OAUTH_KEY'
 oauth_secret: 'YOUR_OAUTH_SECRET'
 oauth_access_token: 'YOUR_OAUTH_ACCES_TOKEN'
 oauth_access_token_secret: 'YOUR_OAUTH_ACCES_TOKEN_SECRET'

    We also support xAuth protocol. In order to use it, provide your username and password instead of your access token:

     host: 'YOUR_CARTODB_DOMAIN'
 oauth_key: 'YOUR_OAUTH_KEY'
 oauth_secret: 'YOUR_OAUTH_SECRET'
 username: 'YOUR_CARTODB_USERNAME'
 password: 'YOUR_CARTODB_PASSWORD'

  3. Setup your cartoDB connection object. To do so, load the YAML file and assign it to a CartoDB::Config object:

     CartoDB::Settings = YAML.load_file(Rails.root.join('config/cartodb_config.yml'))
 CartoDB::Connection = CartoDB::Client::Connection.new

And that's it. Now you should be able to run querys against the cartoDB servers using the CartoDB::Connection object.

Rails apps

If you're developing a Rails app, you just need to add the cartodb_config.yml file to your rails app config directory. And that's it. You can access cartoDB anywhere in your app's code using the CartoDB::Connection class.

Using the cartoDB API

List of supported methods to interact with cartoDB:

####1. Create table.

Creates a new table in cartoDB. The table's name will be normalized, for example, 'table #1' will become 'table_1'.

Arguments:

  • table_name: table's name.

  • schema: list of fields the table will contain.

  • the_geom_type: Type of geometry the_geom field will have. Currently we only support 'POINT', but we'll support more types soon.

Example:

CartoDB::Connection.create_table 'table #1', [{:name => 'field1', :type => 'text'}], 'POINT'

Results:

{:id => 1,
 :name => "table_1",
 :schema =>
 [["cartodb_id", "number"],
  ["field1", "string"],
  ["updated_at", "date"],
  ["created_at", "date"]]}

####2. Add column.

Adds a new column to an existing table.

Arguments:

  • table_name: table's name.
  • column_name: new column's name.
  • column_type: new column's data type. Supported types: string, numeric, date, boolean and geometry.

Example:

CartoDB::Connection.add\_column 'table_1', 'my_column', 'numeric'

Results:

[]

####3. Drop column.

Removes an existing column in the specified table.

Arguments:

  • table_name: table's name which column will be dropped.
  • column_name: name of the column to be dropped.

Example:

CartoDB::Connection.drop\_column 'table_1', 'my_column'

Results:

[]

####4. Change column.

Changes name and data type of an existing column.

Arguments:

  • table_name: table's name which column will be changed.
  • old_column_name: current name of the column to be changed.
  • new_column_name: new name for the column.
  • column_type: new data type of the column.

Example:

CartoDB::Connection.change\_column 'table_1', 'field1', 'myfield', 'boolean'

Results:

[]

####5. List tables.

List all tables in your cartoDB account.

Example:

CartoDB::Connection.tables

Results:

{:total_entries => 1,
 :tables =>
 [{:id => 1,
  :name => "table_1",
  :privacy => "PUBLIC",
  :tags => "",
  :schema =>
  [["cartodb_id", "number"],
   ["the_geom", "geometry", "geometry", "point"],
   ["field1", "string"],
   ["created_at", "string"],
   ["updated_at", "string"]],
  :updated_at => Mon, 12 Sep 2011 00:00:00 +0000,
  :rows_counted => 1}]}

####6. Table's detail

Shows information about the specified table.

Arguments:

  • table_name: Name of the table you want to get info.

Example:

CartoDB::Connection.table 'table_1'

Results:

{:id => 1,
 :name => "table_1",
 :privacy => "PRIVATE",
 :tags => "",
 :schema => 
 [["cartodb_id", "number"],
  ["myfield", "boolean"],
  ["updated_at", "date"],
  ["created_at", "date"]]}

####7. Drop table.

Deletes the specified table.

Arguments:

  • table_name: Name of the table to delete.

Example:

CartoDB::Connection.drop_table 'table_1'

Results:

[]

####8. Get single row.

You can get a single row with this method by specifying its cartodb_id.

Arguments:

  • table_name: Name of the table.
  • row_id: Id of the row we want.

Example:

CartoDB::Connection.row 'table_1', 1

Result:

{:id => 1,
 :updated_at => Tue, 13 Sep 2011 00:00:00 +0000,
 :created_at => Tue, 13 Sep 2011 00:00:00 +0000,
 :cartodb_id => 1,
 :field1 => "cartoDB is awesome!"}

####9. Insert row.

Inserts a new row in the specified table.

Arguments:

  • table_name: Name of the table.
  • row: A ruby hash with the name of the columns we want to insert data in, and its values.

Example:

CartoDB::Connection.insert_row 'table_1', :field1 => 'cartoDB is

awesome!'

Results:

{:id => 1,
 :updated_at => Tue, 13 Sep 2011 00:00:00 +0000,
 :created_at => Tue, 13 Sep 2011 00:00:00 +0000,
 :cartodb_id => 1,
 :field1 => "cartoDB is awesome!"}

####10. Update row.

Updates a single row in the specified table.

Arguments:

  • table_name: Name of the table.
  • row_id: Id of the row we want to update.
  • row: A ruby hash containing the column names and values for the update.

Example:

CartoDB::Connection.update_row 'table_1', 1, :field1 => 'cartoDB is

really awesome!'

Result:

{:id => 1,
 :updated_at => Tue, 13 Sep 2011 00:00:00 +0000,
 :created_at => Tue, 13 Sep 2011 00:00:00 +0000,
 :cartodb_id => 1,
 :field1 => "cartoDB is *really* awesome!"}

####11. Delete row.

Deletes a row in the specified table.

Arguments:

  • table_name: Name of the table.
  • row_id: Id of the row we want to delete.

Example:

CartoDB::Connection.delete_row 'table_1', 1

Result:

{:time => 0.008, :total_rows => 0, :rows => []}

####12. Execute a sql query.

Executes an sql query against your database in cartoDB.

Arguments:

  • sql: String containing the query we want to execute.
  • options: A ruby hash containing optional params to run the query. Currently we support pagination using the :page and :rows_per_page parameters in the options argument.

Example:

# At first, lets introduce some dummy data for the test
10.times{ CartoDB::Connection.insert_row 'table_1', :field1 => 'cartoDB is awesome!'}

# And now, the query itself
CartoDB::Connection.query 'SELECT * FROM table_1', :page => 1,

:rows_per_page => 5

Results:

{:time=>0.017,
 :total_rows=>10,
 :rows=>[{:updated_at=>Tue, 13 Sep 2011 00:00:00 +0000,
          :created_at=>Tue, 13 Sep 2011 00:00:00 +0000,
          :cartodb_id=>2,
          :field1=>"cartoDB is awesome!"},
          ...
          ]}

More info

You can also check the oficial cartoDB Documentation if you want more info about the cartoDB API.