Initial commit

doc/developer-center/auth-api/guides/01-CARTO-Authorization.md

@@ -0,0 +1,20 @@
+## CARTO Authorization 
+
+All requests to CARTO's APIs (Maps, Sql, etc.) require you to authenticate with an API Key.
+API Keys identify your project and provide a powerful and flexible primitive for managing access to CARTO's resources like APIs and Datasets.
+
+These API Keys can be provisioned, revoked and regenerated through the [Auth API]({{site.authapi_docs}}/reference/) or the dashboard. You are able to manage authorization through the UI, by [logging on to your CARTO account](https://carto.com) and managing everything in there. Here you have an example of the authorization dashboard in a real CARTO account.
+
+![Authorization dashboard image 1](../img/capture-dashboard-auth.png)
+
+And here you can see the process of creating a new API key, managing its name and resources in terms of APIs and Datasets, including its permissions.
+
+It requires to add a name and grant permission for at least one of these: 
+* SQL API: you will have to include CREATE datasets or specific permissions on any table.
+* MAPS API: you will have to specify SELECT permissions on any table.
+* CREATE datasets: allows you to create tables in the user schema by using the SQL API, and also modify or delete the tables previously created with it. It won't allow to modify or delete a table created with a different API key, in that case you'll receive an `Access denied` error.
+* LISTING datasets: allows to read the metadata from the existing tables, views and materialized views in the user schema by using the endpoint: `api/v4/datasets`
+
+![Authorization dashboard image 2](../img/capture-auth-new-apikey.png)
+
+**Warning:** Changes to the key permissions are not possible once key is generated.

doc/developer-center/auth-api/guides/02-how-to-send-API-Keys.md

@@ -0,0 +1,78 @@
+## How to send API Keys
+
+A CARTO API Key is physically a token/code of 12+ random alphanumeric characters.
+
+You can pass in the API Key to our APIs either by using the HTTP Basic authentication header or by sending an `api_key` parameter via the query string or request body. 
+
+**Tip:** If you use our client library CARTO.js, you only need to follow the authorization section and we will handle API Keys automatically for you.
+
+The examples shown to illustrate the different methods of how to send API Keys use the following parameters:
+
+```
+- user: username 
+- API Key: 1234567890123456789012345678901234567890 
+- API endpoint: https://username.carto.com/endpoint/ 
+```
+
+
+### HTTP Basic Authentication
+
+Basic Access Authentication is the simplest technique of handling access control and authorization in a standardized way. It consists essentially of an `HTTP Authorization Basic` header followed by the user credentials (username and password) encoded using base64.
+
+If that looks complicated to you, don’t worry. Most client software provide simple mechanisms to use HTTP Basic Authentication, like [curl](https://ec.haxx.se/http-auth.html), [Request](https://github.com/request/request#http-authentication) (JavaScript) and [Requests](http://docs.python-requests.org/en/master/user/authentication/#basic-authentication) (Python).
+
+For requests to CARTO’s APIs, take the API Key as the password, and the username as the user who issued that API Key.
+
+#### Examples:
+
+##### Curl
+
+```bash
+curl -X GET \
+  'https://username.carto.com/endpoint/' \
+  -H 'authorization: Basic dXNlcm5hbWU6MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MA==' 
+```
+
+##### Request (JavaScript)
+
+```javascript
+request.get('https://username.carto.com/endpoint/', {
+  'auth': {
+    'user': 'username',
+    'pass': 1234567890123456789012345678901234567890
+  }
+});
+```
+
+##### Requests (Python)
+```python
+r = requests.get('https://username.carto.com/endpoint/', auth=(username, 1234567890123456789012345678901234567890))
+```
+
+### Query string/Request body parameter
+
+Alternatively, you can use an URL query string parameter or a field in the request body. In both cases, the name of the parameter is `api_key`.
+
+#### Examples:
+
+```bash
+curl -X GET 'https://username.carto.com/endpoint/?api_key=1234567890123456789012345678901234567890'
+```
+
+```bash
+curl -X POST \
+  'https://username.carto.com/endpoint/' \
+  -H 'content-type: application/json' \
+  -d '{
+	"api_key": "1234567890123456789012345678901234567890"
+  }'
+```
+
+
+If, for some mysterious reason, you submit the API Key with more than one of the available methods, the order of precedence is as follows:
+
+1. HTTP Basic Authentication header 
+2. URL query string parameter 
+3. Request body field 
+
+Likewise, for security reasons and future-proofing, we recommend that you use that same order when choosing a method for sending the API Key. In other words, favour the use of HTTP Basic Authentication over the URL query string, and try to avoid the body field. We support this method just for backwards compatibility. 

doc/developer-center/auth-api/guides/03-types-of-API-Keys.md

@@ -0,0 +1,78 @@
+## Types of API Keys
+
+In CARTO, you can find 3 types of API Keys:
+
+- Regular 
+- Default public 
+- Master
+
+
+#### Regular
+
+Regular API Keys are the most common type of API Keys. They provide access to APIs and database tables (AKA datasets) in a granular and flexible manner.
+
+For example one API key can provide access to:
+  
+- The SQL API 
+- The `world_population` dataset with select permission 
+- The `liked_cities` dataset with select/insert permissions 
+- Creating new datasets in the user account
+- Listing existing datasets in the user account
+  
+With this API Key you can: 
+
+- Access the SQL API, but not the Maps API.
+- Run a `SELECT SQL` query to the `world_population` dataset, but not an `UPDATE`, `DELETE` or `INSERT`.
+- Run an `INSERT` to the `liked_cities` dataset, but not to `national_incomes`.
+- Run `CREATE TABLE AS...` SQL queries to create new tables in the user account. As the owner of the tables created you'll also be able to `DROP` and `ALTER` the created tables.
+- Read metadata (like name or privacy) from `national_incomes`, but not its content.
+
+It's possible to create as many regular API Keys as you want. Moreover, to enforce security, we encourage you to create as many regular API Keys as apps/maps you produce. Since regular API Keys can be independently revoked, you have complete control of the lifecycle of your API credentials.
+
+An important property to keep in mind about regular API Keys is that they are *not editable*. You can not add/delete datasets nor APIs. It’s designed this way on purpose for security reasons.
+
+Another important property of Regular API keys is that they inherit all the datasets permissions from the Default Public API Key.
+
+You can see below an example of a real API key as it is displayed in a CARTO account.
+
+![Capture Auth API key section in dashboard](../img/capture-auth-apikey.png)
+
+#### Default Public
+
+Default public are a kind of regular API Keys. They too provide access to APIs and datasets, but for the latter in a read-only way.
+
+Every user has one and only one Default Public API Key. That means that on user creation a Default API Key is issued for that user, and that these type of keys are not revocable/deletable.
+
+For example one Default Public API Key can provide access to 
+
+- the SQL API 
+- the Maps API 
+- the `world_population` dataset with read permission 
+- the `liked_cities` dataset with read permission 
+
+As you can see, API and read-only selected datasets access are possible.
+
+At the beginning of this authentication section we stated that all API requests require an API Key. Well, we lied a little bit. If none is provided, the Default Public API Key is used as a fall back. 
+
+**Warning:** This is done for backwards compatibility reasons. Don’t expect this behaviour to be maintained in the long term, it can be deprecated. 
+
+Get used to always send an API Key, even if it’s the Default Public.
+
+A cosmetic difference compared to the other API Key types is the code/token that identifies these API Keys, it’s just: _default_public_. It’s a simple human-readable constant string, no randoms involved.
+
+
+#### Master
+
+Master keys are a very special kind of API Keys. As it happens with the Default Public type, every user has one and only one Master non revocable API Key.
+
+The special thing about Master API Keys is that they grant access to EVERYTHING: APIs and datasets (select/insert/create/delete). Additionally, a Master API Key is required to access most of the Auth API endpoints.
+
+Your Master API key carries many privileges, so be sure to keep it secret. Do not share it in publicly accessible areas such as GitHub or client-side code. 
+
+Below you have an example of a master API key.
+
+![Capture Master Auth API key section in dashboard](../img/capture-auth-apikey-master.png)
+
+**Tip:** If you think is has been compromised, regenerate it immediately.
+
+Actually, you should use Master API Keys sparingly. Try to limit its direct use only to interact programmatically with the [Auth API]({{site.authapi_docs}}/reference/). Issue and use regular API Keys for the rest of use cases.

doc/developer-center/auth-api/guides/04-general-considerations.md

@@ -0,0 +1,9 @@
+## General Considerations
+
+- Regenerate a regular/master API Key if you suspect it has being compromised. A regenerated API Key grants the same permissions as before, but has a new code/token. Maps/apps using a regenerated API Key must be updated to adapt to that change, otherwise they will stop working. 
+- Send always an API Key in your API requests 
+- Issue a new regular API Key per map/app. Try to avoid sharing keys between maps/apps 
+- Grant the least amount of necessary permissions per API Key 
+- Use the Master API Key sparingly 
+- Keep your Master API Key secret! 
+- Do not overuse the Default Public API Key. It’s meant for obviously public Datasets. 

doc/developer-center/auth-api/guides/05-Authorization-CARTO-views.md

@@ -0,0 +1,45 @@
+## Authorization for CARTO views
+
+With the [CARTO Auth API](https://carto.com/developers/auth-api/), it is possible to create API Keys not only for tables in CARTO (aka datasets), but also for Views in CARTO.
+
+CARTO use PostgreSQL as the database to store your datasets, so you can create a View in CARTO in the same way that it is created in PostgreSQL. We would recommend checking [this section](https://www.postgresql.org/docs/9.5/static/tutorial-views.html) of the PostgreSQL documentation if you want to learn more about how Views are created in PostgreSQL.
+
+What is the advantage of using a View with the CARTO Auth API? Well, in order to answer that question, let's assume that you have a dataset in CARTO and you want to restrict partial information of your dataset when publishing a map or using the SQL API. For example, you might have a dataset named `clients` with [private privacy](https://carto.com/learn/guides/publish-share/privacy-settings-for-protecting-maps-and-data/) and you want to build a map with clients of New York area only, so you can create a View as it is done in the next block of code:
+
+```sql
+CREATE VIEW clients_nyc AS (
+    SELECT * FROM clients WHERE area = 'NY'
+);
+```
+
+Now, you would need to use the Auth API in order to create the API Key for the View with a payload that sets the permissions of the new API Key that will be created. In this example, we are giving read-only or select permission to our View so it can only be available when using the API key with the [CARTO Maps API](https://carto.com/developers/maps-api/) or [CARTO.js](https://carto.com/developers/carto-js/).
+
+```json
+{
+  "name": "Clients-NYC",
+  "grants": [
+    {
+      "type": "apis",
+      "apis": [
+        "maps"
+      ]
+    },
+    {
+      "type": "database",
+      "tables": [
+        {
+          "schema": "public",
+          "name": "clients_nyc",
+          "permissions": [
+            "select"
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+If you try to access to the data of this View using the [CARTO SQL API](https://carto.com/developers/sql-api/), you will receive a forbidden error, because this API Key do not have permissions to be accessed using the CARTO SQL API.
+
+So, by creating API Keys for the Views in CARTO using the Auth API, we can display the information partial information that we want and at the same time, keeping our data private.

doc/developer-center/auth-api/reference/swagger.yaml

@@ -0,0 +1,621 @@
+openapi: 3.0.0
+info:
+  title: Auth API
+  description: >
+    # Introduction
+
+    This API allows you to manage API keys. API keys are the fundamental
+    building block of CARTO's authorization system. See this this guide for more
+    information.
+
+
+    This API accepts and returns JSON.
+
+    API base endpoint is `https://<your_username>.carto.com/api/v3/api_keys` or `https://<org_name>.carto.com/u/<your_username/api/v3/api_keys` in case you are using a user belonging to an organization.
+
+    # Authorization
+
+    There are three different API Keys that provide with different access privileges:
+
+    1. `default`: This API provides access to all public objects. It cannot be removed.
+
+    1. `master`: Using this API Key you will have full access and will be able to create/manage `regular` API Keys. It cannot be removed. You should keep its token safe and use it only when strictly necessary.
+
+    1. `regular`: This API Keys can be created with custom access privileges and can also be removed.
+
+    # API Key format
+
+    Every API Key consists on four main parts:
+
+    1. **name**: You will choose it when creating the API Key and it will be used for indexing your API Keys.
+
+    1. **type**: As mentioned before, there are three type of API Keys: `default`, `master` and `regular` providing different levels of access.
+
+    1. **token**: It will be used for authenticating your requests.
+
+    1. **grants**: Describes which APIs this API Key provides access to and to which tables. It consists on an array of two JSON objects. This object's `type` attribute can be `apis`, `database` or `dataservices`:
+
+        - `apis`: Describes which APIs does this API Key provide access to through `apis` attribute:
+        ```{
+              {
+                    "type": "apis",
+                    "apis": [
+                        "sql",
+                        "maps"
+                    ]
+              }
+        ```
+        - `database`: Describes to which tables and schemas and which privileges on them this API Key grants access to through `tables`, `schemas` and `table_metadata` attributes.
+          You can grant read (`select`) or write (`insert`, `update`, `delete`) permissions on tables.
+          For the case of `schemas`, once granted the `create` permission on a schema, you'll be able to run SQL queries such as `CREATE TABLE AS...`, `CREATE VIEW AS...` etc. to create entities on it.
+          Also, you can allow to list all tables metadata (like name or privacy) with the `table_metadata` attribute.
+        ```{
+              {
+                    "type": "database",
+                    "tables": [
+                        {
+                            "schema": "public",
+                            "name": "my_table",
+                            "permissions": [
+                                "insert",
+                                "select",
+                                "update"
+                            ]
+                        }
+                    ],
+                    "schemas": [
+                        {
+                            "name": "public",
+                            "permissions": [
+                                "create"
+                            ]
+                        }
+                    ],
+                    "table_metadata" : []
+              }
+        ```
+        - `dataservices`: Describes to which data services this API Key grants access to though `services` attribute:
+        ```{
+              {
+                    "type": "dataservices",
+                    "services": [
+                        "geocoding",
+                        "routing",
+                        "isolines",
+                        "observatory"
+                    ]
+              }
+        ```
+
+    # Authentication
+
+    In order to authenticate your requests to the API, they need to include a `Basic` `Authentication` header, where the `username` would be your username and the `password` would be your API Key's token. This authentication method will be valid across all CARTO components (Auth API, Maps API, SQL API). You can build your own `Authorization` header as follows:
+
+
+    ```
+    "Basic #{Base64.strict_encode64(username + ':' + api_key.token)}"
+    ```
+
+
+    **Important:** The API key you provide to access Auth API must be of type
+    `master`.
+  version: 0.0.1
+  contact:
+    name: Have you found an error? Github issues
+    url: 'https://github.com/CartoDB/cartodb/issues/new'
+servers:
+  - url: 'https://{user}.carto.com/api/v3'
+    description: Production server (uses live data)
+    variables:
+      domain:
+        default: carto.com
+        description: 'If on premise, change it to your domain'
+      user:
+        default: username
+        description: Your username
+paths:
+  /api_keys:
+    get:
+      summary: List API keys
+      description: Returns the API keys list.
+      tags:
+        - API Keys
+      operationId: getApiKeys
+      parameters:
+        - in: query
+          name: per_page
+          schema:
+            type: integer
+          description: Limits number of API Keys listed
+          required: false
+        - in: query
+          name: page
+          schema:
+            type: integer
+          description: Defines what page to fetch
+          required: false
+        - in: query
+          name: order
+          schema:
+            type: string
+          description: Its used to define the critera by which API Keys are listed. It can be any of the attributes
+          required: false
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ApiKeys'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+
+    post:
+      summary: Create API key
+      description: >-
+        Creates a `regular` API key. `master` and `default_public` API Keys are automatically generated on
+        user's creation.
+      tags:
+        - API Keys
+      operationId: createApiKey
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ApiKeyCreation'
+      responses:
+        '201':
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiKey'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '422':
+          $ref: '#/components/responses/BadInput'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+
+  '/api_keys/{name}':
+    parameters:
+      - $ref: '#/components/parameters/apiKeyName'
+    get:
+      summary: Get API key
+      description: >-
+        Returns an API key based on its `name`.
+
+      tags:
+        - API Keys
+      operationId: getApiKeyById
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiKey'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+
+    delete:
+      summary: Delete API key
+      description: >-
+        Deletes an API key based on it's `name`. Only `regular` API keys can be
+        deleted.
+      tags:
+        - API Keys
+      operationId: deleteApiKeyById
+      responses:
+        '200':
+          description: The resource was deleted successfully.
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+      x-code-samples:
+
+  '/api_keys/{name}/token/regenerate':
+    parameters:
+      - $ref: '#/components/parameters/apiKeyName'
+    post:
+      summary: Regenerate API key token
+      description: Regenerates the API key token. The rest of the fields remain the same.
+      tags:
+        - API Keys
+      operationId: regenerateApiKeyById
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiKey'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+      x-code-samples:
+
+components:
+  schemas:
+    ApiKeys:
+      type: object
+      properties:
+        total:
+          type: integer
+          description: Total number of API Keys
+        count:
+          type: integer
+          description: Number of returned API Keys
+        result:
+          type: array
+          items:
+            $ref: '#/components/schemas/ApiKey'
+        _links:
+          type: object
+          properties:
+            first:
+              $ref: '#/components/schemas/Links'
+              description: Link to the first page
+            prev:
+              $ref: '#/components/schemas/Links'
+              description: Link to the previous page
+            next:
+              $ref: '#/components/schemas/Links'
+              description: Link to the next page
+            last:
+              $ref: '#/components/schemas/Links'
+              description: Link to the last page
+      example:
+        total: 3
+        count: 3
+        result:
+          - name: Master
+            user:
+              username: amartin
+            type: master
+            token: slxIYwIDyEGGS2W9W-uEKw
+            grants:
+              - type: apis
+                apis:
+                  - sql
+                  - maps
+              - type: database
+                tables: []
+                schemas: []
+                table_metadata: []
+              - type: dataservices
+                services:
+                  - geocoding
+                  - routing
+                  - isolines
+                  - observatory
+            created_at: '2018-02-08 14:24:41 +0000'
+            updated_at: '2018-02-08 14:24:41 +0000'
+            _links:
+              self: 'https://carto.com/api/v3/api_keys/Master'
+          - name: MyTableApi
+            user:
+              username: amartin
+            type: regular
+            token: moLv8B-kotcjUL-uxMhbGg
+            grants:
+              - type: apis
+                apis:
+                  - maps
+              - type: database
+                tables:
+                  - schema: public
+                    name: my_table
+                    permissions:
+                      - insert
+                      - select
+                      - update
+                schemas:
+                  - name: public
+                    permissions:
+                      - create
+                table_metadata: []
+              - type: dataservices
+                services:
+                  - geocoding
+                  - observatory
+            created_at: '2018-02-14 13:23:12 +0000'
+            updated_at: '2018-02-14 13:23:12 +0000'
+            _links:
+              self: 'https://carto.com/api/v3/api_keys/MyTableApi'
+          - name: Default public
+            user:
+              username: amartin
+            type: default
+            token: default_public
+            grants:
+              - type: apis
+                apis:
+                  - sql
+                  - maps
+              - type: database
+                tables: []
+                schemas: []
+            created_at: '2018-02-15 13:50:36 +0000'
+            updated_at: '2018-02-15 13:50:36 +0000'
+            _links:
+              self: 'https://carto.com/api/v3/api_keys/Default%20public'
+        _links:
+          first:
+            href: 'https://carto.com/api/v3/api_keys?order=updated_at&page=1&per_page=20'
+          last:
+            href: 'https://carto.com/api/v3/api_keys?order=updated_at&page=1&per_page=20'
+
+    ApiKey:
+      allOf:
+        - type: object
+          properties:
+            name:
+              type: string
+            user:
+              properties:
+                username:
+                  type: string
+            type:
+              $ref: '#/components/schemas/ApiKeysTypes'
+            token:
+              type: string
+            grants:
+              type: array
+              items:
+                oneOf:
+                  - $ref: '#/components/schemas/ApisGrant'
+                  - $ref: '#/components/schemas/GrantDatabase'
+                  - $ref: '#/components/schemas/GrantDataservices'
+            _links:
+              type: object
+              properties:
+                self:
+                  $ref: '#/components/schemas/Links'
+                  description: Link to the resource
+        - $ref: '#/components/schemas/Timestamps'
+      required:
+        - name
+        - type
+        - grants
+      example:
+        name: MyTableApi
+        user:
+          username: amartin
+        type: regular
+        token: moLv8B-kotcjUL-uxMhbGg
+        grants:
+          - type: apis
+            apis:
+              - maps
+          - type: database
+            tables:
+              - schema: public
+                name: my_table
+                permissions:
+                  - insert
+                  - select
+                  - update
+            schemas:
+              - name: public
+                permissions:
+                  - create
+            table_metadata: []
+          - type: dataservices
+            services:
+              - geocoding
+              - observatory
+        created_at: '2018-02-14 13:23:12 +0000'
+        updated_at: '2018-02-14 13:23:12 +0000'
+        _links:
+          self:
+            href: 'http://amartin.carto.com/api/v3/api_keys/MyTableApi'
+
+    ApiKeyCreation:
+      type: object
+      properties:
+        name:
+          type: string
+          description: For identifying your API Key
+        grants:
+          type: array
+          items:
+            oneOf:
+              - $ref: '#/components/schemas/GrantDatabase'
+              - $ref: '#/components/schemas/ApisGrant'
+              - $ref: '#/components/schemas/GrantDataservices'
+            discriminator:
+              propertyName: type
+      required:
+        - name
+        - grants
+      example:
+        name: MyTableApi
+        grants:
+          - type: apis
+            apis:
+              - maps
+          - type: database
+            tables:
+              - schema: public
+                name: my_table
+                permissions:
+                  - select
+                  - update
+                  - insert
+            schemas:
+              - name: public
+                permissions:
+                  - create
+            table_metadata: []
+          - type: dataservices
+            services:
+              - geocoding
+              - observatory
+    GrantDataservices:
+      type: object
+      properties:
+        type:
+          type: string
+          enum:
+            - dataservices
+        services:
+          type: array
+          items:
+            $ref: '#/components/schemas/Dataservices'
+          uniqueItems: true
+      required:
+        - type
+        - services
+    Dataservices:
+      type: string
+      enum:
+        - geocoding
+        - routing
+        - isolines
+        - observatory
+
+    GrantDatabase:
+      type: object
+      properties:
+        type:
+          type: string
+          enum:
+            - database
+        tables:
+          type: array
+          items:
+            $ref: '#/components/schemas/TableGrant'
+        schemas:
+          type: array
+          items:
+            $ref: '#/components/schemas/SchemaGrant'
+        table_metadata:
+          type: array
+      required:
+        - type
+    TableGrant:
+      type: object
+      properties:
+        name:
+          type: string
+        schema:
+          type: string
+        permissions:
+          type: array
+          items:
+            type: string
+            enum:
+              - select
+              - insert
+              - update
+              - delete
+          uniqueItems: true
+      required:
+        - name
+        - schema
+        - permissions
+    SchemaGrant:
+      type: object
+      properties:
+        name:
+          type: string
+        permissions:
+          type: array
+          items:
+            type: string
+            enum:
+              - create
+          uniqueItems: true
+      required:
+        - name
+        - permissions
+    ApisGrant:
+      type: object
+      properties:
+        type:
+          type: string
+          enum:
+            - apis
+        apis:
+          type: array
+          items:
+            $ref: '#/components/schemas/Apis'
+          uniqueItems: true
+      required:
+        - type
+        - apis
+    Apis:
+      type: string
+      enum:
+        - sql
+        - maps
+    ApiKeysTypes:
+      type: string
+      enum:
+        - master
+        - default
+        - regular
+    Timestamps:
+      type: object
+      properties:
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+    Links:
+      type: object
+      properties:
+        href:
+          type: string
+          format: url
+          description: link to the resource
+  securitySchemes:
+    ApiKeyHTTPBasicAuth:
+      type: http
+      scheme: basic
+    ApiKeyQueryParam:
+      type: apiKey
+      in: header
+      name: api_key
+  parameters:
+    apiKeyName:
+      in: path
+      name: name
+      required: true
+      schema:
+        type: string
+      description: the API key `name`
+  responses:
+    NotFound:
+      description: The specified resource was not found
+    Unauthorized:
+      description: Unauthorized. Wrong or no authentication provided.
+    Forbidden:
+      description: Forbidden. The API key does not authorize this request.
+    BadInput:
+      description: Request's parameters error

doc/developer-center/auth-api/support/01-support-options.md

@@ -0,0 +1,36 @@
+## Support Options
+
+Feeling stuck? There are many ways to find help.
+
+* Ask a question on [GIS StackExchange](https://gis.stackexchange.com/questions/tagged/carto) using the `CARTO` tag.
+* [Report an issue](https://github.com/CartoDB/cartodb/issues) in Github.
+* Engine Plan customers have additional access to enterprise-level support through CARTO's support representatives.
+
+If you just want to describe an issue or share an idea, just <a class="typeform-share" href="https://cartohq.typeform.com/to/mH6RRl" data-mode="popup" target="_blank"> send your feedback</a>
+
+### Issues on Github
+
+If you think you may have found a bug, or if you have a feature request that you would like to share with the Auth API team, please [open an issue](https://github.com/CartoDB/cartodb/issues/new). 
+
+Before opening an issue, review the [contributing guidelines](https://github.com/CartoDB/cartodb/blob/master/CONTRIBUTING.md).
+
+
+### Community support on GIS Stack Exchange
+
+GIS Stack Exchange is the most popular community in the geospatial industry. This is a collaboratively-edited question and answer site for geospatial programmers and technicians. It is a fantastic resource for asking technical questions about developing and maintaining your application.
+
+
+When posting a new question, please consider the following:
+
+* Read the GIS Stack Exchange [help](https://gis.stackexchange.com/help) and [how to ask](https://gis.stackexchange.com/help/how-to-ask) pages for guidelines and tips about posting questions.
+* Be very clear about your question in the subject. A clear explanation helps those trying to answer your question, as well as those who may be looking for information in the future.
+* Be informative in your post. Details, code snippets, logs, screenshots, etc. help others to understand your problem.
+* Use code that demonstrates the problem. It is very hard to debug errors without sample code to reproduce the problem.
+
+### Engine Plan Customers
+
+Engine Plan customers have additional support options beyond general community support. As per your account Terms of Service, you have access to enterprise-level support through CARTO's support representatives available at [enterprise-support@carto.com](mailto:enterprise-support@carto.com)
+
+In order to speed up the resolution of your issue, provide as much information as possible (even if it is a link from community support). This allows our engineers to investigate your problem as soon as possible.
+
+If you are not yet CARTO customer, browse our [plans & pricing](https://carto.com/pricing/) and find the right plan for you.

doc/developer-center/auth-api/support/02-contribute.md

@@ -0,0 +1,36 @@
+## Contribute
+
+CARTO platform is an open-source ecosystem. You can read about the [fundamentals]({{site.fundamental_docs}}/components/) of CARTO architecture and its components.
+We are more than happy to receive your contributions to the code and the documentation as well.
+
+## Filling a ticket
+
+If you want to open a new issue in our repository, please follow these instructions:
+
+1. Descriptive title.
+2. Write a good description, it always helps.
+3. Specify the steps to reproduce the problem.
+4. Try to add an example showing the problem.
+
+## Contributing code
+
+Best part of open source, collaborate in Auth API code!. We like hearing from you, so if you have any bug fixed, or a new feature ready to be merged, those are the steps you should follow:
+
+1. Fork the repository.
+2. Create a new branch in your forked repository.
+3. Commit your changes. Add new tests if it is necessary.
+4. Open a pull request.
+5. Any of the maintainers will take a look.
+6. If everything works, it will merged and released \o/.
+
+If you want more detailed information, this [GitHub guide](https://guides.github.com/activities/contributing-to-open-source/) is a must.
+
+## Completing documentation
+
+Auth API documentation is located in ```docs/```. That folder is the content that appears in the [Developer Center](http://carto.com/developers/auth-api/). Just follow the instructions described in [contributing code](#contributing-code) and after accepting your pull request, we will make it appear online :).
+
+**Tip:** A convenient, easy way of proposing changes in documentation is by using the GitHub editor directly on the web. You can easily create a branch with your changes and make a PR from there.
+
+## Submitting contributions
+
+You will need to sign a Contributor License Agreement (CLA) before making a submission. [Learn more here](https://carto.com/contributions).

doc/developer-center/cartocss/02-properties-for-torque.md

@@ -0,0 +1,208 @@
+## CartoCSS Properties for Torque Style Maps
+
+While you can use _most_ of the CartoCSS properties to customize Torque maps, CARTO provides additional CartoCSS properties that are specific for Torque style maps. You can add these CartoCSS properties to [Torque](#cartocss---torque-maps), [Torque Heatmaps](#cartocss---torque-heatmaps), and [Torque Category](#cartocss---torque-category-maps) maps. 
+
+**Note:** For a reference of the CartoCSS properties that are currently supported with Torque, see the [torque-reference.json file](https://github.com/CartoDB/torque-reference/blob/master/1.0.0/reference.json).
+
+### CartoCSS - Torque Maps
+
+The following CartoCSS properties can be applied to Torque style maps. Note that some values vary, depending on the type of Torque map you are creating.
+
+[-torque-frame-count](#-torque-frame-count-number) | [-torque-animation-duration](#-torque-animation-duration-number) | [-torque-time-attribute](#-torque-time-attribute-string)
+[-torque-aggregation-function](#-torque-aggregation-function-keyword) | [-torque-resolution](#-torque-resolution-float) | [-torque-data-aggregation](#-torque-data-aggregation-keyword) 
+[frame-offset](#frame-offset-number) | 
+
+**Note:** All Torque CartoCSS syntax is prefaced with a hypen.
+
+#### -torque-frame-count `number`
+
+Description | Specifies the number of animation steps/frames in your torque animation.
+Sample CartoCSS Code | `-torque-frame-count:128;`
+Default Value | 128, the data is broken into 128 time frames when parsing CartoCSS. If the data contains a fewer number of total frames, a lessor value is used.
+Available Values | See [numbers](#numbers).
+
+**Tip:** In the CARTO Builder, this is the _STEPS_ value when the style is ANIMATED.
+
+#### -torque-animation-duration `number`
+
+Description | Specifies the length of time for your animation, in seconds.
+Sample CartoCSS Code | `-torque-animation-duration:30;`
+Default Value | undefined. Any positive number value is accepted.
+Available Values | See [numbers](#numbers). _This can also be a decimal - see [float](#float)._
+
+**Tip:** In the CARTO Builder, this is the _DURATION_ value when the style is ANIMATED.
+
+#### -torque-time-attribute `string`
+
+Description | Defines the name of the date column in your dataset. This column can be an integer *or* a date.
+Sample CartoCSS Code | `-torque-time-attribute:"cartodb_id";`
+Default Value | undefined
+Available Values | See [string](#string).
+
+**Tip:** In the CARTO Builder, this is the _COLUMN_ value when the style is ANIMATED.
+
+#### -torque-aggregation-function `keyword`
+
+**Note:** Please note the different available values that should be applied if you are using a [Torque Category](#cartocss---torque-category-maps) map.
+
+Description | Since Torque maps renders data in clusters, this property defines how values are displayed in each cluster of the map. Column data must be numeric. For example, you can define: a maximum value, a count, or the total number of values in each cluster.<br /><br />**Note:** When visualizing Torque style maps, it is required that you normalize your data to show a total count, or a range, of `0`-`255`. For more details, see this description about [statistical normalization](https://books.google.com/books?id=FrUQHIzXK6EC&pg=PT347&lpg=PT347&dq=choropleth+normalization&source=bl&ots=muDZhsb2jT&sig=DbomJnKedQjaKvcQgm_sVqHBt-8&hl=en&sa=X&ved=0CCYQ6AEwAjgKahUKEwje0ee8qaTHAhUCZj4KHRF5CjM#v=onepage&q=choropleth%20normalization&f=false).
+Sample CartoCSS Code | `-torque-aggregation-function: "count(cartodb_id)";`
+Default Value | `"count(cartodb_id)"`
+Available Values | `count(column_name), max(column_name), sum(column_name)`
+Related Example | Wiki page about [how spatial aggregation works](https://github.com/CartoDB/torque/wiki/How-spatial-aggregation-works).
+
+**Note:** Since the CARTO geospatial database is built on the PostgreSQL platform and supports advanced PostGIS capabilities, see [PostgreSQL Aggregate Functions](http://www.postgresql.org/docs/10/static/functions-aggregate.html) for additional supported values.
+
+**Tip:** Functions can also be combinations of functions and operations. For example, `log(1 + max(column_name))`.
+
+#### -torque-resolution `float`
+
+Description | Since Torque maps create a grid from your data and aggregates data to each cell of that grid, this property defines the width and height of each cell, in pixels. 
+Sample CartoCSS Code | `-torque-resolution:2;`
+Default Value | undefined
+Available Values | Resolution values should be applied in powers of 2 (for example, `2` `4` `8` and so on). The maximum value is `256`.
+
+**Note:** Defining a larger number applies a larger grid to your data.
+
+**Tip:** In the CARTO Builder, this is the _RESOLUTION_ value when the style is ANIMATED.
+
+#### -torque-data-aggregation `keyword`
+
+Description | Defines how Torque maps display past data. By default, linear data aggregation is applied, where no traces of past data appears. Optionally, you can show past data markers cumulatively.
+Sample CartoCSS Code | `-torque-data-aggregation:linear;`
+Default Value | `linear`, does not leave any trace of past data.
+Available Values | `linear` `cumulative`
+
+**Tip:** In the CARTO Builder, this is the _OVERLAP_ value when the style is ANIMATED.
+
+#### frame-offset `number`
+
+Description | Once your data is aggregated, you can further customize your Torque animation options by specifying how a pixel is rendered in the frames, after the initial rendering (the explosion effect on a Torque map).
+Sample CartoCSS Code | `[frame-offset=1] { ... }`
+Default Value | undefined, customize the marker options for each `frame-offset` property to add more styling. 
+Available Values | See [numbers](#numbers).
+
+**Tip:** In the CARTO Builder, this is the _TRAILS_ value when the style is ANIMATED.
+
+The following example displays additional `frame-offset` values applied to a Torque map.
+
+{% highlight scss %}
+#twitter_citymaps[frame-offset=1] {
+ marker-width:12;
+ marker-fill-opacity:0.45; 
+}
+#twitter_citymaps[frame-offset=2] {
+ marker-width:14;
+ marker-fill-opacity:0.225; 
+}
+#twitter_citymaps[value=1] {
+ marker-fill:#A6CEE3; 
+}
+{% endhighlight %}
+
+**Tip:** You can also select each cluster value and apply custom marker styles, based on the data category. For example, suppose you want to apply a unique style only to the maximum value in your dataset, change the marker style for the maximum value in your animation. These values are located in your CartoCSS properties.
+
+The following example displays CartoCSS properties with a Torque map.
+
+{% highlight scss %}
+/** torque visualization */
+
+Map {
+-torque-frame-count:512;
+-torque-animation-duration:30;
+-torque-time-attribute:"cartodb_id";
+-torque-aggregation-function:"count(cartodb_id)";
+-torque-resolution:2;
+-torque-data-aggregation:linear;
+}
+
+#twitter_citymaps{
+  comp-op: lighter;
+  marker-fill-opacity: 0.9;
+  marker-line-color: #FFF;
+  marker-line-width: 1.5;
+  marker-line-opacity: 1;
+  marker-type: ellipse;
+  marker-width: 6;
+  marker-fill: #ff9900;
+}
+#twitter_citymaps[frame-offset=1] {
+ marker-width:8;
+ marker-fill-opacity:0.45; 
+}
+#twitter_citymaps[frame-offset=2] {
+ marker-width:10;
+ marker-fill-opacity:0.225; 
+}
+{% endhighlight %}
+
+### CartoCSS - Torque Heatmaps
+
+While any of the [Torque CartoCSS properties](#cartocss---torque-maps) can be applied to a Torque Heatmap, the following CartoCSS properties can also be applied to Torque Heatmaps.
+
+- [image-filters `functions`](#image-filters-function), enables you to define the color stop for your heatmap
+
+- [marker-file `uri`](#marker-file-uri), when creating a Torque Heatmap with Carto, marker files are automatically provided. You cannot change these options
+
+- [marker-fill-opacity `float`](#marker-fill-opacity-float)
+
+- [marker-width `expression`](#marker-width-expression)
+
+**Note:** It is a [known issue](http://gis.stackexchange.com/questions/137384/marker-file-for-torque-cartodb) that certain marker properties are not supported when applied to Torque and Torque Category maps. Specifically, when the [marker-file](#marker-file-uri) and [marker-fill](#marker-fill-color) CartoCSS properties are applied, you cannot color a sprite using the marker-fill value. You must create a sprite per color when applying these properties to Torque map. Optionally, change the map type to a Torque Heatmap as a workaround.
+
+The following example displays CartoCSS properties with a Torque Heatmap.
+
+{% highlight scss %}
+/** torque_heat visualization */
+
+Map {
+-torque-frame-count:1;
+-torque-animation-duration:10;
+-torque-time-attribute:"cartodb_id";
+-torque-aggregation-function:"count(cartodb_id)";
+-torque-resolution:2;
+-torque-data-aggregation:linear;
+}
+
+#twitter_citymaps{
+  image-filters: colorize-alpha(blue, cyan, #008000, yellow , orange, red);
+  marker-file: url(http://s3.amazonaws.com/com.cartodb.assets.static/alphamarker.png);
+  marker-fill-opacity: 0.4*[value];
+  marker-width: 35;
+}
+#twitter_citymaps[frame-offset=1] {
+ marker-width:37;
+ marker-fill-opacity:0.2; 
+}
+#twitter_citymaps[frame-offset=2] {
+ marker-width:39;
+ marker-fill-opacity:0.1; 
+}
+{% endhighlight %}
+
+### CartoCSS - Torque Category Maps
+
+While any of the [Torque CartoCSS properties](#cartocss---torque-maps) can be applied to a Torque Category map, the `-torque-aggregration-function` contains different available values that are specific for Torque Category maps.
+
+#### -torque-aggregation-function `keyword` (Torque Category only)
+
+Description | Torque Category applies a PostgreSQL command to find the values that appear most often in your data (in order to cluster your data accordingly).<br /><br />**Note:** When visualizing Torque style maps, it is required that you normalize your data to show a total count, or a range, of `0`-`255`. For more details, see this description about [statistical normalization](https://books.google.com/books?id=FrUQHIzXK6EC&pg=PT347&lpg=PT347&dq=choropleth+normalization&source=bl&ots=muDZhsb2jT&sig=DbomJnKedQjaKvcQgm_sVqHBt-8&hl=en&sa=X&ved=0CCYQ6AEwAjgKahUKEwje0ee8qaTHAhUCZj4KHRF5CjM#v=onepage&q=choropleth%20normalization&f=false).
+Sample CartoCSS Code | `-torque-aggregation-function:"CDB_Math_Mode (torque_category)";`
+Default Value | `"CDB_Math_Mode(torque_category)"`
+Available Values | `count(column_name), max(column_name), sum(column_name)`<br /><br />**Tip:** For a Torque category layer that is created dynamically with `carto.createLayer`, the SQL query must explicitly include how to build the torque_category column. You must include both the `sql` and `table_name` parameters. See this [createLayer with torque category layer](https://gist.github.com/danicarrion/dcaf6f00a71aa55134b4) example.<br /><br />**Note:** `column_name` is a column that contains an integer or number for each category in the map. If you are applying CartoCSS with the CARTO Editor, you can select a text column. When applied as the `CDB_Math_Mode` value, the [statistical mode](https://en.wikipedia.org/wiki/Mode_%28statistics%29), or category, of the most occurrences over time appear as a Torque pixel. If a pixel returns multiple values, the colors may overlap and render incorrectly.<br /><br />**Tip:** An advanced math trick to properly blend colors is to apply the `sum(distinct(column_name));` value. This enables you to render pixels in categories and apply colors to each value. For example, when all pixel values=1, the sum of distinct is 1. When all pixels values=2, the sum of distinct is 2. When the values are mixed with either 1 or 2, the sum of distinct is 3. You can then apply `marker-fill` colors to each value category (value=1, value=2, value=3). If you have more than two values in your column, use these guidelines to figure out your own math trick to render the data.<br /><br />Additionally, you can use the `column_name` value to diverge values (i.e. when there is only one record of category 1 and 99 records of category 2).<br /><br />**Tip:** Since Torque does not return negative values, set this value high, i.e. 100. For example, `"100+sum(floor(category_name*1.5)-2)";` converts values to negative and positive values and sums them up. The greater the negative value, the greater the preference to category 1 in the pixel. The greater the positive value, the greater the preference to category 2.
+Related Examples | Wiki page about [how spatial aggregation works](https://github.com/CartoDB/torque/wiki/How-spatial-aggregation-works).
+
+The following example displays CartoCSS properties with a Torque Category map.
+
+{% highlight scss %}
+/** torque_cat visualization */
+
+Map {
+  -torque-frame-count:1024;
+  -torque-animation-duration:30;
+  -torque-time-attribute:"dates";
+  -torque-aggregation-function:"CDB_Math_Mode(torque_category";
+  -torque-resolution:2;
+  -torque-data-aggregation:linear;
+}
+{% endhighlight %}

doc/developer-center/cartocss/03-best-practices.md

@@ -0,0 +1,319 @@
+## CartoCSS Best Practices
+
+While there are many ways to apply the same visual effects with CartoCSS properties, this section describes the most efficient and intuitive methods for structuring your CartoCSS syntax.
+
+You can apply CartoCSS properties to the overall map style, or to specific map symbolizers (such as markers and points). Sometimes, applying properties to a symbolizer is not the most effective workflow for enhancing your overall map style. Other times, applying a style to the overall map is not rendered if there is no default value defined, and thus, not needed. For example, see how  [composite operations](#composite-operation-effects) can be used for color blending, based on style or symbolizer.
+
+When applying CartoCSS syntax, it helps to understand how values are applied to your map:
+
+- The source is where the style is applied (either as a value or as a symbolizer property)
+- The destination is the effect on the rest of the map, underneath the source
+- Any layers that appear above the source are unaffected by the applied style and are rendered normally 
+- Typically, you apply CartoCSS properties to different layers on a map. You can add multiple styles and values for each layer
+
+- Alternatively, you can apply CartoCSS by nesting categories and values. Categories contain multiple values listed under the same, single category using brackets `{ }`. This enables you visualize all of the styling elements applied to the overall map or to individual symbolizers, and avoid adding any redundant or unnecessary parameters. This is the suggested method if you are applying styles to a multi-scale map.
+
+**Note:** Be mindful when applying styles to a map with multiple layers. Instead of applying an overall style to each map layer, apply the style to one layer on the map using this nested structure. For example, suppose you have a map with four layers, you can define zoom dependent styling as a nested value in one map layer. You do not have to go through each layer of the map to apply a [zoom style](#example-5-zoom-based-styling-with-cartocss). Using the nested structure allows you to apply all of the styling inside the brackets `{ }`. This is a more efficient method of applying overall map styling.
+
+Each of the examples below produces the same visual effect. Note how the CartoCSS syntax is structured.
+
+### Example 1: CartoCSS syntax structured by point
+
+Marker fill values are applied to the overall style of the map. Each map point is labeled `#continent_points[continent="name"] {` and contains its own marker-fill style.
+
+{% highlight scss %}
+#continent_points {
+  marker-fill-opacity: 0.9;
+  marker-line-color: #FFF;
+  marker-line-width: 1;
+  marker-line-opacity: 1;
+  marker-placement: point;
+  marker-type: ellipse;
+  marker-width: 10;
+  marker-allow-overlap: true;
+}
+#continent_points[continent="Africa"] {
+  marker-fill: #A6CEE3;
+}
+#continent_points[continent="Antarctica"] {
+  marker-fill: #1F78B4;
+}
+#continent_points[continent="Asia"] {
+  marker-fill: #B2DF8A;
+}
+#continent_points[continent="Australia"] {
+  marker-fill: #33A02C;
+}
+#continent_points[continent="Europe"] {
+  marker-fill: #FB9A99;
+}
+#continent_points[continent="North America"] {
+  marker-fill: #E31A1C;
+}
+#continent_points[continent="Oceania"] {
+  marker-fill: #FDBF6F;
+}
+#continent_points[continent="South America"] {
+  marker-fill: #FF7F00;
+}
+{% endhighlight %}
+
+### Example 2: CartoCSS syntax structured by category
+
+Marker fill values are applied to the overall style of the map. `marker-line-opacity`, `marker-placement`, and `marker-type` are removed from the overall map style, since the default values for these properties do not render any styling effects, they are not necessary.
+
+**Tip:** In some cases, default values for CartoCSS properties render no styling effects on your map. If you apply CartoCSS syntax with the default values `none``undefined`, the map appears the same with or without these properties. Ensure to define values for properties that apply no default styling.
+
+Each point is categorized as `[continent="name"] {` and contains its own marker-fill style. 
+*You do not need to preface each point with the `#continent_points` label.* Note how syntax highlighting is applied to clearly indicate the category.
+
+{% highlight scss %}
+#continent_points {
+  marker-fill-opacity: 0.9;
+  marker-line-color: #FFF;
+  marker-line-width: 1;
+  marker-width: 10;
+  marker-allow-overlap: true;
+
+  [continent="Africa"] {
+    marker-fill: #A6CEE3;
+  }
+  [continent="Antarctica"] {
+    marker-fill: #1F78B4;
+  }
+  [continent="Asia"] {
+    marker-fill: #B2DF8A;
+  }
+  [continent="Australia"] {
+    marker-fill: #33A02C;
+  }
+  [continent="Europe"] {
+    marker-fill: #FB9A99;
+  }
+  [continent="North America"] {
+    marker-fill: #E31A1C;
+  }
+  [continent="Oceania"] {
+    marker-fill: #FDBF6F;
+  }
+  [continent="South America"] {
+    marker-fill: #FF7F00;
+  }
+}
+{% endhighlight %}
+
+### Example 3: CartoCSS syntax structured by @ values
+
+Apply the @ symbol to lists of all the color values for your categories. CartoCSS syntax is structured so that you can apply all your color changes in one section `@name: color;` and reference the point style within the category label `marker-fill: @name;`. This enables you to visualize exactly where your marker-fill values are located, in addition to the overall map styles.
+
+{% highlight scss %}
+@africa: #A6CEE3;
+@antarctica: #1F78B4;
+@asia: #B2DF8A;
+@australia: #33A02C;
+@europe: #FB9A99;
+@northamerica: #E31A1C;
+@oceania: #FDBF6F;
+@southamerica:#FF7F00; 
+
+#continent_points {
+  marker-fill-opacity: 0.9;
+  marker-line-color: #FFF;
+  marker-line-width: 1;
+  marker-width: 10;
+  marker-allow-overlap: true;
+
+  [continent="Africa"] {
+   marker-fill: @africa;
+  }
+  [continent="Antarctica"] {
+    marker-fill: @antarctica;
+  }
+  [continent="Asia"] {
+    marker-fill: @asia;
+  }
+  [continent="Australia"] {
+    marker-fill: @australia;
+  }
+  [continent="Europe"] {
+    marker-fill: @europe;
+  }
+  [continent="North America"] {
+    marker-fill: @northamerica;
+  }
+  [continent="Oceania"] {
+    marker-fill: @oceania;
+  }
+  [continent="South America"] {
+    marker-fill: @southamerica;
+  }
+}
+{% endhighlight %}
+
+### Example 4: Multiple Symbolizers for a Map Layer
+
+In some cases, you may need to apply multiple symbolizers to one map layer. For example, a point layer typically contains marker syntax. You can also attach [other compatible symbolizer](#cartocss-symbolizer) properties, to achieve a desired styling effect.
+
+Enter a double-colon symbol :: to indicate a duplicate map layer without actually adding a new layer to your map. This dummy layer created through CartoCSS styling acts as an attachment, enabling you to apply multiple symbolizers to the selected layer.
+
+Suppose you have a point symbol and want to put a glowing halo around it. You need CartoCSS values for the point style and CartoCSS values for the glowing halo. 
+
+- Add the styling for the points in your map layer
+- Add a second, attachment, layer of the same data and create the styling for the halo
+
+{% highlight scss %}
+/** bottom attachment of the glowing halo **/
+
+#layer {
+ marker-width: 20;
+ marker-fill: teal;
+ marker-fill-opacity: 1;
+ marker-line-color: #FFF;
+ marker-line-width: 0;
+ marker-line-opacity: 1;
+ marker-placement: point;
+ marker-type: ellipse;
+ marker-allow-overlap: true;
+}
+{% endhighlight %}
+
+{% highlight scss %}
+/** top layer of the symbol**/
+
+#layer {
+ marker-width: 10;
+ marker-fill: #FFB927 ;
+ marker-fill-opacity: 0.9;
+ marker-line-color: #FFF;
+ marker-line-width: 0;
+ marker-line-opacity: 1;
+ marker-placement: point;
+ marker-type: ellipse;
+ marker-allow-overlap: true;
+}
+{% endhighlight %}
+
+Alternatively, you can achieve the same effect by using a single map layer and inserting the double-colon symbol `::` You can type any text to describe the styling element that is being applied.
+
+{% highlight scss %}
+#layer {
+  
+ //bottom layer of symbol
+  ::halo {
+    marker-width: 20;
+    marker-fill: teal;
+    marker-fill-opacity: 1;
+    marker-line-color: #FFF;
+    marker-line-width: 0;
+    marker-line-opacity: 1;
+    marker-placement: point;
+    marker-type: ellipse;
+    marker-allow-overlap: true;
+  }
+
+//top layer of symbol  
+   marker-width: 10;
+   marker-fill: #FFB927 ;
+   marker-fill-opacity: 0.9;
+   marker-line-color: #FFF;
+   marker-line-width: 0;
+   marker-line-opacity: 1;
+   marker-placement: point;
+   marker-type: ellipse;
+   marker-allow-overlap: true;  
+}
+{% endhighlight %}
+
+- The ::halo describes the style elements that you are applying to the halo
+
+- The default, top layer describes the style elements that you are applying to the point
+
+**Note:** Similar to how map layers are rendered, symbolizers are rendered from bottom to top. To see an example, view this live map which is using [multiple symbolizers](https://mamataakella.carto.com/builder/36cb22c8-3334-11e6-ad49-0ecfd53eb7d3/embed) applied to point styles.
+
+### Example 5: Zoom-Based Styling with CartoCSS
+
+Zoom-based styling refers to the ability to change what is displayed on a map, or how it is visualized, based on the zoom-level. When you zoom in or out of the Map View, certain features or data (such as streets, waterways, or labels) appear or fade away.
+
+For example, apply the _STAMEN TONER_ [basemap](https://carto.com/learn/guides/styling/basemaps-for-rendering-map-backgrounds) to your map and notice how buildings and features are shown or hidden, depending on the zoom level. You can apply the same functionality to your data by applying zoom-based styling with CartoCSS.
+
+Whenever CartoCSS properties are enclosed in brackets `[zoom] { }`, this indicates that zoom-based styling should be activated when the map meets the specified zoom level. It enforces rules for when and how data appears on your map. For example, you can specify conditional styling to:
+
+- Change the size of marker symbols at a specified zoom level.
+- Show or hide text labels at a specified zoom level and/or define how labels appear. For more details about text labels and zoom-based styling, see the [_Applying Text Labels to your Data_](https://carto.com/learn/guides/styling/applying-text-labels-to-your-data) Guide in CARTO Builder documentation.
+
+In the following example, the `[zoom]` value indicates that the size of the geometry should change when zoom level `4` is reached. [Square brackets] indicate zoom-based styling, while the {curly brackets} indicate styling conditions to be applied at that zoom level.
+
+{% highlight scss %}
+ [zoom = 4] {marker-width: 6}
+{% endhighlight %}
+
+**Tip:** You can specify the logical operator for the zoom level (greater than `>`, less than `<`, equal to `=` or a combination of those).
+
+The following syntax displays how the entire layer is styled in CartoCSS. Layer styling shows that the default `marker-width` is `3`. When the zoom level is equal to `4`, or equal to/greater than `5`, the marker-width values change on your visualization. This styling increases the geometry size as the map is zoomed.
+
+{% highlight scss %}
+#layer{
+  marker-fill-opacity: 0.9;
+  marker-line-color: #FFF;
+  marker-line-width: 0;
+  marker-line-opacity: 1;
+  marker-placement: point;
+  marker-type: ellipse;
+  marker-width: 3;
+  marker-fill: #FF6600;
+  marker-allow-overlap: true;
+  [zoom = 4] {marker-width: 6}
+  [zoom = 5] {marker-width: 12}
+  [zoom > 5] {marker-width: 16}
+}
+{% endhighlight %}
+
+Similarly, you can use the [attachment method](#example-4-multiple-symbolizers-for-a-map-layer) to apply multiple zoom-based styling parameters to a layer.
+
+{% highlight scss %}
+#layer[type='City'][zoom>=4]{
+ ::inner{
+   marker-fill-opacity: 1;
+   marker-fill:#2b2b2b;
+   marker-line-width: 0;
+   marker-line-opacity: 0.65;
+   marker-placement: point;
+   marker-type: ellipse;
+   marker-width: 5;
+   marker-line-color: #2b2b2b;
+   marker-allow-overlap: true;
+ }
+{% endhighlight %} 
+
+### Adding Comments to your Code
+
+If you are just learning CartoCSS, it might be useful to add comments next to lines of your CartoCSS code. For example, you can add comments to describe a specific hex color, the default value for a property, the available values, and so on. 
+
+Enter comments by using the following format in your CartoCSS code. _Note the required spacing_:
+
+`cartocss-property; /* comment */`
+
+##### Example of Comments in CartoCSS
+
+In the following example, there are user comments entered in the `marker-line-color`, `marker-placement`, `marker-width`, and `marker-fill` CartoCSS properties.
+
+{% highlight scss %}
+/** simple visualization */
+
+#month_day{
+  marker-fill-opacity: 0.9;
+  marker-line-color: #FFF; /* white */
+  marker-line-width: 1;
+  marker-line-opacity: 1;
+  marker-placement: point; /* options are point, line, interior */
+  marker-type: ellipse;
+  marker-width: 15; /* default value was 10 */
+  marker-fill: #2E5387; /* hex color is St Tropaz */
+  marker-allow-overlap: true;
+  marker-comp-op: overlay;
+}
+{% endhighlight %}
+
+As long as you are careful with the spacing, these comments will not interfere when applying CartoCSS style to your map.
+
+**Tip:** You are notified if there any errors in the CartoCSS code.

doc/developer-center/cartocss/04-errors.md

@@ -0,0 +1,18 @@
+## CartoCSS Errors
+
+Entering CartoCSS styling is simple. Most common errors are a caused by typos and missing formatting. If you are using CartoCSS in the Builder, you are notified which line of syntax contains an error. You can also click the *undo* and *redo* arrow buttons after entering code changes with CartoCSS.
+
+<span class="wrap-border"><img src="../img/cartocss/errors.jpg" alt="Undo Redo CartoCSS Builder buttons" /></span>
+
+Always apply the following format when entering CartoCSS code and be mindful of any quotes, brackets, and end line semi-colons.
+
+{% highlight scss %}#layer_name {
+  cartocss-property-name: value;
+  cartocss-property-name: value;
+  cartocss-property-name: value;
+  cartocss-property-name: value;
+}{% endhighlight %}
+
+**Note:** If you are entering CartoCSS syntax for Torque specific properties, all [Torque CartoCSS](#cartocss-properties-for-torque-style-maps) syntax is prefaced with a hypen.
+
+**Tip:** See [CartoCSS Best Practices](#cartocss-best-practices) for suggestions about how to structure your CartoCSS syntax.

doc/developer-center/cartocss/05-composite-operations.md

@@ -0,0 +1,434 @@
+## CartoCSS Composite Operations
+
+Composite operations style the way colors of overlapping geometries interact with each other. Similar to blend operations in Photoshop, these composite operations style the blend modes on your map. The main reason to use composite operations is to fine-tune how much some features in your map stand out compared to others. They are a great way to control your maps legibility.
+
+- There is a shortcut for selecting the _BLENDING_ composite operation value, directly from the STYLE options of a selected map layer
+
+	**Tip:** <a href="../img/cartocss/select_BLENDING_option.gif" target="_blank">See how to select a BLENDING `comp-op` value through the STYLE options</a>.
+
+- You can also enter CartoCSS syntax to apply the `comp-op` property with additional values
+
+	**Tip:** <a href="../img/cartocss/cartocss_comp_op.gif" target="_blank">See how to apply a `comp-op` value with CartoCSS</a>.
+
+### Effects of Composite Operations
+
+Composite operations are blending modes for your map layers. They fall into two main categories: [color](#color-blending-values) and [alpha](#alpha-blending-values), and can be applied to all non-basemap elements in your CARTO map by adding the `comp-op` value to your CartoCSS code. 
+
+Composite operations can be applied as an overall style effect, as shown in the following code:
+
+{% highlight css %}
+comp-op: multiply;
+{% endhighlight %}
+
+Or, it can be applied to the specific symbolizer property, depending on the color blending operation you are trying to achieve. For example:
+
+{% highlight css %}
+marker-comp-op: multiply;
+polygon-comp-op: color-burn;
+text-comp-op: screen;
+{% endhighlight %}
+
+- The layer (or text) that you choose the composite operation in is called the source
+
+- Its composite operation is applied to each layer beneath, which are called destination layers. In CARTO, the source layer itself needs to have a color fill, but its composite operations apply to destination layers with color or texture fills (even raster layers)
+
+	**Note:** Any layers that appear above the source are unaffected by the `comp-op` value and are rendered normally.
+
+### CartoCSS Symbolizer Values
+
+The following CartoCSS properties can be used as a blending effect on a map layer. Alternatively, these properties can be applied to invoke a composite operation effect on a particular symbolizer. For details, see [Effects of Composite Operations](#effects-of-composite-operations). Click a link to view the CartoCSS property description.
+
+[line-comp-op](#line-comp-op-keyword) | [line-pattern-comp-op](#line-pattern-comp-op-keyword)| [marker-comp-op](#marker-comp-op-keyword)
+[point-comp-op](#point-comp-op-keyword) | [polygon-comp-op](#polygon-comp-op-keyword) | [polygon-pattern-comp-op](#polygon-pattern-comp-op-keyword)
+[raster-comp-op](#raster-comp-op-keyword) | [shield-comp-op](#shield-comp-op-keyword) | [text-comp-op](/#text-comp-op-keyword)
+
+### Color Blending Values
+
+The following color blending operations can be applied with the `comp-op` property.
+
+[overlay](#overlay) | [multiply](#multiply) | [color-dodge](#color-dodge)
+[plus](#plus) | [minus](#minus) | [screen](#screen)
+[darken](#darken) | [lighten](#lighten) | [hard-light](#hard-light)
+[soft-light](#soft-light) | [grain-merge](#grain-merge) | [grain-extract](#grain-extract)
+[hue](#hue) | [saturation](#saturation) | [color](#color)
+[value](#value) | [color-burn](#color-burn) | [difference](#difference)
+[exclusion](#exclusion) | [contrast](#contrast) | [invert](#invert)
+[invert-rgb](#invert-rgb) | clear | 
+
+#### Overlay
+
+Overlay is a color blend mode that combines [multiply](#multiply) and [screen](#screen) composite operations. Black appears as dark, as it originally is in its layer; white appears as bright, as it originally is in its layer. How purely other colors are rendered depends on how close they are to white or black. The closer a color is in value to pure midtone gray, the less it will appear. Use this when you want to show both light and dark in your overlapping layers, for example if you are using a textured polygon fill and want the highlights and shadows to appear through another layer. Notice in the example below how the gray-equivalent areas take on the color of the source layer.
+
+{% highlight css %}
+marker-comp-op: overlay;
+{% endhighlight %}
+
+![overlay](../img/cartocss//overlay.jpg)
+
+#### Multiply
+
+Multiply literally multiplies the color of the top layer by the color of each layer beneath, which typically results in the overlapping areas become darker.
+
+A layers color is made of a mix of red, green and blue color channels. Each channel is assigned a percentage decimal value from 0 to 1. If all channels had a 0 value, the color is completely black; if the value is 1, the color is completely white. Multiply takes these channel numbers for one layer and multiplies them with the channel numbers of another. Your colors will often get darker which multiplying two decimal numbers together gives you a smaller decimal. The result is closer to 0 (black). Multiplying 1 (white) by another value will give you that other value, so the area where white mixes with another color will become that other color. Multiplying any color by 0 (black) will always render black.
+
+Imagine it like layering colored sheets of cellophane over one another; white disappears, black stays black. Use this when you want to darken overlapping areas in your map.
+
+![multiply](../img/cartocss/multiply.jpg)
+
+Choosing multiply as the Blending option adds the following CartoCSS code:
+
+{% highlight css %}
+marker-comp-op: multiply;
+{% endhighlight %}
+
+#### Color-Dodge
+
+The color-dodge color blend mode is similar to screen but the overall effect is more extreme. Your elements become much brighter (except if your source layer is black). Darker areas are tinted towards the source color. Use this when you want to have a major lightening effect with extreme contrast between your layers, without much detail showing.
+
+{% highlight css %}
+marker-comp-op: color-dodge;
+{% endhighlight %}
+
+![color-dodge](../img/cartocss/color_dodge.jpg)
+
+A good reason to lighten a map element is to reduce how much it visually competes with more important map features. For example, see what graticules look like over polygons in [this map,](http://bit.ly/1Y75upF) when _Screen_ is applied:
+
+![screen-use-case](../img/cartocss/screen-use-case.png)
+
+#### Plus
+
+The plus composite operation adds the color channel values of the source with the destinations. Visually, it adds the sources color to the darkest parts of the destination, and brightens the lighter parts, but tinted towards the source color. If you add a source color where red is the dominant color channel to the destinations red green and blue color channels, the dominant color in the result will be red. The overall effect is brighter than color-dodge. Lighter source colors effect the destination layer more than dark ones. A black source layer will have no effect; a white one will paint the whole destination layer white in the area of overlap.
+
+{% highlight css %}
+marker-comp-op: plus;
+{% endhighlight %}
+
+![plus](../img/cartocss/plus.jpg)
+
+#### Minus
+
+Minus works the same way as plus, but instead of adding the color channel values it subtracts them. For example, if your source layer is mostly red, it will subtract this from the destination layers so the overall color is mostly blue and green. This darkens the destination layer more extremely than color-burn, and is also more tinted towards the source color.
+
+{% highlight css %}
+marker-comp-op: minus;
+{% endhighlight %}
+
+![minus](../img/cartocss/minus.jpg)
+
+#### Screen
+
+Similar to [Multiply](#multiply), screen multiplies the overlapping areas. Unlike multiply, it subtracts the multiplied color channel numbers from their added value to invert them. This makes the overlapping areas brighter. If white is used, it will not change appearance. Black areas will disappear. Use this when you want to lighten overlapping areas in your map.
+
+{% highlight css %}
+marker-comp-op: screen;
+{% endhighlight %}
+
+![screen](../img/cartocss/screen.jpg)
+
+#### Darken
+
+Darken has a similar effect to multiply, but is more extreme. As it applies the color from the source layer to the destination layers, it compares each to find the darkest-colored pixels and keeps those. In the example below displays the **darken** composite operation in the top circle layer. Notice how only the hillshade shadows and black line show through from the destination layers, because all other elements have lighter-colored pixels than the circle. All pixel colors that are lighter than the top circle take on the circle's color. Use this when you want a darken effect that shows original color in the darkest areas of overlap, or when you want less detail than is shown in multiply.
+
+{% highlight css %}
+marker-comp-op: darken;
+{% endhighlight %}
+
+![darken](../img/cartocss/darken.jpg)
+
+#### Lighten
+
+Lighten works the same way as darken, but inversely. The lightest-colored pixels from each layer are kept, and if pixels are darker than the source layer, then the source layer color replaces them. This can be useful when you want to change the color of your overlapping area's shadows.
+
+{% highlight css %}
+marker-comp-op: lighten;
+{% endhighlight %}
+
+![lighten](../img/cartocss/lighten.jpg)
+
+#### Hard Light
+
+Hard Light is another color comp-op that you can use with CartoCSS:
+
+{% highlight css %}
+marker-comp-op: hard-light;
+{% endhighlight %}
+
+It works similarly to soft light, but is more extreme. Instead of using screen and multiply it uses color-dodge and color-burn, although not applied as strongly as with those comp-ops.
+
+![hard-light](../img/cartocss/hard-light.jpg)
+
+#### Soft Light
+
+Soft Light will either screen or multiply the destination layer colors, depending on the color of the source layer. If the source color is darker than 50% gray, the multiply effect will be used. If it is lighter than 50%, then screen will be used. Soft-light's effects are not applied as strongly as multiply's or screen's though, so the resulting colors are less extremely tinted. Usually darks will not be pure black and highlights are not pure white.
+
+{% highlight css %}
+marker-comp-op: soft-light;
+{% endhighlight %}
+
+![soft-light](../img/cartocss/soft-light.jpg)
+
+#### Grain-Merge
+
+Grain-merge is the opposite of grain-extract. It adds the source and destination layer color channel values together, then subtracts 128. When used with textured destination layers, the overall visual effect shows the destination layers texture in the source layer overlap area, but with colors tinted towards the source layers.
+
+{% highlight css %}
+marker-comp-op: grain-merge;
+{% endhighlight %}
+
+![grain-merge](../img/cartocss/grain-merge.jpg)
+
+#### Grain-Extract
+
+Grain-extract subtracts destination layer color channel values from the source layer, and then adds 128. When used with textured destination layers, the overall visual effect shows the destination layers texture in the source layer overlap area, but with a brightened film-negative effect.
+
+{% highlight css %}
+marker-comp-op: grain-extract;
+{% endhighlight %}
+
+![grain-extract](../img/cartocss/grain-extract.jpg)
+
+#### Hue
+
+Hue keeps the color brightness and saturation levels of the destination layers, but renders a result with the same hue as the source layer.
+
+{% highlight css %}
+marker-comp-op: hue;
+{% endhighlight %}
+
+![hue](../img/cartocss/hue.jpg)
+
+#### Saturation
+
+Saturation keeps the hue and brightness levels of the destination layers, but renders a result with the same level of saturation as the source layer. If you are using white in the source layer, there will be less saturation in the result. Black will render the highest level of saturation. Color half way between them, gray, will not have an effect.
+
+{% highlight css %}
+marker-comp-op: saturation;
+{% endhighlight %}
+
+![saturation](../img/cartocss/saturation.jpg)
+
+#### Color
+
+Color keeps the source layer's hue and saturation levels, but renders a result with the brightness of the destination layers.
+
+{% highlight css %}
+marker-comp-op: color;
+{% endhighlight %}
+
+![color](../img/cartocss/color.jpg)
+
+#### Value
+
+Value keeps the brightness levels of the source, but renders a result with the hue and saturation levels of the destination layers.
+
+{% highlight css %}
+marker-comp-op: value;
+{% endhighlight %}
+
+![value](../img/cartocss/value.jpg)
+
+#### Color-Burn
+
+Color-burn works similarly to color-dodge, but has a darkening effect. It increases the contrast between source and destination layers, with pixels in your overlapping area tinted towards the source color. Use this when you want a darkening effect with more contrast than multiply or darken.
+
+{% highlight css %}
+marker-comp-op: color-burn;
+{% endhighlight %}
+
+![color-burn](../img/cartocss/color-burn.jpg)
+
+For a good example of using darkening effects, view [this election map](https://team.carto.com/u/stuartlynn/viz/ab4541a4-767b-11e5-b637-0ea31932ec1d/public_map). Its lower layer shows population density with gray scale colors, and its upper layer shows U.S. political parties in red and blue. When you use a darkening composite operation, the polygons show voting results by political party, modulated by the population density.
+
+![darken-use-case](../img/cartocss/darken-use-case.png)
+
+#### Difference
+
+The difference blending mode compares the source to the destination layers and finds the brightest color areas for each color channel. It gets the difference between color channel numbers by subtracting them from each other, and taking that absolute value. Using pure white inverts the colors it is blending with; black has no effect. In areas where the colors being compared are very close in value, the result is black.
+
+{% highlight css %}
+marker-comp-op: difference;
+{% endhighlight %}
+
+![difference](../img/cartocss/difference.jpg)
+
+#### Exclusion
+
+Exclusion is similar to difference, but less extreme. In areas where the colors being compared are very close in value, the result is lighter than black. For example, notice the gray areas where the circle is the same color as the layers beneath, in following map:
+
+{% highlight css %}
+marker-comp-op: exclusion;
+{% endhighlight %}
+
+![exclusion](../img/cartocss/exclusion.jpg)
+
+#### Contrast
+
+Contrast magnifies the difference between the dark and light areas of your overlapping layers. If the source layer color is lighter than 50% gray, the destination layers will show through the source layer with decreased contrast. If the source is darker than 50% gray, the destination layers will show through the source layer with increased contrast. Besides making lighter areas brighter and darker areas darker, this has the visual effect of erasing fine detail.
+
+{% highlight css %}
+marker-comp-op: contrast;
+{% endhighlight %}
+
+![contrast](../img/cartocss/contrast.jpg)
+
+Use contrast effects when you are trying to control how both dark and light elements in your map stand out from the other elements, or blend in with them better. For example, compare the dark red and blue areas to the lighter colored areas in the [the map](http://bit.ly/1M4v9tW) below. Notice how the gray county outlines do not stand out as well against the darker red and blue backgrounds.  
+
+![overlay-use-case-1](../img/cartocss/overlay-use-case-1.png)
+
+Now, look how much more evenly the county lines blend with background colors in [this map](http://bit.ly/1M4v9tW). We have also kept the white state outlines.
+
+![overlay-use-case-2](../img/cartocss/overlay-use-case-2.png)
+
+#### Invert
+
+Invert turns each RGB channel color into its opposite. Areas that look black originally will turn white, areas that look red will turn green, blues will turn orange, yellows will turn purple.
+
+{% highlight css %}
+marker-comp-op: invert;
+{% endhighlight %}
+
+![invert](../img/cartocss/invert.jpg)
+
+#### Invert-RGB
+
+Invert-rgb also inverts color channel colors, but then tints them towards the source color.
+
+{% highlight css %}
+marker-comp-op: invert-rgb;
+{% endhighlight %}
+
+![invert-rgb](../img/cartocss/invert-rgb.jpg)
+
+### Alpha Blending Values
+
+The following alpha blending values can be applied with the `comp-op` property and combine different levels of source transparency with destination layers. These are useful for masking parts of one layer with another. They use the shape of the layer to show or hide the rest of the rendered map, as opposed to altering the color of a layer.
+
+**Tip:** Alpha values are useful when applying the `comp-op` property to the overall map style [effect](#composite-operation-effects). As an additional resource for working with alpha composition methods, see [Duff-Porter Alpha Composition Methods](http://www.imagemagick.org/Usage/compose/#duff-porter).
+
+[src](#src) | [dst](#dst) | [src-over](#src-over)
+[dst-over](#dst-over) | [src-in](#src-in) | [dst-in](#dst-in)
+[src-out](#src-out) | [dst-out](#dst-out) | [src-atop](#src-atop)
+[dst-atop](#dst-atop) | [xor](#xor) | [clear](#clear)
+
+#### Src
+
+Src is an alpha composite operation that keeps the full transparency of the source layer. Whether the source layer is above or below layers using other composite operations, it will show through completely opaque.
+
+{% highlight css %}
+marker-comp-op: src;
+{% endhighlight %}
+
+![src](../img/cartocss/src.jpg)
+
+#### Dst
+
+Dst is an alpha composite operation that keeps the full transparency of the destination layers. The source layer becomes invisible in areas where it is overlapping with the destination layers.
+
+{% highlight css %}
+marker-comp-op: dst;
+{% endhighlight %}
+
+![dst](../img/cartocss/dst.jpg)
+
+#### Src-over
+
+Src-over keeps the full transparency of both the source and destination layers. The visual effect is that the source layer shows on top of all layers involved in the overlap area.
+
+{% highlight css %}
+marker-comp-op: src-over;
+{% endhighlight %}
+
+![src-over](../img/cartocss/src-over.jpg)
+
+#### Src-in
+
+Src-in only shows the part of the source layer that intersects with the destination layer.
+
+{% highlight css %}
+marker-comp-op: src-in;
+{% endhighlight %}
+
+![src-in](../img/cartocss/src-in.jpg)
+
+#### Src-out
+
+Src-out only shows the part of the source layer that does not intersect with the destination layer. The destination layers are also not drawn within the area of overlap.
+
+{% highlight css %}
+marker-comp-op: src-out;
+{% endhighlight %}
+
+![src-out](../img/cartocss/src-out.jpg)
+
+#### Src-atop
+
+Src-atop makes sure that the source layer is shown at the top of all layers involved in the composite operation, within the area of overlap.
+
+{% highlight css %}
+marker-comp-op: src-atop;
+{% endhighlight %}
+
+![src-atop](../img/cartocss/src-atop.jpg)
+
+#### Dst-over
+
+Dst-over also keeps the full transparency of the source and destination layers, but its effect is that the source is shown beneath all destination layers.
+
+{% highlight css %}
+marker-comp-op: dst-over;
+{% endhighlight %}
+
+![dst-over](../img/cartocss/dst-over.jpg)
+
+#### Dst-in
+
+Inside the overlap area, dst-in only shows the destination layer.
+
+{% highlight css %}
+marker-comp-op: dst-in;
+{% endhighlight %}
+
+![dst-in](../img/cartocss/dst-in.jpg)
+
+#### Dst-out
+
+Dst-out only shows the part of the destination layer that does not overlap with the source layer. It also removes the source layer's color.
+
+{% highlight css %}
+marker-comp-op: dst-out;
+{% endhighlight %}
+
+![dst-out](../img/cartocss/dst-out.jpg)
+
+#### Dst-atop
+
+Dst-atop shows the destination layers on top of the source layer, in the places where they overlap.
+
+{% highlight css %}
+marker-comp-op: dst-atop;
+{% endhighlight %}
+
+![dst-atop](../img/cartocss/dst-atop.jpg)
+
+#### Xor
+
+Xor shows both the source and destination layers, but only the parts that do not overlap each other.
+
+{% highlight css %}
+marker-comp-op: xor;
+{% endhighlight %}
+
+![xor](../img/cartocss/xor.jpg)
+
+#### Clear
+
+The clear composite operation acts as an eraser. It makes all pixels transparent in the area where source and destination layers overlap.
+
+{% highlight css %}
+marker-comp-op: clear;
+{% endhighlight %}
+
+![clear](../img/cartocss/clear.jpg)
+
+*[Contains public sector information licensed under the Open Government Licence v3.0.](http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/)
+* Null Island topography taken from USGS National Map. [Map services and data available from U.S. Geological Survey, National Geospatial Program.](http://viewer.nationalmap.gov/basic/?basemap=b1&category=ned,nedsrc&title=3DEP%20View)

doc/developer-center/import-api/guides/01-quickstart.md

@@ -0,0 +1,81 @@
+## Quickstart
+
+For this example (and the rest of the ones illustrated here) we will be using a command-line tool known as `cURL`. For more info about this tool see [this blog post](http://quickleft.com/blog/command-line-tutorials-curl) or type `man curl` in bash.
+
+### Uploading a Local File
+
+Suppose you have a CARTO account whose username is *documentation*, and you want to upload a local file named *prism_tour.csv* (located in the *Documents* folder). This requires that you execute the following command on a Terminal window:
+
+#### Call
+
+```bash
+curl -v -F file=@/home/documentation/Documents/prism_tour.csv
+"https://documentation.carto.com/api/v1/imports/?api_key=3102343c42da0f1ffe6014594acea8b1c4e7fd64"
+```
+
+Note that the *api_key* element has an alphanumeric value that is exclusive to the *documentation* CARTO account.
+
+The response to this request appears in the following format, where a successful value indicates that the import process is enqueued:
+
+#### Response
+
+```
+{
+  "item_queue_id": "efa9925c-31dd-11e4-a95e-0edbca4b5057",
+  "success": true
+}
+```
+
+The `item_queue_id` value is a unique identifier that references the import process. Once this process has started, its information can be obtained doing a request to the imports endpoint as explained in the ["Check the status of an import process]({{site.importapi_docs}}/guides/standard-tables/#check-the-status-of-an-import-process) section.
+
+### Uploading from a Remote URL
+
+Suppose you have a server at the hostname *examplehost.com*, with a csv named *sample.csv* already uploaded. Creating a table from the URL requires that you execute the following command on a Terminal window:
+
+#### Call
+
+```bash
+curl -v -H "Content-Type: application/json" -d '{"url":"https://examplehost.com/sample.csv"}'
+"https://documentation.carto.com/api/v1/imports/?api_key=3102343c42da0f1ffe6014594acea8b1c4e7fd64"
+```
+
+The response to this request returns the following format, returning a success value if the import process is correctly enqueued:
+
+#### Response
+
+```
+{
+  "item_queue_id": "efa9925c-31dd-11e4-a95e-0edbca4b5057",
+  "success": true
+}
+```
+
+### Connecting to a Database
+
+Suppose you have an external MySQL database named _mydb_ that you want to connect to. For the purpose of this example, you will access a server with the address of _mydbserver.com_. Your username is _myuser_, and your password is _mypass_. Connect a CARTO dataset to a remote table, named _mytable_, by executing the following command on a Terminal window:
+
+#### Call
+
+```bash
+curl -v -H "Content-Type: application/json" -d '{
+  "connector": {
+    "provider": "mysql",
+    "connection": {
+      "server":"mydatabaserver.com",
+      "database":"mydb",
+      "username":"myuser,
+      "password":"mypass"
+    },
+    "table": "mytable"
+  }
+}' "https://documentation.carto.com/api/v1/imports/?api_key=3102343c42da0f1ffe6014594acea8b1c4e7fd64"
+```
+
+#### Response
+
+```
+{
+  "item_queue_id": "tyf9925c-32dd-11f4-a95f-0fdbca4b5058",
+  "success": true
+}
+```

doc/developer-center/import-api/guides/02-general-concepts.md

@@ -0,0 +1,33 @@
+## General Concepts
+
+The following concepts are the same for every endpoint in the API except when it is noted explicitly.
+
+
+### Auth
+
+Manipulating data on a CARTO account requires prior authentication using a unique identifier as a password. For the import API, a special identifier known as the API Key is used as a proof of authentication for each user account to authorize access to its data.
+
+To execute an authorized request, `api_key=YOURAPIKEY` should be added to the request URL. This parameter can be also passed as a POST parameter. We **strongly advise** using HTTPS when you are performing requests that include your `api_key`.
+
+---
+
+### Errors
+
+Errors are reported using standard HTTP codes and extended information encoded in the HTML language, as shown in the following example:
+
+```html
+<html>
+  <head>
+    <title>411 Length Required</title>
+  </head>
+  <body bgcolor="white">
+    <center>
+      <h1>411 Length Required</h1>
+    </center>
+    <hr>
+    <center>nginx</center>
+  </body>
+</html>
+```
+
+Depending on the specific case, additional information regarding the error may be presented. See support section for details about known error codes and solutions.

doc/developer-center/import-api/guides/03-standard-tables.md

@@ -0,0 +1,212 @@
+## Standard Tables
+
+A standard import stores the data you upload from files with valid formats, creating tables at CARTO. These are the default tables used to store the data of the uploaded files (that will be used to create datasets and maps). Any CARTO user may create, manipulate, and delete their own datasets.
+
+### Upload file
+
+##### Definition
+
+```bash
+POST api/v1/imports 
+```
+
+##### Params
+
+Param | Description
+--- | ---
+api_key | The target CARTO account API key.
+file | When importing local files, you need to perform a POST with a file (see the call with cURL example in this section).
+url | When importing remote files, the full URL to the publicly accessible file.
+type_guessing | If set to `false` disables field type guessing (for Excel and CSVs). Optional. Default is `true`.
+quoted_fields_guessing | If set to `false` disables type guessing of CSV fields that come inside double quotes. Optional. Default is `true`.
+content_guessing | Set to `true` to enable content guessing and automatic geocoding based on results. Currently, this only implements geocoding of countries, cities and IP addresses. Optional. Default is `false`.
+create_vis | Set to `true` to flag the import so that when it finishes, it creates a Map automatically after importing the Dataset. Optional. Default is `false`.
+collision_strategy | Determines the behavior when importing a dataset that has the same name as an existing table. By default, it is imported and renamed with a sequential number (`mytable`,  `mytable_1`...). Optional. If you set `collision_strategy=skip`, the table with the matching name will not be imported. If you set `collision_strategy=overwrite`, it will replace the table with the matching name, but only if the schemas are compatible.
+privacy | Used to set the privacy settings of the table or tables resulting from the import. If **create_vis** is set to true, the resulting visualization privacy settings will also be determined by this parameter. **privacy** can be set to:
+--- | ---
+<i class="Icon Icon--s5 Icon--cGrey Icon--mAlign Icon--indent"></i> public | The resulting table or visualization can be viewed by anyone.
+<i class="Icon Icon--s5 Icon--cGrey Icon--mAlign Icon--indent"></i> private | The resulting table or visualization can only be viewed by the uploader.
+<i class="Icon Icon--s5 Icon--cGrey Icon--mAlign Icon--indent"></i> link | The resulting table or visualization can only be viewed through a private link shared by the uploader.
+table_name | Used to duplicate one of your existing tables. **Do not mix with File/URL imports**.
+table_copy | Similar to *table_name*, internally used for table copying. **Do not set**.
+table_id | Internal usage for table migrations. **Do not set**.
+append | Reserved for future usage. **Do not set**.
+sql | Used to create a new table from a SQL query applied to one of your tables. **Do not mix with File/URL imports**.
+service_name | Used to upload from datasources, indicates which datasource to use. Check [here](https://github.com/CartoDB/cartodb/tree/master/services/datasources/lib/datasources) for an updated list of available datasources to use. **Intended for CARTO Builder usage**.
+service_item_id | Used to upload from datasources and indicates data of the datasource. Check [here](https://github.com/CartoDB/cartodb/tree/master/services/datasources/lib/datasources) for an updated list of available datasources to use. **Intended for CARTO Builder usage**.
+
+##### Response
+
+The response includes:
+
+Attributes | Description
+--- | ---
+item_queue_id | A unique alphanumeric identifier referencing the import process in the targeted account.
+success | A boolean value indicating whether the import process was started or not.
+
+#### Local File Upload Example
+
+##### Call
+
+```bash
+curl -v -F file=@/path/to/local/file "https://{account}.carto.com/api/v1/imports/?api_key={account API Key}"
+```
+
+##### Response
+
+```
+{
+  "item_queue_id": "9906bce0-f1a3-4b07-be71-818f4bfd7673",
+  "success": true
+}
+```
+
+#### URL Upload Example
+
+##### Call
+
+```bash
+curl -v -H "Content-Type: application/json" -d '{"url":"https://remotehost.url/path/to/remotefile"}'
+"https://{account}.carto.com/api/v1/imports/?api_key={account API Key}"
+```
+
+##### Response
+
+```
+{
+  "item_queue_id": "9906bce0-f1a3-4b07-be71-818f4bfd7673",
+  "success": true
+}
+```
+
+
+### Check the status of an import process
+
+When uploading a file for import, it may take some time due to the file's size and the additional processing on the CARTO side. Using this request, an import process state can be retrieved.
+
+##### Definition
+
+```bash
+GET /api/v1/imports/<import_id>
+```
+
+##### Params
+
+Param | Description
+--- | ---
+api_key | The target CARTO account API key.
+The import identifer | A unique alphanumeric element that identifies the import process to be retrieved. It is the *item_queue_id* element returned after running the upload request successfully.
+
+##### Response
+
+The response includes the following items:
+
+Attributes | Description
+--- | ---
+id | A unique identifier for the import process. It is the same as the *import id* provided in the request.
+user_id | A unique alphanumeric element that identifies the CARTO account user in the internal database.
+table_id | A unique alphanumeric element that identifies the created table in the internal CARTO database.
+data_type | This element identifies the service type used to import the file. Possible values are `file`, `url`, `external_table`, `query`, `table` or `datasource`.
+table_name | The final name of the created table in the targeted CARTO account. It usually has the same name as the uploaded file, unless there already exists a table with the same name (in this case, an integer number is appended to the table name).
+state | A string value indicating the current state of the importing process. It can have any of the following values: *enqueued*, *pending*, *uploading*, *unpacking*, *importing*, *guessing*, *complete*, or *failure*.
+error_code | A number corresponding to the error code in case of failure during the import process, that is, when the *success* item has a *false* value.
+queue_id | A unique identifier for the import process in the importing queue. It is the same as the *import id* provided in the request.
+tables_created_count | The number of tables that the import process generated. For multi-file uploads, this value can be greater than one. If the import process fails, its value will be `null`.
+synchronization_id | This element has a *null* value when the import is not configured as a Sync Table.
+type_guessing | A boolean indicating whether field type guessing (for Excel and CSVs) is enabled or not.
+quoted_fields_guessing | A boolean indicating whether type guessing of CSV fields inside double quotes is enabled for the data import.
+content_guessing | A boolean indicating whether content guessing and automatic geocoding is enabled for the data import.
+create_visualization | A boolean indicating whether the import process will create a map automatically or not. Its value corresponds to the import option `create_vis` chosen by the user.
+visualization_id | A unique identifier for the map created in the import process. Only applies if `create_visualization` is set to `true`.
+user_defined_limits | Internal usage for user limits.
+get_error_text | This element contains an error description to be outputted in case of a failure during the import process. It contains  the error title and description, its source (`user` or `cartodb`), and troubleshooting details.
+display_name | Similar to `table_name`. For `url` uploads, it shows the name of the file. Otherwise, it shows the import id.
+success | A boolean value indicating whether the import process succeeded (*true* or  *false*).
+warnings | A text field containing warning messages related to the import process, if applicable. 
+is_raster | A boolean value indicating whether the imported table contains raster data or not.
+
+#### Example
+
+##### Call
+
+```bash
+curl -v "https://{account}.carto.com/api/v1/imports/{import_id}?api_key={account API Key}
+```
+
+##### Response
+
+```
+{
+  id: "029a6053-b2fb-43dd-baa6-805d679c404f",
+  user_id: "ca8c5ace-d573-450b-8a43-6c7eafadd80e",
+  table_id: null,
+  data_type: "url",
+  table_name: null,
+  state: "failure",
+  error_code: 1002,
+  queue_id: "029a6053-b2fb-43dd-baa6-805d679c404f",
+  tables_created_count: null,
+  synchronization_id: null,
+  type_guessing: true,
+  quoted_fields_guessing: true,
+  content_guessing: false,
+  create_visualization: false,
+  visualization_id: null,
+  user_defined_limits: "{"twitter_credits_limit":0}",
+  get_error_text: {
+    title: "Unsupported/Unrecognized file type",
+    what_about: "Should we support this filetype? Let us know in our <a href='mailto:support@carto.com'>support email</a>!",
+    source: "user"
+  },
+  display_name: "shapefile_streets.cpg",
+  success: false,
+  warnings: null,
+  is_raster: false
+}
+```
+
+---
+
+### Retrieving a list of all the current import processes
+
+Lists the import identifiers of the files that are being imported in the targeted CARTO account.
+
+##### Definition
+
+```bash
+GET /api/v1/imports/
+```
+
+##### Params
+
+Param | Description
+--- | ---
+api_key | The target CARTO account API key.
+
+##### Response
+
+The response includes:
+
+Attributes | Description
+--- | ---
+imports | A list of unique alphanumeric identifiers referencing the import processes in the targeted CARTO account.
+success | A boolean value indicating if the request was successful.
+
+#### Example
+
+##### Call
+
+```bash
+curl -v "https://{account}.carto.com/api/v1/imports/?api_key={account API Key}"
+```
+
+##### Response
+
+```
+{
+  "imports": [
+    "1234abcd-1234-1a2b-3c4d-4321dcba5678"
+    ],
+  "success": true
+}
+```

doc/developer-center/import-api/guides/04-map-visualizations.md

@@ -0,0 +1,74 @@
+## CARTO Map Visualizations
+
+The *Export map* option enables you to download a map, and the connected dataset, as a .carto file. This is useful for downloading complete CARTO visualizations that you can share or import.
+
+**Note:** The Import API export visualization command only works for maps created from your dashboard.
+
+A cURL POST request allows you to export the visualization, which you will have to poll with a GET command until the state is `complete`.
+
+### Export a CARTO Visualization
+
+#### Call
+
+```bash
+curl -H 'Content-Type: application/json' https://{username}.carto.com/api/v3/visualization_exports\?api_key\={api_key} -X POST --data '{"visualization_id":"{visualization_id}"}'
+```
+
+##### Params
+
+Param | Description
+--- | ---
+api_key | The target CARTO account API key.
+visualization_id | A unique identifier for the map created in the export process. Only applies if `create_visualization` is set to true when the map was created.
+
+#### Response
+
+```
+{"id":"b94c26f3-fa16-4f13-b672-45ebbd5a9c95","visualization_id":"ace62506-brc8-6570-2p91-8vf3af3ftc44","user_id":"42b78090-6a11-475a-8060-0a90322752af2","state":"pending","url":null,"created_at":"2016-05-05T09:36:09+00:00","updated_at":"2016-05-05T09:36:09+00:00"}
+```
+
+_After making the POST request to create the export, it is expected that the request will take some time. You must poll the server by making a GET request, until state becomes complete._ For example:
+
+```
+curl -v -H 'Content-Type: application/json' https://{username}.carto.com/api/v3/visualization_exports/{visualization_export_id}\?api_key\={api_key} -X GET
+```
+
+Once completed, the response status changes to `complete` and displays the upload url location of the .carto visualization file:
+
+```
+{"id":"b94c26f3-fa16-4f13-b672-45ebbd5a9c95","visualization_id":"{visualization_id}","user_id":"42b78090-6a11-475a-8060-0a90322752af2","state":"complete","url":"/uploads/6a2b6fbd86e2c750160a/ace62506-brc8-6570-2p91-8vf3af3ftc44.carto","created_at":"2016-05-05T09:36:09+00:00","updated_at":"2016-05-05T09:36:13+00:00"}%
+```
+
+The response includes:
+
+Attributes | Description
+--- | ---
+id | A unique identifier for the export process. It is the same as the _export id_ provided in the request.
+vizualization_id | A unique identifier for the map created in the export process. Only applies if `create_visualization` is set to true when the map was created.
+user_id | A unique alphanumeric element that identifies the CARTO account user in the internal database.
+state | A string value indicating the current state of the export process. It can have any of the following values: _enqueued, pending, uploading, unpacking, importing, guessing, complete_, or _failure_.
+url | The **public** URL address where the file to be exported is located.
+created_at | The date time at which the visualization was created in the CARTO database.
+updated_at | The date time at which the visualization had its contents modified.
+
+##### Example
+
+Example POST request:
+
+```
+curl -v -H 'Content-Type: application/json' https://{username}.carto.com/api/v3/visualization_exports\?api_key\={api_key} -X POST --data '{"visualization_id":"9a0f4384-afe3-412a-8b09-136b7d9a4013"}'
+{"id":"72e488a6-cf0e-404d-bc7e-de9c9840aadf","visualization_id":"9a0f4384-afe3-412a-8b09-136b7d9a4013","user_id":"d80fe0f5-0465-4c4a-a2fe-1f14a93f3c5b","state":"pending","url":null,"created_at":"2016-05-20T07:01:38+00:00","updated_at":"2016-05-20T07:01:38+00:00"}%
+```
+
+Example completed response:
+
+```
+curl -H 'Content-Type: application/json' https://{username}.carto.com/api/v3/visualization_exports/72e488a6-cf0e-404d-bc7e-de9c9840aadf\?api_key\=04039a13c1bdda65df8bd825b3b8e8117444c950 -X GET
+{"id":"72e488a6-cf0e-404d-bc7e-de9c9840aadf","visualization_id":"9a0f4384-afe3-412a-8b09-136b7d9a4013","user_id":"d80fe0f5-0465-4c4a-a2fe-1f14a93f3c5b","state":"complete","url":"http://s3.amazonaws.com/com.cartodb.imports.production/9d149e72331bf074e35f/9a0f4384-afe3-412a-8b09-136b7d9a4013.carto?AWSAccessKeyId=AKIAJK5S64CVBE35QTKA&Expires=1463734900&Signature=b4cwrdoB%2B0FlTelIzNOAgslUDXY%3D","created_at":"2016-05-20T07:01:38+00:00","updated_at":"2016-05-20T07:01:40+00:00"}%
+```
+
+### Import a CARTO Visualization
+
+To import a .carto visualization, you can use the standard Import API procedure for uploading a local file.
+
+See the import errors list on Support section to troubleshoot any importing errors.

doc/developer-center/import-api/guides/05-sync-tables.md

@@ -0,0 +1,311 @@
+## Sync Tables
+
+Sync tables are available for certain CARTO plans. These tables store data from a remote file and refresh their contents during periodic intervals specified by the user. The base files from which the sync tables retrieve their contents may come from Google Drive, Dropbox, Box or a public URL. 
+
+### Upload and manage synced tables
+
+##### Definition
+
+```html
+GET /api/v1/synchronizations
+```
+
+##### Params
+
+Param | Description
+--- | ---
+api_key | The target CARTO account API key.
+
+##### Response
+
+The response includes an **array** of items, each one containing the following elements:
+
+Attributes | Description
+--- | ---
+id | A unique alphanumeric identifier of the synced table.
+name | The actual name of the created sync table.
+interval | An integer value representing the number of seconds between synchronizations of the table contents.
+url | The **public** URL address where the file to be synchronized is located.
+state | A string value indicating the current state of the synchronized dataset. It can have any of the following values: **created**,  **queued**, **syncing**, **success** or **failure**.
+created_at | The date time at which the table was created in the CARTO database.
+updated_at | The date time at which the table had its contents modified.
+run_at | The date time at which the table will get its contents synched with the source file.
+retried_times | An integer value indicating the number of attempts that were performed to sync the table.
+log_id | A unique alphanumeric identifier to locate the log traces of the given table.
+error_code | An integer value representing a unique error identifier.
+error_message | A string value indicating the message related to the *error_code* element.
+ran_at | The date time at which the table **had** its contents synched with the source file.
+modified_at | The date time at which the table was manually modified, if applicable.
+etag | HTTP entity tag of the source file.
+checksum | See **etag**.
+user_id | A unique alphanumeric element that identifies the CARTO account user in the internal database.
+service_name | A string with the name of the datasource used to import the file. It can have any of the following values: *gdrive* for Google Drive, *dropbox* for Dropbox and *null* for URL imports.
+
+service_item_id | A unique identifier used by CARTO to reference the sync table and its related datasource service.
+type_guessing | A boolean indicating whether field type guessing (for Excel and CSVs) is enabled or not.
+quoted_fields_guessing | A boolean indicating whether type guessing of CSV fields inside double quotes is enabled for the data import.
+content_guessing | A boolean indicating whether content guessing and automatic geocoding is enabled for the data import.
+visualization_id | A unique identifier for the map created in the import process. Only applies if `create_visualization` is set to true.
+from_external_source | A boolean indicating whether the Sync Table is connected to an external source, generally the CARTO Data library.
+
+Finally, the array includes a **total_entries** element that indicates the number of items contained in the response array.
+
+#### Example
+
+##### Call
+
+```bash
+curl -v "https://{username}.carto.com/api/v1/synchronizations/?api_key={account API Key}"
+```
+
+##### Response
+
+```javascript
+{
+  "synchronizations": [
+    {
+    "id": "246dae5e-5302-1ae5-af51-0e85ad047bba",
+    "name": "barrios_5",
+    "interval": 2592000,
+    "url": "https://common-data.carto.com/api/v2/sql?q=select+*+from+%22barrios%22&format=shp&filename=barrios",
+    "state": "success",
+    "created_at": "2015-09-04T12:40:37+00:00",
+    "updated_at": "2016-02-01T12:45:07+00:00",
+    "run_at": "2016-03-02T12:45:07+00:00",
+    "retried_times": 0,
+    "log_id": "2d9b4a52-1daa-429b-b425-6ad561609cb1",
+    "error_code": null,
+    "error_message": null,
+    "ran_at": "2016-02-01T12:45:07+00:00",
+    "modified_at": "2015-04-22T12:17:50+00:00",
+    "etag": null,
+    "checksum": null,
+    "user_id": "cf8a5cce-d573-4a0b-8c43-6caeaf1dd80e",
+    "service_name": null,
+    "service_item_id": "https://common-data.carto.com/api/v2/sql?q=select+*+from+%22barrios%22&format=shp&filename=barrios",
+    "type_guessing": true,
+    "quoted_fields_guessing": true,
+    "content_guessing": true,
+    "visualization_id": "2954fa60-5a02-11e5-888a-0e5e07bb5d8a",
+    "from_external_source": false
+    }
+  ],
+  "total_entries": 1
+}
+```
+
+---
+
+### Syncing a file from a URL
+
+##### Definition
+
+```html
+POST /api/v1/synchronizations
+```
+
+##### Params
+
+Param | Description
+--- | ---
+api_key | The targeted CARTO account API key.
+url | The **public** URL address where the file to be imported is located.
+interval | The number of seconds for the synchronization period. *Note*: Sync interval must be at least 900 (15 minutes).
+type_guessing | If set to *false* disables field type guessing (for Excel and CSVs). Optional. Default is *true*.
+quoted_fields_guessing | If set to *false* disables type guessing of CSV fields that come inside double quotes. Optional. Default is *true*.
+content_guessing | Set it to *true* to enable content guessing and automatic geocoding based on results. Currently it only implements geocoding of countries. Optional. Default is *false*.
+
+##### Response
+
+The response includes the following items:
+
+Attributes | Description
+--- | ---
+endpoint | This item refers to the internal CARTO controller code responsible for performing the import.
+item_queue_id | A unique alphanumeric identifier that refers to the import process. It can be used to retrieve data related to the created table.
+id | An alphanumeric identifier used internally by CARTO as a reference to the import process.
+name | This item is currently deprecated.
+interval | An integer value that stores the number of seconds between synchronizations.
+state | A string value indicating the current condition of the importing process. It can have any of the following values: **created**,  **queued**, **syncing**, **success** or **failure**.
+user_id | A unique alphanumeric identifier to reference the user in the CARTO Engine.
+created_at | The date time at which the table was created in the CARTO Engine.
+updated_at | The date time at which the table had its contents modified.
+run_at | The date time at which the table will get its contents synched with the source file.
+ran_at | The date time at which the table **had** its contents synched with the source file.
+modified_at | The date time at which the table was manually modified, if applicable.
+etag | HTTP entity tag of the source file.
+checksum | See **etag**.
+log_id | A unique alphanumeric identifier to locate the log traces of the given table.
+error_code | An integer value representing a unique error identifier.
+error_message | A string value indicating the message related to the *error_code* element.
+retried_times | An integer value indicating the number of attempts that were performed to sync the table.
+service_name | A string with the name of the datasource used to import the file. It can have any of the following values: *gdrive* for Google Drive, *dropbox* for Dropbox and *null* for URL imports.
+
+service_item_id | A unique identifier used by CARTO to reference the sync table and its related datasource service.
+type_guessing | A boolean indicating whether field type guessing (for Excel and CSVs) is enabled or not.
+quoted_fields_guessing | A boolean indicating whether type guessing of CSV fields inside double quotes is enabled for the data import.
+content_guessing | A boolean indicating whether content guessing and automatic geocoding is enabled for the data import.
+visualization_id | A unique identifier for the map created in the import process. Only applies if `create_visualization` is set to true.
+from_external_source | A boolean indicating whether the Sync Table is connected to an external source, generally the CARTO Common-Data library.
+
+#### Example
+
+##### Call
+
+```bash
+curl -v -H "Content-Type: application/json" -d '{"url":"https://public.url.to.file/sample_file", "interval":"3600"}' "https://{username}.carto.com/api/v1/synchronizations/?api_key={account API Key}"
+```
+
+##### Response
+
+```
+{
+  "data_import": {
+    "endpoint": "/api/v1/imports",
+    "item_queue_id": "1234abcd-1234-1a2b-3c4d-4321dcba5678"
+  },
+  "id": "abcd1234-a5b6-c7d8-1a2b-efgh5678abcd",
+  "name": null,
+  "interval": 3600,
+  "url": "https://public.url.to.file/sample_file",
+  "state": "created",
+  "user_id": "aaaabbbb-1234-5678-dcba-abcd1234efgh",
+  "created_at": "2014-08-05T13:39:15+00:00",
+  "updated_at": "2014-08-05T13:39:15+00:00",
+  "run_at": "2014-08-05T14:39:15+00:00",
+  "ran_at": "2014-08-05T13:39:15+00:00",
+  "modified_at": null,
+  "etag": null,
+  "checksum": "",
+  "log_id": "06fafab8-3502-11e4-9514-0e230854a1cb",
+  "error_code": null,
+  "error_message": null,
+  "retried_times": 0,
+  "service_name": null,
+  "service_item_id": null,
+  "type_guessing": true,
+  "quoted_fields_guessing": true,
+  "content_guessing": false,
+  "visualization_id": null,
+  "from_external_source": false
+}
+```
+
+---
+
+### Removing the synchronization feature from a given dataset
+
+A sync table can be converted to a standard dataset (a dataset that never gets synced).
+
+##### Definition
+
+```bash
+DELETE /api/v1/synchronizations/<import_id>
+```
+
+##### Params
+
+Param | Description
+--- | ---
+api_key | The target CARTO account API key.
+Target table import id | The unique alphanumeric identifier of the target sync dataset.
+
+#### Example
+
+##### Call
+
+```bash
+curl -v -X "DELETE" https://{username}.carto.com/api/v1/synchronizations/{import_id}?api_key={account API Key}"
+```
+
+##### Response
+
+An HTTP No content - 204 response should result as a confirmation for the removal of the synchronization feature for the target table.
+
+---
+
+### Check whether a sync table is syncing or not
+
+A large synced table may take some time to get fully synced. In the meantime, it could be useful to check whether it finished refreshing its contents.
+
+##### Definition
+
+```bash
+GET /api/v1/synchronizations/<import_id>/sync_now
+```
+
+##### Params
+
+Param | Description
+--- | ---
+api_key | The target CARTO account API key.
+Target table import id | The unique alphanumeric identifier of the target sync table.
+
+##### Response
+
+The response includes the following items:
+
+Attributes | Description
+--- | ---
+state | A string value indicating the status of the synchronization. It can have any of the following values: **created**,  **queued**, **syncing**, **success** or **failure**.
+
+#### Example
+
+##### Call
+
+```bash
+curl -v -X "GET" "https://{username}.carto.com/api/v1/synchronizations/{import_id}/sync_now?api_key={account API Key}"
+```
+
+##### Response
+
+```
+{
+  "state": "syncing"
+}
+```
+
+---
+
+### Force a synchronization action on a sync table
+
+Sync tables have their contents synchronized with the source file in periodic time intervals as specified by the user during the creation process. However, a dataset can be synchronized at an arbitrary moment in time if desired. **Note**: Forcing a synchronization can only be performed when the last synchronization attempt occurred at least 900 seconds (15 minutes) before.
+
+#### Definition
+
+```bash
+PUT /api/v1/synchronizations/<import_id>/sync_now
+```
+
+##### Params
+
+Param | Description
+--- | ---
+api_key | The target CARTO account API key.
+Target table import id | The unique alphanumeric identifier of the target sync table.
+
+#### Response
+
+The response includes the following items:
+
+Attributes | Description
+--- | ---
+enqueued | A boolean value indicating whether the request has been successfully appended to the processing queue.
+synchronization_id | A unique alphanumeric identifier referring to the queue element just added.
+
+#### Example
+
+##### Call
+
+```bash
+curl -v -X "PUT" "https://{username}.carto.com/api/v1/synchronizations/<import_id>/sync_now?api_key={account API Key}" -H "Content-Length:0"
+```
+
+##### Response
+
+```bash
+{
+  "enqueued": true,
+  "synchronization_id": "1234abcd-aaaa-2222-4444-dcba4321a1b2"
+}
+```

doc/developer-center/import-api/guides/06-the-arcgis-connector.md

@@ -0,0 +1,221 @@
+## Importing an ArcGIS™ Layer
+
+The ArcGIS™ Connector allows you to import ArcGIS™ layers into a CARTO account as dataset from ArcGIS Server™ (version 10.1 or higher is required). Note that **this connector is disabled by default** in the CARTO importer options. If you are interested in enabling it, please contact [support@carto.com](mailto:support@carto.com) for more details.
+
+**Tip:** You can easily import ArcGIS™ server table URLs from CARTO Builder, with the ArcGIS Server™ Connect Dataset option.
+
+### Import an ArcGIS™ Layer
+
+ArcGIS™ layers stored in ArcGIS Server™ can get imported as CARTO datasets. Such layers must be (PUBLIC) and accessible via an **ArcGIS™ API REST URL**, using the following structure:
+
+```html
+http://<host>/<site>/rest/services/<folder>/<serviceName>/<serviceType>/<layer_ID>
+```
+
+##### Definition
+
+```bash
+POST api/v1/imports 
+```
+
+##### Params
+
+Param | Description
+--- | ---
+interval | This value **MUST** be set to *0*. **Different values do not guarantee correct imports**.
+service_item_id | The ArcGIS&trade; API REST URL where the ArcGIS&trade; layer is located.
+service_name | This value **MUST** be set to *arcgis* to make use of this connector.
+value | Same URL as specified in the *service_item_id* parameter.
+
+##### Response
+
+The response includes:
+
+Attributes | Description
+--- | ---
+item_queue_id | A unique alphanumeric identifier referencing the imported file in the targeted account.
+success | A boolean value indicating whether the import process was successfully appended to the processing queue or not.
+
+#### Example
+
+##### Call
+
+```bash
+curl -v -H "Content-Type: application/json" -d '{"interval":"0","service_item_id": "http://url.to.arcgis.server.layer", "service_name": "arcgis", "value": "http://url.to.arcgis.server.layer"}' "https://{username}.carto.com/api/v1/imports/?api_key={API_KEY}"
+```
+
+##### Response
+
+```
+{
+  "item_queue_id": "d676fd50-b774-4052-a4f1-e56ac6a4300e",
+  "success": true
+}
+```
+
+### Syncing an ArcGIS&trade; Layer
+
+An ArcGIS&trade; layer can get imported to a CARTO account as a synchronized table. The target ArcGIS&trade; layer must be (PUBLIC) and accessible via an ArcGIS&trade; API REST URL, using the following structure:
+```html
+http://<host>/<site>/rest/services/<folder>/<serviceName>/<serviceType>/<layer_ID>
+```
+
+##### Definition
+
+```bash
+POST /api/v1/synchronizations
+```
+
+##### Params
+
+Param | Description
+--- | ---
+interval | The number of seconds for the synchronization period. *Note*: Sync interval must be at least 900 (15 minutes).
+service_item_id | The ArcGIS&trade; API REST URL where the ArcGIS&trade; dataset is located. **Note:** Layers and Datasets must be (PUBLIC) and accessible via an ArcGIS&trade; API REST URL. You cannot enforce ArcGIS Server security parameters into the request, the REST endpoints must be publicly available.
+service_name | This value **MUST** be set to *arcgis* to make use of this connector.
+url | This value **MUST** be empty.
+
+##### Response
+
+The response includes the following items:
+
+Attributes | Description
+--- | ---
+endpoint | This item refers to the internal CARTO controller code responsible for performing the import.<br/><br/>
+item_queue_id | A unique alphanumeric identifier that refers to the import process. It can be used to retrieve data related to the created dataset.
+id | An alphanumeric identifier used internally by CARTO as a reference to the import process.
+name | This item is currently deprecated.
+interval | An integer value that stores the number of seconds between synchronizations.
+url | This value is empty in this case.
+state | A string value indicating the current condition of the importing process. It can have any of the following values: **created**,  **queued**, **syncing**, **success** or **failure**.
+user_id | A unique alphanumeric identifier to reference the user in the CARTO Engine.
+created_at | The date time at which the dataset was created in the CARTO Engine.
+updated_at | The date time at which the dataset had its contents modified.
+run_at | The date time at which the table will get its contents synced with the source file.
+ran_at | The date time at which the table **had** its contents synced with the source file.
+modified_at | The date time at which the dataset was manually modified, if applicable.
+etag | HTTP entity tag of the source file.
+checksum | See **etag**.
+log_id | A unique alphanumeric identifier to locate the log traces of the given dataset.
+error_code | An integer value representing a unique error identifier.
+error_message | A string value indicating the message related to the *error_code* element.
+retried_times | An integer value indicating the number of attempts that were performed to sync the table.
+service_name | This value is set to *arcgis*.
+service_item_id | This item contains the ArcGIS&trade; API REST URL targeting the imported ArcGIS&trade; layer.
+type_guessing | A boolean indicating whether field type guessing (for Excel and CSVs) is enabled or not.
+quoted_fields_guessing | A boolean indicating whether type guessing of CSV fields inside double quotes is enabled for the data import.
+content_guessing | A boolean indicating whether content guessing and automatic geocoding is enabled for the data import.
+visualization_id | A unique identifier for the map created in the import process. Only applies if `create_visualization` is set to true.
+from_external_source | A boolean indicating whether the Sync Table is connected to an external source, generally the CARTO Common-Data library.
+
+#### Example
+
+##### Call
+
+```bash
+curl -v -H "Content-Type: application/json" -d '{"interval":"604800","service_item_id": "http://url.to.arcgis.server.layer", "service_name": "arcgis", "url":""}' "https://{username}.carto.com/api/v1/synchronizations?api_key={API_KEY}"
+```
+
+##### Response
+
+```
+{
+  "endpoint":"/api/v1/imports",
+  "item_queue_id":"4ff4abdd-9d37-4b7a-8e13-fb00376e2a58",
+  "id":"d4bc05e8-5063-11e4-9886-0e018d66dc29",
+  "name":null,
+  "interval":604800,
+  "url":"",
+  "state":"created",
+  "user_id":"4884b545-07f4-4ce4-a62f-fe9e2412098f",
+  "created_at":"2014-10-10T09:57:22+00:00",
+  "updated_at":"2014-10-10T09:57:22+00:00",
+  "run_at":"2014-10-17T09:57:22+00:00",
+  "ran_at":"2014-10-10T09:57:22+00:00",
+  "modified_at":null,
+  "etag":null,
+  "checksum":"",
+  "log_id":"6aa19bf6-42db-477a-9b69-2c4f74fd8c31",
+  "error_code":null,
+  "error_message":null,
+  "retried_times":0,
+  "service_name":"arcgis",
+  "service_item_id":"http://url.to.arcgis.layer",
+  "type_guessing": true,
+  "quoted_fields_guessing": true,
+  "content_guessing": true,
+  "visualization_id": "2954fa60-5a02-11e5-888a-0e5e07bb5d8a",
+  "from_external_source": false
+}
+```
+
+### Import an ArcGIS&trade; Dataset
+
+This option allows you to programmatically import a complete set of layers belonging to an ArcGIS&trade; dataset (as opposed to using CARTO Builder ArcGIS Server&trade; Connect Dataset option). Such a dataset must be (PUBLIC) and accessible via an ArcGIS&trade; API REST URL, using the following structure:
+
+```html
+http://<host>/<site>/rest/services/<folder>/<serviceName>/<serviceType>/
+```
+
+##### Definition
+
+```bash
+POST api/v1/imports 
+```
+
+##### Params
+
+Param | Description
+--- | ---
+interval | This value **MUST** be set to *0*. **Different values do not guarantee correct imports**.
+service_item_id | The ArcGIS&trade; API REST URL where the ArcGIS&trade; dataset is located.
+service_name | This value **MUST** be set to *arcgis* to make use of this connector.
+value | Same URL as specified in the *service_item_id* parameter
+
+##### Response
+
+The response includes:
+
+Attributes | Description
+--- | ---
+item_queue_id | A unique alphanumeric identifier referencing the imported file in the targeted account.
+success | A boolean value indicating whether the file import succeeded or not.
+
+#### Example
+
+##### Call
+
+```bash
+curl -v -H "Content-Type: application/json" -d '{"interval":"0","service_item_id": "http://url.to.arcgis.server.dataset", "service_name": "arcgis", "value": "http://url.to.arcgis.server.dataset"}' "https://{username}.carto.com/api/v1/imports/?api_key={API_KEY}"
+```
+
+##### Response
+
+```
+{
+  "item_queue_id": "c478fd50-f984-4091-d1f2-e72ac6c4333e",
+  "success": true
+}
+```
+
+### Limits
+
+Connections to ArcGIS&trade; server are limited by two types of timeouts: connection and response timeouts.
+
+#### Connection timeout
+
+Connection timeout to the ArcGIS&trade; server is set to 60 seconds.
+
+This means if the ArcGIS&trade; server does not respond to a request in 60 seconds the connection is closed and the synchronization of the dataset will fail.
+
+In the vast majority of cases a connection timeout means there's something wrong in the ArcGIS&trade; server, so you should contact the server administrator for more details about the issue.
+
+#### Response timeout
+
+Response timeout from the ArcGIS&trade; server is set to 60 seconds.
+
+This means the ArcGIS&trade; server did not finish the request in 60 seconds, after the connection was made, so the resulting dataset will be incomplete and the import will fail with a `Download timeout` error code.
+
+Response timeouts can happen for a number of reasons, the more commons ones are because the ArcGIS&trade; server is overloaded and is not able to respond in a timely manner or the dataset is too big to be transferred in 60 seconds from the server to CARTO.
+
+In any case, we recommend you to first check any issue with the ArcGIS&trade; server administrator and if that does not solve the issue contact us at [support@carto.com](mailto:support@carto.com) for more details.

doc/developer-center/import-api/guides/08-importing-geospatial-data.md

@@ -0,0 +1,199 @@
+## Importing Geospatial Data
+
+This section explains how importing a dataset creates columns in CARTO (and the naming conventions that you should use). It includes how CARTO guesses content during the import process, lists the supported geospatial formats for uploading data, and describes how to upload multilayer datasets or batch file uploads.
+
+### Dataset Basics
+
+When a file is imported, it is transformed into a dataset that can be processed by CARTO. The system automatically creates the following columns:
+
+* **cartodb_id**
+  * This column is used as the primary key of the table
+  * Its values must be integers, non-null, and unique
+* **the_geom**
+  * This column stores the main geometric features of a dataset in the EPSG 4326 projection
+* **the_geom_webmercator**
+  * This column stores the geometries transformed into the EPSG 3857 projection, and is used for rendering purposes
+* **_feature_count**
+  * This column is automatically created when overview representations of data are created (for datasets containing more than 500,000 points).
+
+When a dataset is exported from CARTO, it includes the `cartodb_id` and `the_geom` columns, which will be reused if the dataset is then imported to the system. This ensures that importing an exported dataset contains the original exported dataset content and row order.
+
+If these columns are generated by the user, the [CARTO table requirements](https://github.com/CartoDB/cartodb-postgresql/blob/master/doc/CartoDB-user-table.rst) must be followed in order to produce a successful import. Otherwise, importing datasets which do not meet the requirements (such as a dataset with duplicated integers in its `cartodb_id` column) will result in an import failure.
+
+#### Naming
+
+Apply the following naming conventions for datasets in CARTO, and avoid using the reserved words as part of your file names.
+
+* Table names must begin with a letter (a-z). Otherwise, "table_" is prepended to the name
+* Column names must begin with a letter (a-z) or an underscore (_)
+* Column and table names can have a maximum of 63 characters. Names are trimmed if they exceed this length
+
+##### Reserved Words
+
+There are certain words reserved in the system that cannot be used to name columns or datasets, mainly the PostgreSQL reserved words. Any names that conflict with a reserved word are prefixed with an underscore (_) automatically.
+
+### Import Guessing
+
+CARTO includes guessing functionality during the import process. This is useful for when files or data are missing some upload information. The following guessing options are available:
+
+* **Fields guessing**
+
+  For files whose format does not include type information (usually CSV files), field guessing options can be enabled. There are two particular guessing options for these type of files:
+
+  * **Type guessing**: determines the type of imported columns from the text contents, available in the CSV file. If enabled, it generates numeric and boolean columns when appropriate, otherwise, it uses regular string columns
+
+  * **Quoted fields guessing**: when disabled, avoids double quoted fields for type guessing. Otherwise, double quoted fields are used when enabled
+
+* **Content Guessing**
+
+  Files that contain country, city, IP address information can be automatically geocoded by the system, if the content guessing option is enabled. This automatic geocoding only occurs if there is not a big proportion of repeated, or null values, in a column. Content guessing does not require the target columns to be named in a special way (such as "country" or "city"), CARTO inspects the different available columns and identifies which of them can be guessed geospatially.
+
+**Tip:** For information about how to granularly configure the guessing options for your import process, view the upload file parameters on the standard tables section.
+
+### Supported Geospatial Data Formats
+
+CARTO supports several geospatial data formats to upload vector data. The important details of each format, as well as some guidelines to upload your files to CARTO, are defined in this section.
+
+#### Shapefile
+
+The Shapefile format is a multi-file format — it consists of a set of files with the same name and stored in the same directory, which are differentiated by their extension.
+
+A Shapefile has to be formed, at least, by a .shp file, a .shx file, a .prj file and a .dbf file. These files contain the geometry data, the indexes, the projection information and the attributes, respectively. Other auxiliary files are not mandatory and contain extra information for the Shapefile. Shapefiles must be imported as a single compressed file, in the .zip or .gz format.
+
+**Note:** The Shapefile format has certain limitations that can affect the way that your datasets are exported/imported into CARTO:
+
+* The column name cannot exceed 10 characters. Exporting a dataset with longer names in this format will trim the names
+* Date columns only support the date, not the time. Exporting and importing a date column as a Shapefile will remove all time information and maintain just the date. If you need to work with date and time data, it is recommended to export/import the information as a string and convert it to a date
+* Although the projection of the file should be correctly determined and adjusted from the .prj file, it is recommended to upload Shapefiles in the EPSG 4326 projection
+* For improved compatibility, ensure you save your Shapefile with encoding UTF-8, prior importing
+
+#### Keyhole Markup Language (KML)
+
+The KML format is a XML based format which adds to it a geographical meaning by being able to define features such as points, polygons or lines in the EPSG 4326 projection.
+
+KML uses common XML types such as string, boolean, double, or int, so your column types will be respected when your dataset is imported or exported from CARTO.
+
+Each feature is defined as a Placemark element, which usually contains a name, a description, and the geometry itself. If more data columns are required, these fields need to be defined and included inside a ExtendedData element of the KML document.
+
+In terms of geometric elements, the Point, Polygon, Line, MultiGeometry and Geometry elements are supported. Different geometry types in the same layer are not supported.
+
+#### KMZ
+
+A Keyhole Markup language Zipped (KMZ) file corresponds to a compressed file, including a KML file and zero, or more, supporting files (images, icons, overlays or other elements referenced in the KML file). See the [Keyhole Markup Language (KML) section for more information](#keyhole-markup-language-kml).
+
+#### GeoJSON
+
+The GeoJSON format is an extension of the JavaScript Object Notation (JSON) that encodes geographical features and their metadata. This format supports data types such as string, double or boolean. Dates exported as GeoJSON are stored as strings and will be recognized as such, on data imports.
+
+With respect to geometries, Points, (Multi)Polygons and (Multi)Lines are supported. GeometryCollection geometric objects are not supported and will raise an import error. The supported geometries can be imported inside FeatureCollection and Feature objects.
+
+Importing different geometry types in a FeatureCollection element is not supported.
+
+#### CSV
+
+Comma-Separated Values (or TSV, Tab-Separated Values) files can be imported to CARTO. For a successful import, follow these formatting guidelines:
+
+* The first line of the CSV file must contain the name of the columns
+* The rest of the lines of the CSV file must follow the schema defined by the header column, in terms of number of columns
+* To ensure correct parsing, it is recommended that string values are double-quoted
+* If the data itself contains quotes, the values must be double-quoted and the internal quotes must be escaped
+* CSV lines must be terminated with CR/LF, or LF line terminators. CR line terminators are not supported
+
+
+###### Example: Quoted strings in a CSV
+
+`````
+name, description, score
+"John Doe", "Awesome, the best player ever", 100
+`````
+
+###### Example: Escaped quotes in a CSV
+
+````
+name, geojson
+"Null Island", "{""type"": ""Point"", ""coordinates"": [0,0]}"
+````
+
+##### CSV Format Guessing
+
+As the CSV format does not specify the type of the columns in the data, CARTO applies a guessing functionality that converts your data to columns, using a supported format. This enables you to generate numeric columns, or geocode your dataset directly on import.
+
+There are two particular guessing options for CSV files: types guessing and quoted fields guessing. View the [Import Guessing](#import-guessing) section for details.
+
+#### Spreadsheets (Excel or OpenDocument)
+
+Excel files, or other spreadsheets (such as OpenDocument spreadsheets or Google Drive spreadsheets) are supported by CARTO.
+
+The format of the uploaded Spreadsheet must apply the following format:
+
+* The first row must contain the names for each column
+* Merged cells are not supported
+* Graphs, charts, or other kind of elements are not supported
+
+For multi-sheet spreadsheets, only the first sheet will be imported. For the case of Google Drive the maximum size of the spreadhseet is limited to 10MB.
+
+#### GPX
+
+The GPX (GPS Exchange Format) files are XML documents that contain waypoints, tracks and/or routes. When importing a GPX file, CARTO will generate different datasets for points, tracks and waypoints. The resulting names of these datasets will be a combination of the GPX name and their type: `_track_points`, `_tracks`, and `_waypoints`, respectively.
+
+#### OSM
+
+CARTO supports importing Open Street Map dumps (.osm files). These files are XML documents that have a `osm` parent element that can contain blocks of nodes, ways, or relations representing points, lines or polygons. CARTO will automatically separate OSM dumps into different tables, depending on the geometry. Therefore, importing a single OSM file can lead to more than one resulting dataset.
+
+#### MapInfo
+
+The MapInfo file format is geospatial vector data developed by MapInfo, which supports grids based multiple files. MapInfo files (.DAT, .ID, .MAP, .TAB) must be imported as a single compressed file, in the .zip or .gz format. 
+
+##### CARTO
+
+CARTO files are CARTO generated map visualization files. This .carto file includes the dataset and visualization definition, which contains any SQL queries, CartoCSS, basemaps, attributions, metadata, and styling that was applied to a map. This is useful for downloading complete CARTO visualizations that you can share or import.
+
+#### GeoPackage
+
+GeoPackage (GPKG) files are an [open standard format](https://www.geopackage.org/) for spatial data. The format supports multiple layers, and all the geometry types used by CARTO: Points, (Multi)Polygons and and (Multi)Lines. GeoPackage files can be imported as an uncompressed .GPKG file or as a compressed .ZIP file. Each layer (up to 50) in the GeoPackage file will be imported as a separate CARTO table.
+
+### FileGeodatabase
+
+File Geodatabase (GDB) is a proprietary [Esri format](http://desktop.arcgis.com/en/arcmap/10.3/manage-data/administer-file-gdbs/file-geodatabases.htm) for spatial data. The GDB format is a directory with a `.gdb` extension containing the data files, so for download and upload a zip file containing the directory is used, either with a `.zip` or a `.gdb.zip` extension. Each layer (up to 50) in the GDB file will be imported as a separate CARTO table.
+
+**Note:** The "[personal geodatabase](http://desktop.arcgis.com/en/arcmap/latest/manage-data/administer-file-gdbs/personal-geodatabases.htm)" (having a `.mdb` extension) format used by ArcGIS 8 and ArcGIS 9 is not supported by CARTO. 
+
+### Multilayer Uploads
+
+Several of the formats supported by CARTO can store different layers, or geometric types, by definition. Importing a file that contains more than one layer result in different imported datasets.
+
+If the option `create_vis` is enabled in the import process, the different layers imported will be added to the created map. The number of layers that can be included in a map depends on the maximum value of layers per map in the configuration of the user.
+
+The maximum number of datasets created from a multilayer file is 10. If the imported file contains more than 10 layers, those layers are omitted.
+
+**Important note:** The "[personal geodatabase](http://desktop.arcgis.com/en/arcmap/latest/manage-data/administer-file-gdbs/personal-geodatabases.htm)" (having a `.mdb` extension) format used by ArcGIS 8 and ArcGIS 9 is not supported by CARTO.
+
+#### Shapefile
+
+The different layers included in a Shapefile are imported as independent datasets.
+
+#### KML Files
+
+KML files generate a different dataset, per each Folder, that they contain.
+
+#### GPX Files
+
+GPX files that contain more than one type of elements (waypoints, tracks, and/or routes) are imported in a different dataset, per type.
+
+#### OSM Files
+
+OSM files generate a different layer, per each type of geometry that their nodes, ways, or relations represent (points, polygons or lines).
+
+#### GeoPackage
+
+GPKG files generate a different dataset for each layer in the file, up to 50.
+
+#### File Geodatabase
+
+GDB files generate a different dataset for each layer in the file, up to 50.
+
+### Multiple File Uploads
+
+You can perform a batch file upload if the files are sent to the server in a compressed format. As with the case of multilayer uploads, if the import process is configured to generate a map after import, the different datasets are added as layers to the new map. The number of layers that can be included in a map depends on the maximum value of layers allotted to the users account.
+
+The maximum number of files that can be imported in a single file is 10. If the compressed file contains more than 10 files, only the first 10 files are imported and the rest of the files are omitted.

doc/developer-center/import-api/guides/09-column-names-normalization.md

@@ -0,0 +1,44 @@
+## Column names normalization
+
+When data is uploaded into CARTO using the Import API, the resulting dataset in CARTO might have different column names than the original dataset.
+
+This is because as part of the import workflow there's a process to normalize the column names to avoid unsupported column names in the datasets created after the import process finishes. Some of the actions taken when normalizing column names are:
+
+- Remove accents
+- Convert multiple consecutive underscores and hyphens to a single underscore
+- Remove unsupported characters ([]{}&%$+, etc.)
+- Remove white spaces
+- Avoid duplicated column names
+- Avoid column names longer than 63 characters
+- Avoid reserved words
+- Force lower case names
+- Force column names to start by a character
+
+### Some examples of column name normalization
+
+Find below a table with some examples of column names and how they are normalized by the Import API:
+
+| *original column name* | *normalized column name* |
+| Field: 2 | field_
+| 2 Items | _2_item
+| Unnamed: 0 | unnamed_0
+| 201moore | _201moore
+| 201moore | _201moore_1
+| Acadia 1.2.3 | acadia_1_2_3
+| _testingTesting | _testingtesting
+| 1 | _1
+| 1.0 | _1_0
+| SELECT | _select
+| à | a
+| longcolumnshouldbesplittedsomehowanditellyouwhereitsgonnabesplittedrightnow | longcolumnshouldbesplittedsomehowanditellyouwhereitsgonnabespli 
+| longcolumnshouldbesplittedsomehowanditellyouwhereitsgonnabesplittedrightnow | longcolumnshouldbesplittedsomehowanditellyouwhereitsgonnabe_1 
+| all | _all
+
+### Changing column names
+
+In some cases you may want to preserve some of the column names in your original data. For example, let's say you have a column name `column__1` which indeed is a valid column name for PostgreSQL and the Import API renamed it as `column_1`. In the case you want to preserve `column__1` as the column name, right after the import process finished you can update the column name using the [CARTO SQL API](https://carto.com/developers/sql-api/) with a query like this:
+
+```sql
+  ALTER TABLE test_1 RENAME COLUMN column_1 to column__1;
+  SELECT CDB_TableMetadataTouch('test_1');
+```

doc/developer-center/import-api/reference/swagger.yaml

@@ -0,0 +1,971 @@
+openapi: 3.0.0
+info:
+  title: Import API
+  description: >
+    # Introduction
+
+    The CARTO Import API allows you to upload files to a CARTO account, 
+    check on their current upload status, as well as delete and list importing 
+    processes on a given account. This API consists of several HTTP requests targeted 
+    at a set of CARTO endpoints that deal with the conversion and import of the sent files. 
+    CARTO tables can be classified as Standard Tables or Sync Tables. Additionally, 
+    the ArcGIS Server™ Connector enables you to import ArcGIS™ layers into your datasets.
+
+    # Authorization
+
+    In order to access Maps API you must provide an API key. The CARTO
+    Authorization guide explains how these keys are sent (TLDR: _HTTP basic
+    auth_ or _query string param_ with the API key token). Depending on the
+    permissions granted to the provided API key, the request will be authorized
+    or not.
+  version: 0.0.1
+  contact:
+    name: Have you found an error? Github issues
+    url: 'https://github.com/CartoDB/Windshaft-cartodb/issues'
+servers:
+  - url: 'https://{user}.{domain}/api'
+    description: Production server (uses live data)
+    variables:
+      domain:
+        default: carto.com
+        description: 'If on premise, change it to your domain'
+      user:
+        default: username
+        description: Your username
+tags:
+  - name: Standard Tables
+    description: Store data you upload from files creating tables at CARTO
+    externalDocs:
+      url: 'http://doc.carto.com/pet-operations.htm'
+  - name: CARTO Map Visualizations
+    description: Download a map, and the connected dataset, as a .carto file
+    externalDocs:
+      url: 'http://doc.carto.com/pet-operations.htm'
+  - name: Sync Tables
+    description: Store data from a remote file and refresh their contents during periodic intervals
+    externalDocs:
+      url: 'http://doc.carto.com/pet-operations.htm'
+paths:
+  '/v1/imports':
+    post:
+      summary: Create import
+      description: |
+        Upload File
+      tags:
+        - Standard Tables
+      operationId: createImport
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateImport'
+            examples:
+              url:
+                $ref: '#/components/examples/CreateImportUrl'
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RequestResponse'
+              example:
+                item_queue_id: 9906bce0-f1a3-4b07-be71-818f4bfd7673
+                success: true
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+      x-code-samples:
+        - lang: Curl
+          source: |
+            curl -v -F file=@/path/to/local/file "https://{account}
+            .carto.com/api/v1/imports/?api_key={account API Key}"
+    get:
+      summary: List current import processes
+      description: Lists the import identifiers of the files that are being imported in the targeted CARTO account
+      tags:
+        - Standard Tables
+      operationId: getImports
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  imports:
+                    type: array
+                    description: A list of unique alphanumeric identifiers referencing the import processes in the targeted CARTO account
+                    items:
+                      type: string
+                  success:
+                    type: boolean
+                    description: A boolean value indicating if the request was successful
+              example:
+                imports:
+                  - "1234abcd-1234-1a2b-3c4d-4321dcba5678"
+                success: true
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+      x-code-samples:
+        - lang: Curl
+          source: >
+            curl -v "https://{account}.carto.com/api/v1/imports/?api_key={account API Key}"
+  '/v1/imports/{import_id}':
+    get:
+      parameters:
+        - in: path
+          name: import_id
+          description: A unique alphanumeric element that identifies the import process to be retrieved. It is the `item_queue_id` element returned after running the upload request successfully.
+          schema:
+            type: string
+          required: true
+      summary: Check import status
+      description: |
+        Returns the Import's status and its associated metadata.
+      tags:
+        - Standard Tables
+      operationId: getImportStatus
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ImportStatusResponse'
+              example:
+                id: 029a6053-b2fb-43dd-baa6-805d679c404f
+                user_id: ca8c5ace-d573-450b-8a43-6c7eafadd80e
+                table_id: null
+                data_type: url
+                table_name: null
+                state: failure
+                error_code: 1002
+                queue_id: 029a6053-b2fb-43dd-baa6-805d679c404f
+                tables_created_count: null
+                synchronization_id: null
+                type_guessing: true
+                quoted_fields_guessing: true
+                content_guessing: false
+                create_visualization: false
+                visualization_id: null
+                user_defined_limits: '{twitter_credits_limit:0}'
+                get_error_text:
+                  title: Unsupported/Unrecognized file type
+                  what_about: 'Should we support this filetype? Let us know in our <a href=''mailto:support@carto.com''>support email</a>!'
+                  source: user
+                display_name: shapefile_streets.cpg
+                success: false
+                warnings: null
+                is_raster: false
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+      x-code-samples:
+        - lang: Curl
+          source: >
+            curl -v "https://{account}.carto.com/api/v1/imports/{import_id}?api_key={account API Key}
+  '/v3/visualization_exports':
+    post:
+      summary: Export as .carto file
+      description: |
+        The Export map option enables you to download a map, 
+        and the connected dataset, as a .carto file. This .carto
+        file includes the dataset and visualization definition,
+        which contains any SQL queries, CartoCSS, basemaps,
+        attributions, metadata, and styling that was applied to a
+        map. This is useful for downloading complete CARTO
+        visualizations that you can share or import.
+
+        Note: The Import API export visualization command only works for maps created from `Your maps` dashboard.
+      tags:
+        - CARTO Map Visualizations
+      operationId: exportCarto
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ExportCarto'
+            example:
+              visualization_id: 'ace62506-brc8-6570-2p91-8vf3af3ftc44'
+                
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ExportCartoResponse'
+              example:
+                id: 'b94c26f3-fa16-4f13-b672-45ebbd5a9c95'
+                visualization_id: 'ace62506-brc8-6570-2p91-8vf3af3ftc44'
+                user_id: '42b78090-6a11-475a-8060-0a90322752af2b'
+                state: 'pending'
+                url: null
+                created_at: '2016-05-05T09:36:09+00:00'
+                updated_at: '2016-05-05T09:36:09+00:00'
+                
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+      x-code-samples:
+        - lang: Curl
+          source: |
+            curl -v -H 'Content-Type: application/json' https://{username}.carto.com/api/v3/visualization_exports\?api_key\={api_key} -X POST --data '{"visualization_id":"9a0f4384-afe3-412a-8b09-136b7d9a4013"}'
+  '/v3/visualization_exports/{visualization_export_id}':
+    get:
+      parameters:
+        - in: path
+          name: visualization_export_id
+          description: A unique alphanumeric element that identifies the export process to be retrieved. It is the `id` element returned after running the export request successfully.
+          schema:
+            type: string
+          required: true
+      summary: Check .carto export status
+      description: |
+        After making the POST request to create the export, it is expected that the request will take some time. You must poll the server by making a GET request, until state becomes complete. Once completed, the response status changes to `complete` and displays the upload url location of the .carto visualization file
+      tags:
+        - CARTO Map Visualizations
+      operationId: getExportStatus
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ExportCartoResponse'
+              example:
+                id: 'b94c26f3-fa16-4f13-b672-45ebbd5a9c95'
+                visualization_id: 'ace62506-brc8-6570-2p91-8vf3af3ftc44'
+                user_id: '42b78090-6a11-475a-8060-0a90322752af2b'
+                state: 'complete'
+                url: '/uploads/6a2b6fbd86e2c750160a/ace62506-brc8-6570-2p91-8vf3af3ftc44.carto'
+                created_at: '2016-05-05T09:36:09+00:00'
+                updated_at: '2016-05-05T09:36:13+00:00'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+      x-code-samples:
+        - lang: Curl
+          source: >
+            curl -v "https://{account}.carto.com/api/v1/imports/{import_id}?api_key={account API Key}
+  '/v1/synchronizations':
+    get:
+      summary: List current sync tables
+      description: List current sync tables
+      tags:
+        - Sync Tables
+      operationId: getSyncTables
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListSyncTablesResponse'
+              example:
+                synchronizations:
+                - id: 246dae5e-5302-1ae5-af51-0e85ad047bba
+                  name: barrios_5
+                  interval: 2592000
+                  url: https://common-data.carto.com/api/v2/sql?q=select+*+from+%22barrios%22&format=shp&filename=barrios
+                  state: success
+                  created_at: '2015-09-04T12:40:37+00:00'
+                  updated_at: '2016-02-01T12:45:07+00:00'
+                  run_at: '2016-03-02T12:45:07+00:00'
+                  retried_times: 0
+                  log_id: 2d9b4a52-1daa-429b-b425-6ad561609cb1
+                  error_code: null
+                  error_message: null
+                  ran_at: '2016-02-01T12:45:07+00:00'
+                  modified_at: '2015-04-22T12:17:50+00:00'
+                  etag: null
+                  checksum: null
+                  user_id: cf8a5cce-d573-4a0b-8c43-6caeaf1dd80e
+                  service_name: null
+                  service_item_id: https://common-data.carto.com/api/v2/sql?q=select+*+from+%22barrios%22&format=shp&filename=barrios
+                  type_guessing: true
+                  quoted_fields_guessing: true
+                  content_guessing: true
+                  visualization_id: 2954fa60-5a02-11e5-888a-0e5e07bb5d8a
+                  from_external_source: false
+                total_entries: 1
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+      x-code-samples:
+        - lang: Curl
+          source: >
+            curl -v "https://{username}.carto.com/api/v1/synchronizations/?api_key={account API Key}"
+    post:
+      summary: Sync a file from a URL
+      description: |
+        Desc
+      tags:
+        - Sync Tables
+      operationId: syncTable
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateSyncTablesPayload'
+            example:
+              url: 'https://public.url.to.file/sample_file'
+              interval: 3600
+                
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CreateSyncTablesResponse'
+              example:
+                  data_import:
+                    endpoint: "/api/v1/imports"
+                    item_queue_id: 1234abcd-1234-1a2b-3c4d-4321dcba5678
+                  id: abcd1234-a5b6-c7d8-1a2b-efgh5678abcd
+                  name: null
+                  interval: 3600
+                  url: https://public.url.to.file/sample_file
+                  state: created
+                  user_id: aaaabbbb-1234-5678-dcba-abcd1234efgh
+                  created_at: '2014-08-05T13:39:15+00:00'
+                  updated_at: '2014-08-05T13:39:15+00:00'
+                  run_at: '2014-08-05T14:39:15+00:00'
+                  ran_at: '2014-08-05T13:39:15+00:00'
+                  modified_at: null
+                  etag: null
+                  checksum: ''
+                  log_id: 06fafab8-3502-11e4-9514-0e230854a1cb
+                  error_code: null
+                  error_message: null
+                  retried_times: 0
+                  service_name: null
+                  service_item_id: null
+                  type_guessing: true
+                  quoted_fields_guessing: true
+                  content_guessing: false
+                  visualization_id: null
+                  from_external_source: false
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+      x-code-samples:
+        - lang: Curl
+          source: |
+            curl -v -H "Content-Type: application/json" -d '{"url":"https://public.url.to.file/sample_file", "interval":"3600"}' "https://{username}.carto.com/api/v1/synchronizations/?api_key={account API Key}"
+  '/v1/synchronizations/{import_id}':
+    delete:
+      summary: Remove sync feature from table
+      description: A sync table can be converted to a standard dataset (a dataset that never gets synced)
+      tags:
+        - Sync Tables
+      operationId: removeSyncTables
+      parameters:
+        - in: path
+          name: import_id
+          description: The unique alphanumeric identifier of the target sync dataset
+          schema:
+            type: string
+          required: true
+      responses:
+        '204':
+          description: No content
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+      x-code-samples:
+        - lang: Curl
+          source: >
+            curl -v -X "DELETE" https://{username}.carto.com/api/v1/synchronizations/{import_id}?api_key={account API Key}"
+  '/v1/synchronizations/{import_id}/sync_now':
+    get:
+      summary: Check whether a sync table is syncing or not
+      description: A large synced table may take some time to get fully synced. In the meantime, it could be useful to check whether it finished refreshing its contents
+      tags:
+        - Sync Tables
+      operationId: checkSyncTables
+      parameters:
+        - in: path
+          name: import_id
+          description: The unique alphanumeric identifier of the target sync dataset
+          schema:
+            type: string
+          required: true
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  state:
+                    type: string
+                    enum:
+                      - created
+                      - queued
+                      - syncing
+                      - success
+                      - failure
+                    title: State
+                    description: A string value indicating the status of the synchronization
+              example:
+                  state: syncing
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+      x-code-samples:
+        - lang: Curl
+          source: >
+            curl -v -X "GET" "https://{username}.carto.com/api/v1/synchronizations/{import_id}/sync_now?api_key={account API Key}"
+    put:
+      summary: Force a synchronization action on a sync table
+      description: |
+        Sync tables have their contents synchronized with the source file in periodic time intervals as specified by the user during the creation process. However, a dataset can be synchronized at an arbitrary moment in time if desired. Note: Forcing a synchronization can only be performed when the last synchronization attempt occurred at least 900 seconds (15 minutes) before.
+      tags:
+        - Sync Tables
+      operationId: forceSyncTable
+      parameters:
+        - in: path
+          name: import_id
+          description: The unique alphanumeric identifier of the target sync dataset
+          schema:
+            type: string
+          required: true
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  enqueued:
+                    type: boolean
+                    title: Enqueued
+                    description: A boolean value indicating whether the request has been successfully appended to the processing queue
+                  synchronization_id  :
+                    type: string
+                    title: Synchronization ID
+                    description: A unique alphanumeric identifier referring to the queue element just added
+              example:
+                enqueued: false
+                synchronization_id: "1234abcd-aaaa-2222-4444-dcba4321a1b2"
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+      x-code-samples:
+        - lang: Curl
+          source: |
+            curl -v -X "PUT" "https://{username}.carto.com/api/v1/synchronizations/<import_id>/sync_now?api_key={account API Key}" -H "Content-Length:0"
+components:
+  schemas:
+    CreateImport:
+      type: object
+      properties:
+        file:
+          $ref: '#/components/schemas/File'
+        url:
+          $ref: '#/components/schemas/Url'
+        type_guessing:
+          type: boolean
+          default: true
+          title: Type guessing
+          description:   If set to `false` disables field type guessing (for Excel and CSVs)
+        quoted_fields_guessing:
+          type: boolean
+          default: false
+          title: Quoted fields guessing
+          description:   If set to `false` disables type guessing of CSV fields that come inside double quotes
+        content_guessing:
+          type: boolean
+          default: false
+          title: Content guessing
+          description:   Set to `true` to enable content guessing and automatic geocoding based on results. Currently, this only implements geocoding of countries, cities and IP addresses
+        create_vis:
+          type: boolean
+          default: false
+          title: Create Vis
+          description:   Set to `true` to flag the import so that when it finishes, it creates a Map automatically after importing the Dataset
+        collision_strategy:
+          type: string
+          enum:
+            - skip
+            - overwrite
+          title: Collision strategy
+          description: > 
+            Determines the behavior when importing a dataset 
+            that has the same name as an existing table. By default,
+            it is imported and renamed with a sequential number
+            (*mytable*, *mytable_1*…).
+            
+            - `skip`: the table with the
+            matching name will not be imported.
+            
+            - `overwrite`: it will replace
+            the table with the matching name, but only if the new
+            dataset table includes the same columns and data types as
+            the original table. The new table can also include
+            additional columns, but not fewer than the original table. 
+        privacy:
+          type: string
+          enum:
+            - public
+            - private
+            - link
+          title: Collision strategy
+          description: > 
+              Used to set the privacy settings of the table or
+              tables resulting from the import.
+              If `create_vis` is set to true, the resulting
+              visualization privacy settings will also be 
+              determined by this parameter. 
+              
+              `privacy` can be set to:
+            
+              - `public`: The resulting table or visualization can be viewed by anyone
+              
+              - `private`: The resulting table or visualization can only be viewed by the uploader
+              
+              - `link`: The resulting table or visualization can only be viewed through a private link shared by the uploader
+        table_name:
+          type: string
+          title: Table name
+          description:   Used to duplicate one of your existing tables. **Do not mix with File/URL imports**
+        sql:
+          type: string
+          title: SQL
+          description:   Used to create a new table from a SQL query applied to one of your tables. **Do not mix with File/URL imports**
+    File:
+      type: string
+      title: file
+      description: When importing local files, you need to perform a POST with a file 
+    Url:
+      type: string
+      title: url
+      description: When importing remote files, the full URL to the publicly accessible file
+    RequestResponse:
+      type: object
+      properties:
+        item_queue_id:
+          type: string
+          description: A unique alphanumeric identifier referencing the import process in the targeted account
+        success:
+          type: boolean
+          description: A boolean value indicating whether the import process was started or not.
+    ImportStatusResponse:
+      type: object
+      properties:
+        id:
+          type: string
+          title: ID
+          description: A unique identifier for the import process. It is the same as the `import_id` provided in the request
+        user_id:
+          type: string
+          title: User ID
+          description: A unique alphanumeric element that identifies the CARTO account user in the internal database
+        table_id:
+          type: string
+          title: Table ID
+          description:   A unique alphanumeric element that identifies the created table in the internal CARTO database
+        data_type:
+          type: string
+          enum:
+            - file
+            - url
+            - external_table
+            - query
+            - table
+            - datasource
+          title: Data type
+          description: This element identifies the service type used to import the file
+        table_name:
+          type: string
+          title: Table name
+          description: The final name of the created table in the targeted CARTO account. It usually has the same name as the uploaded file, unless there already exists a table with the same name (in this case, an integer number is appended to the table name)
+        status:
+          type: string
+          enum:
+            - enqueued
+            - pending
+            - uploading
+            - unpacking
+            - importing
+            - guessing
+            - complete
+            - failure   
+          title: State
+          description: A string value indicating the current state of the importing process
+        error_code:
+          type: number
+          title: Error code
+          description: A number corresponding to the error code in case of failure during the import process, that is, when the `success` item has a `false` value
+        queue_id:
+          type: string
+          title: Queue ID
+          description:  A unique identifier for the import process in the importing queue. It is the same as the `import_id` provided in the request
+        tables_created_count:
+          type: number
+          title: Tables created counter
+          description: The number of tables that the import process generated. For multi-file uploads, this value can be greater than one
+          nullable: true
+        synchronization_id:
+          type: string
+          title: Synchronization ID
+          description: This element has a `null` value when the import is not configured as a Sync Table
+          nullable: true
+        type_guessing:
+          type: boolean
+          title: Type guessing
+          description: A boolean indicating whether field type guessing (for Excel and CSVs) is enabled or not
+        quoted_fields_guessing:
+          type: boolean
+          title: Quoted fields guessing
+          description: A boolean indicating whether type guessing of CSV fields inside double quotes is enabled for the data import
+        content_guessing:
+          type: boolean
+          title: Content guessing
+          description: A boolean indicating whether content guessing and automatic geocoding is enabled for the data import
+        create_visualization:
+          type: boolean
+          title: Create visualization
+          description:   A boolean indicating whether the import process will create a map automatically or not. Its value corresponds to the import option `create_vis` chosen by the user
+        visualization_id:
+          type: string
+          title: Visualization ID
+          description: A unique identifier for the map created in the import process. Only applies if `created_visualization` is set to `true`
+          nullable: true
+        get_error_text:
+          type: string
+          title: Get error text
+          description: This element contains an error description to be outputted in case of a failure during the import process. It contains the error title and description, its source (`user` or `cartodb`), and troubleshooting details
+        display_name:
+          type: string
+          title: Display name
+          description: Similar to `table_name`. For `url` uploads, it shows the name of the file. Otherwise, it shows the `import_id`
+        success:
+          type: boolean
+          title: Success
+          description: A boolean value indicating whether the import process succeeded
+        warnings:
+          type: string
+          title: Warnings
+          description: A text field containing warning messages related to the import process, if applicable of the file. Otherwise, it shows the `import_id`
+          nullable: true
+        is_raster:
+          type: boolean
+          title: Is raster
+          description: A boolean value indicating whether the imported table contains raster data or not
+    ExportCarto:
+      type: object
+      properties:
+        visualization_id:
+          type: string
+          title: Visualization ID
+          description: A unique identifier for the map created in the export process. Only applies if `created_visualization` is set to `true` when the map was created. 
+    ExportCartoResponse:
+      type: object
+      properties:
+        id:
+          type: string
+          title: ID
+          description: A unique identifier for the export process. It is the same as the _export id_ provided in the request
+        visualization_id:
+          type: string
+          title: Visualization ID
+          description: A unique identifier for the map created in the export process. Only applies if `created_visualization` is set to `true` when the map was created
+        user_id:
+          type: string
+          title: User ID
+          description: A unique alphanumeric element that identifies the CARTO account user in the internal database
+        state:
+          type: string
+          enum:
+            - enqueued
+            - pending
+            - uploading
+            - unpacking
+            - importing
+            - guessing
+            - complete
+            - failure 
+          title: State
+          description: A string value indicating the current state of the export process
+        url:
+          type: string
+          title: URL
+          description: The **public** URL address where the file to be exported is located
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+          title: Created at
+          description: The date time at which the visualization was created in the CARTO database
+        updated_at:
+          type: string
+          format: date-time
+          title: Updated at
+          description: The date time at which the visualization had its contents modified
+    SyncTablesResponseItem:
+      type: object
+      properties:
+        id:
+          type: string
+          title: ID
+          description: A unique alphanumeric identifier of the synced table
+        name:
+          type: string
+          title: Name
+          description: The actual name of the created sync table
+        interval:
+          type: integer
+          title: Interval
+          description: An integer value representing the number of seconds between synchronizations of the table contents
+        url:
+          type: string
+          title: URL
+          description: The **public** URL address where the file to be synchronized is located
+          nullable: true
+        state:
+          type: string
+          enum:
+            - created
+            - queued
+            - syncing
+            - success
+            - failure
+          title: State
+          description: A string value indicating the current state of the synchronized dataset
+        created_at:
+          type: string
+          format: date-time
+          title: Created at
+          description: The date time at which the table was created in the CARTO database
+        updated_at:
+          type: string
+          format: date-time
+          title: Updated at
+          description: The date time at which the table had its contents modified
+        run_at:
+          type: string
+          format: date-time
+          title: Run at
+          description: The date time at which the table **will** get its contents synched with the source file
+        retried_times:
+          type: integer
+          title: Retried times
+          description: An integer value indicating the number of attempts that were performed to sync the table
+        log_id:
+          type: string
+          title: Log ID
+          description: A unique alphanumeric identifier to locate the log traces of the given table
+        error_code:
+          type: integer
+          title: Error code
+          description: An integer value representing a unique error identifier
+          nullable: true
+        error_message:
+          type: string
+          title: Error message
+          description: A string value indicating the message related to the _error_code_ element
+          nullable: true
+        ran_at:
+          type: string
+          format: date-time
+          title: Ran at
+          description: The date time at which the table **had** its contents synched with the source file
+        modified_at:
+          type: string
+          format: date-time
+          title: Modified at
+          description: The date time at which the table was manually modified, if applicable
+        etag:
+          type: string
+          title: ETAG
+          description: HTTP entity tag of the source file
+          nullable: true
+        checksum:
+          type: string
+          title: Checksum
+          description: See **etag**
+          nullable: true
+        user_id:
+          type: string
+          title: User ID
+          description: A unique alphanumeric element that identifies the CARTO account user in the internal database
+        service_name:
+          type: string
+          enum:
+            - gdrive
+            - dropbox
+          title: State
+          description: |
+            A string with the name of the datasource used to import the file
+            It can have any of the following values: 
+            - **gdrive** - Google Drive
+            - **dropbox** - Dropbox
+            - `null` - URL imports
+          nullable: true
+        service_item_id:
+          type: string
+          title: Service item ID
+          description: A unique identifier used by CARTO to reference the sync table and its related datasource service
+        type_guessing:
+          type: boolean
+          title: Type guessing
+          description:   If set to `false` disables field type guessing (for Excel and CSVs)
+        quoted_fields_guessing:
+          type: boolean
+          title: Quoted fields guessing
+          description:   If set to `false` disables type guessing of CSV fields that come inside double quotes
+        content_guessing:
+          type: boolean
+          title: Content guessing
+          description:   Set to `true` to enable content guessing and automatic geocoding based on results. Currently, this only implements geocoding of countries, cities and IP addresses
+        visualization_id:
+          type: string
+          title: Visualization ID
+          description: A unique identifier for the map created in the import process. Only applies if created_visualization is set to `true`
+        from_external_source:
+          type: boolean
+          title: From external source
+          description: A boolean indicating whether the Sync Table is connected to an external source, generally the CARTO Data library
+    ListSyncTablesResponse:
+      type: object
+      properties:
+        syncronizations:
+          type: array
+          items:
+            $ref: '#/components/schemas/SyncTablesResponseItem'
+        total_entries:
+          type: integer
+          title: Total entries
+          description: Number of items contained in the response array
+    CreateSyncTablesPayload:
+      type: object
+      properties:
+        url:
+          type: string
+          title: URL
+          description: The **public** URL address where the file to be imported is located
+        interval:
+          type: integer
+          title: Interval
+          minimum: 900
+          description: 'The number of seconds for the synchronization period. Note: Sync interval must be at least 900 (15 minutes)'
+        type_guessing:
+          type: boolean
+          title: Type guessing
+          default: true
+          description:   If set to `false` disables field type guessing (for Excel and CSVs)
+        quoted_fields_guessing:
+          type: boolean
+          title: Quoted fields guessing
+          default: true
+          description:   If set to `false` disables type guessing of CSV fields that come inside double quotes
+        content_guessing:
+          type: boolean
+          title: Content guessing
+          default: false
+          description:  Set to `true` to enable content guessing and automatic geocoding based on results. Currently, this only implements geocoding of countries, cities and IP addresses
+    CreateSyncTablesResponse:
+      allOf:
+        - type: object
+          properties:
+            data_import:
+              type: object
+              properties:
+                endpoint:
+                  type: string
+                  title: Endpoint
+                  description: This item refers to the internal CARTO controller code responsible for performing the import
+                item_queue_id:
+                  type: string
+                  title: Item queue ID
+                  description: A unique alphanumeric identifier that refers to the import process. It can be used to retrieve data related to the created table
+        - $ref: '#/components/schemas/SyncTablesResponseItem'
+          
+  securitySchemes:
+    ApiKeyHTTPBasicAuth:
+      type: http
+      scheme: basic
+    ApiKeyQueryParam:
+      type: apiKey
+      in: header
+      name: api_key
+  examples:
+    CreateImportUrl:
+      value:
+        url: https://remotehost.url/path/to/remotefile
+      summary: Import from URL
+    RequestResponseSuccess:
+      value:
+        item_queue_id: 9906bce0-f1a3-4b07-be71-818f4bfd7673
+        success: true
+      summary: A success response  
+  responses:
+    NotFound:
+      description: The specified resource was not found
+    Unauthorized:
+      description: Unauthorized. No authentication provided.
+    Forbidden:
+      description: Forbidden. The API key does not authorize this request.
+    BadInput:
+      description: Request's parameters error

doc/developer-center/import-api/support/01-support-options.md

@@ -0,0 +1,36 @@
+## Support Options
+
+Feeling stuck? There are many ways to find help.
+
+* Ask a question on [GIS StackExchange](https://gis.stackexchange.com/questions/tagged/carto) using the `CARTO` tag.
+* [Report an issue](https://github.com/CartoDB/cartodb/issues) in Github.
+* Engine Plan customers have additional access to enterprise-level support through CARTO's support representatives.
+
+If you just want to describe an issue or share an idea, just <a class="typeform-share" href="https://cartohq.typeform.com/to/mH6RRl" data-mode="popup" target="_blank"> send your feedback</a>
+
+### Issues on Github
+
+If you think you may have found a bug, or if you have a feature request that you would like to share with the Import API team, please [open an issue](https://github.com/CartoDB/cartodb/issues/new). 
+
+Before opening an issue, review the [contributing guidelines](https://github.com/CartoDB/cartodb/blob/master/CONTRIBUTING.md).
+
+
+### Community support on GIS Stack Exchange
+
+GIS Stack Exchange is the most popular community in the geospatial industry. This is a collaboratively-edited question and answer site for geospatial programmers and technicians. It is a fantastic resource for asking technical questions about developing and maintaining your application.
+
+
+When posting a new question, please consider the following:
+
+* Read the GIS Stack Exchange [help](https://gis.stackexchange.com/help) and [how to ask](https://gis.stackexchange.com/help/how-to-ask) pages for guidelines and tips about posting questions.
+* Be very clear about your question in the subject. A clear explanation helps those trying to answer your question, as well as those who may be looking for information in the future.
+* Be informative in your post. Details, code snippets, logs, screenshots, etc. help others to understand your problem.
+* Use code that demonstrates the problem. It is very hard to debug errors without sample code to reproduce the problem.
+
+### Engine Plan Customers
+
+Engine Plan customers have additional support options beyond general community support. As per your account Terms of Service, you have access to enterprise-level support through CARTO's support representatives available at [enterprise-support@carto.com](mailto:enterprise-support@carto.com)
+
+In order to speed up the resolution of your issue, provide as much information as possible (even if it is a link from community support). This allows our engineers to investigate your problem as soon as possible.
+
+If you are not yet CARTO customer, browse our [plans & pricing](https://carto.com/pricing/) and find the right plan for you.

doc/developer-center/import-api/support/02-contribute.md

@@ -0,0 +1,36 @@
+## Contribute
+
+CARTO platform is an open-source ecosystem. You can read about the [fundamentals]({{site.fundamental_docs}}/components/) of CARTO architecture and its components.
+We are more than happy to receive your contributions to the code and the documentation as well.
+
+## Filling a ticket
+
+If you want to open a new issue in our repository, please follow these instructions:
+
+1. Descriptive title.
+2. Write a good description, it always helps.
+3. Specify the steps to reproduce the problem.
+4. Try to add an example showing the problem.
+
+## Contributing code
+
+Best part of open source, collaborate in Import API code!. We like hearing from you, so if you have any bug fixed, or a new feature ready to be merged, those are the steps you should follow:
+
+1. Fork the repository.
+2. Create a new branch in your forked repository.
+3. Commit your changes. Add new tests if it is necessary.
+4. Open a pull request.
+5. Any of the maintainers will take a look.
+6. If everything works, it will merged and released \o/.
+
+If you want more detailed information, this [GitHub guide](https://guides.github.com/activities/contributing-to-open-source/) is a must.
+
+## Completing documentation
+
+Import API documentation is located in ```docs/```. That folder is the content that appears in the [Developer Center](http://carto.com/developers/import-api/). Just follow the instructions described in [contributing code](#contributing-code) and after accepting your pull request, we will make it appear online :).
+
+**Tip:** A convenient, easy way of proposing changes in documentation is by using the GitHub editor directly on the web. You can easily create a branch with your changes and make a PR from there.
+
+## Submitting contributions
+
+You will need to sign a Contributor License Agreement (CLA) before making a submission. [Learn more here](https://carto.com/contributions).

doc/developer-center/import-api/support/03-import-errors.md

@@ -0,0 +1,258 @@
+
+## Import Errors
+
+You may receive an error during the import process when connecting a dataset. This section contains any known error codes, and provides descriptions to help you troubleshoot why your import may have failed. Please [contact us](mailto:support@carto.com) if you need assistance.
+
+The following table contains a list of known errors codes and possible solutions.
+
+<table>
+  <thead>
+    <tr>
+      <th>Code</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1000</td>
+      <td>File I/O error - Something seems to be wrong with the file you uploaded. Check that it is loading fine locally and try uploading it again.</td>
+    </tr>
+    <tr>
+      <td>1001</td>
+      <td>Download error - The remote URL returned an error. Please verify your file is available at that URL.</td>
+    </tr>
+    <tr>
+      <td>1002</td>
+      <td>Unsupported file type - Check our <a href="{{site.importapi_docs}}/guides/importing-geospatial-data/#supported-geospatial-data-formats">list of supported files</a>. See if you can convert your file to one of these file types. If importing from a URL, make sure the remote server is returning the appropriate HTTP Content Type headers for the file type.</td>
+    </tr>
+    <tr>
+      <td>1003</td>
+      <td>Decompression error - Try decompressing and regenerating your compressed file on your computer. If that fails, then locate the original file and make a new compressed version.</td>
+    </tr>
+    <tr>
+      <td>1004</td>
+      <td>XLS/XLSX Error - The XLS/XLSX archive could not be opened or contains data that cannot be imported. Try exporting it into CSV and uploading the CSV instead.</td>
+    </tr>
+    <tr>
+      <td>1005</td>
+      <td>Empty file - The file appears to have no processable information. Double check that the file is indeed correct and that it contains supported data.</td>
+    </tr>
+    <tr>
+      <td>1006</td>
+      <td>Invalid SHP file - Your file appears broken. Double check that all the necessary parts of the file are included in your ZIP archive (including .SHP, .PRJ, etc.). Also, try opening the file locally using QGIS or another tool.</td>
+    </tr>
+    <tr>
+      <td>1007</td>
+      <td>Too many nodes - You requested too many nodes. Either request a smaller area, or use planet.osm.</td>
+    </tr>
+    <tr>
+      <td>1008</td>
+      <td>GDrive access forbidden - Google denied access to GDrive. If you use Google Apps contact your administrator to allow third party Drive applications and try again.</td>
+    </tr>
+    <tr>
+      <td>1009</td>
+      <td>Twitter Server Error - There was an error connecting to Twitter service to retrieve your tweets. The server might be temporally unavaliable, please try again later.</td>
+    </tr>
+    <tr>
+      <td>1010</td>
+      <td>Not a file - Your import request does not contain a file. Make sure that the request is correctly formatted and/or a file is being posted.</td>
+    </tr>
+     <tr>
+      <td>1011</td>
+      <td>Error retrieving data from datasource - There was an error retrieving data from the datasource. Check that the file/data is still present.</td>
+    </tr>
+    <tr>
+      <td>1012</td>
+      <td>Error connecting to datasource - There was an error trying to connect to the datasource. If this problem stays, please contact <a href='mailto:support@carto.com?subject=Error connecting to datasource'>support@carto.com</a>.</td>
+    </tr>
+    <tr>
+      <td>1013</td>
+      <td>Invalid ArcGIS version - The specified ArcGIS server runs an unsupported version. Supported versions are 10.1 onwards.</td>
+    </tr>
+    <tr>
+      <td>1014</td>
+      <td>Invalid name - File name is not valid. Maybe too many tables with similar names. Please change file name and try again.</td>
+    </tr>
+    <tr>
+      <td>1015</td>
+      <td>No results - Query was correct but returned no results, please change the parameters and run it again.</td>
+    </tr>
+    <tr>
+      <td>1016</td>
+      <td>Dropbox permission revoked - CARTO has no permission to access your files at Dropbox. Please import file again.</td>
+    </tr>
+    <tr>
+      <td>1017</td>
+      <td>GDrive file was deleted - GDrive file was removed and can't be synced, please import file again.</td>
+    </tr>
+    <tr>
+      <td>1018</td>
+      <td>File is password protected - File is password protected and can't be imported. Please remove password protection or create a new compressed file without password and try again.</td>
+    </tr>
+    <tr>
+      <td>1019</td>
+      <td>Too Many Layers - The file has too many layers. It can have 50 as maximum.</td>
+    </tr>
+    <tr>
+      <td>1020</td>
+      <td>Download timeout - Data download timed out. Check the source is not running slow and/or try again.</td>
+    </tr>
+    <tr>
+      <td>1021</td>
+      <td>Box permission revoked - CARTO has no permission to access your files at Box. Please import file again.</td>
+    </tr>
+    <tr>
+      <td>1100</td>
+      <td>Download file not found - Provided URL doesn't return a file (error 404). Please check that URL is still valid and that you can download the file and try again.</td>
+    </tr>
+    <tr>
+      <td>1101</td>
+      <td>Forbidden file URL - Provided URL returns authentication error. Maybe it's private, or requires user and password. Please provide a valid, public URL and try again.</td>
+    </tr>
+    <tr>
+      <td>1102</td>
+      <td>Unknown server URL - Provided URL can't be resolved to a known server. Maybe that URL is wrong or behind a private network. Please provide a valid, public URL and try again.</td>
+    </tr>
+    <tr>
+      <td>2001</td>
+      <td>Unable to load data - We couldn't load data from your file into the database.  Please <a href='mailto:support@carto.com?subject=Import load error'>contact us</a> and we will help you to load your data.</td>
+    </tr>
+    <tr>
+      <td>2002</td>
+      <td>Encoding detection error - We couldn't detect the encoding of your file. Please, try saving your file with encoding UTF-8 or <a href='mailto:support@carto?subject=Encoding error in import'>contact us</a> and we will help you to load your data.</td>
+    </tr>
+    <tr>
+      <td>2003</td>
+      <td>Malformed CSV - The CSV or converted XLS/XLSX to CSV file contains malformed or invalid characters. Some reasons for this error can be for example multiline header fields or multiline cells at Excel files or unquoted CSV.</td>
+    </tr>
+    <tr>
+      <td>2004</td>
+      <td>Too many columns - Data has too many columns. You can only import up to 250 columns.</td>
+    </tr>
+    <tr>
+      <td>2005</td>
+      <td>Duplicated column - File has the same header for two or more columns. Please make column names unique and try again.</td>
+    </tr>
+    <tr>
+      <td>2006</td>
+      <td>Encoding error - Problem reading the file. Encoding seems wrong, probably because there's a wrong character. In order to sort it out, open your file with a text editor, save it with encoding UTF-8 and try again.</td>
+    </tr>
+    <tr>
+      <td>2007</td>
+      <td>Encoding error - The file you tried to import failed due to encoding issues. To fix this, force the encoding of your file using a text editor or a tool like QGis. You just need to export your files in UTF-8 format.</td>
+    </tr>
+    <tr>
+      <td>2008</td>
+      <td>Malformed XLS - The Excel file has an unsupported format or is corrupt. To fix this, open it and save as CSV or XLSX.</td>
+    </tr>
+    <tr>
+      <td>2009</td>
+      <td>KML without style Id - The KML file you tried to import failed because a style element doesn't have an ID attribute. To fix this error, please open the file and add an ID to all the style tags.</td>
+    </tr>
+    <tr>
+      <td>2010</td>
+      <td>Incompatible CARTO table - There was an error when converting your table into a CARTO table. Please <a href='mailto:support@carto.com?subject=CartoDBfy error'>contact us</a> and we will help you load your data.</td>
+    </tr>
+    <tr>
+      <td>2011</td>
+      <td>Invalid `cartodb_id` column - The import failed because your table contains an invalid `cartodb_id` column. If you want to use it as a primary key, its values must be integers, non-null, and unique. Otherwise, try renaming your current `cartodb_id` column.</td>
+    </tr>
+    <tr>
+      <td>2012</td>
+      <td>Incompatible schemas - The import failed because you are trying to overwrite a table but the data you are providing is not compatible with the data that table already has. You may me changing some types or removing a column. Please check and try again.</td>
+    </tr>
+     <tr>
+      <td>2013</td>
+      <td>Cannot overwrite table - The synchronization failed because the destination table could not be overwritten. Please make sure that there are no database objects (e.g: views) that depend on it.</td>
+    </tr>
+     <tr>
+      <td>2014</td>
+      <td>Invalid geometries - Your file appears to contain invalid geometries. Try opening the file with another GIS tool and checking the geometry validity.</td>
+    </tr>
+    <tr>
+      <td>3007</td>
+      <td>JSON may not be valid GeoJSON - We can only import GeoJSON formated JSON files. See if the source of this data supports GeoJSON or another file format for download.</td>
+    </tr>
+    <tr>
+      <td>3008</td>
+      <td>Unknown SRID - The SRID of the provided file it's not in the spatial_ref_sys table. You can get rid of this error inserting the SRID specific data in the spatial_ref_sys table.</td>
+    </tr>
+    <tr>
+      <td>3009</td>
+      <td>SHP Normalization error - We were unable to detect the encoding or projection of your Shapefile. Try converting the file to UTF-8 and a 4326 SRID.</td>
+    </tr>
+    <tr>
+      <td>3101</td>
+      <td>Missing projection (.prj) file - CARTO needs a PRJ file for all Shapefile archives uploaded. Contact your data provider to see about aquiring one if it was missing. Otherwise see spatialreference.org to locate the right one if you know it. Remember, the file name for your .prj must be the same as your .shp.</td>
+    </tr>
+    <tr>
+      <td>3201</td>
+      <td>Geometry Collection not supported - We are working to support more formats every day, but currently we cannot take mixed geometry types. Take a look at your data source and see if other formats are available, otherwise, look into tools like OGR to split this file into valid ESRI Shapefiles prior to importing.</td>
+    </tr>
+    <tr>
+      <td>3202</td>
+      <td>Empty KML - This KML doesn't include actual data, but a link to another KML with the data. Please extract the URL from this KML and try to import it.</td>
+    </tr>
+    <tr>
+      <td>8001</td>
+      <td>Over account storage limit, please upgrade - To upgrade your account, go to your Dashboard and click Settings. Click 'Upgrade your server'. Follow the directions for choosing a larger size and setting up your payment information.</td>
+    </tr>
+    <tr>
+      <td>8002</td>
+      <td>You have reached the limit of datasets for your plan. Upgrade your account to get unlimited datasets - To upgrade your account, go to your Dashboard and click Settings. Click 'Upgrade your server'. Follow the directions for choosing a larger size and setting up your payment information.</td>
+    </tr>
+    <tr>
+      <td>8003</td>
+      <td>Error creating table from SQL query - We couldn't create a table from your query. Please check that it doesn't return duplicate column names.</td>
+    </tr>
+    <tr>
+      <td>8004</td>
+      <td>Merge with unmatching column types - The columns you have chosen don't have the same column type in both tables. Please change the types so the columns will have the same type and try again.</td>
+    </tr>
+    <tr>
+      <td>8005</td>
+      <td>Max layers per map reached - You can't add more layers to your map. Please upgrade your account.</td>
+    </tr>
+    <tr>
+      <td>8006</td>
+      <td>Not enough Twitter credits - Unfortunately, you don't have enough Twitter credits to proceed. Please contact <a href='mailto:sales@carto.com?subject=Exceeded%20Twitter%20quota'>Sales</a> if you have questions about how to obtain more credits.</td>
+    </tr>
+    <tr>
+      <td>8007</td>
+      <td>Over account public maps limit, please upgrade - To upgrade your account, go to your Dashboard and click Settings. Click 'Upgrade your server'. Follow the directions for choosing a larger size and setting up your payment information.</td>
+    </tr>
+    <tr>
+      <td>6666</td>
+      <td>Dataset too big - The dataset you tried to import is too big and cannot be processed. If the dataset allows it, you can try splitting it into smaller files and then append them once imported, or contact our support team at <a href='mailto:support@carto.com?subject=Dataset%20too%20big%20import%20error'>support@carto.com</a>.</td>
+    </tr>
+    <tr>
+      <td>6667</td>
+      <td>Import timed out - There is been a problem importing your file due to the time is been taking to process it. Please try again and contact us if the problem persist.</td>
+    </tr>
+    <tr>
+      <td>6668</td>
+      <td>Too many table rows - You cannot import this dataset. The number of rows exceeds the maximum dataset quota permitted for your account. Please contact <a href='mailto:sales@carto.com?subject=Dataset%20too%20many%20table%20rows%20import%20error'>Sales</a> if you have questions about importing this dataset.</td>
+    </tr>
+    <tr>
+      <td>6669</td>
+      <td>Too many concurrent imports - You cannot import more data until one of your active imports finishes. If you need further import slots contact our support team at <a href='mailto:support@carto.com?subject=Dataset%20too%20many%20concurrent%20imports%20error'>support@carto.com</a>.</td>
+    </tr>
+    <tr>
+      <td>6670</td>
+      <td>Too many map templates - You reached the limit of Named Map templates. If you are programatically generating these templates, check how to delete them in the <a href="{{site.mapsapi_docs}}/guides/quickstart/#named-maps">Maps API documentation</a>. Otherwise, contact our support team at <a href='mailto:support@carto.com?subject=Dataset%20too%20many%20concurrent%20imports%20error'>support@carto.com</a>.</td>
+    </tr>
+    <tr>
+      <td>6671</td>
+      <td>Stuck import job - The import job was stuck and we marked it as failed. Please try again and contact our support team at <a href='mailto:support@carto.com?subject=Dataset%20import%20stuck%20error'>support@carto.com</a> if the problem persists.</td>
+    </tr>
+    <tr>
+      <td>99999</td>
+      <td>Unknown - Sorry, something went wrong and we're not sure what. Try
+      uploading your file again, or <a href='mailto:support@carto.com?subject=Unknown error'>contact us</a> and we'll try to help you quickly.</td>
+    </tr>
+  </tbody>
+</table>
+
+### cURL Commands in Windows
+
+If you are running cURL commands through a PC console, note that Windows only supports double quotes "" for cURL commands.

doc/developer-center/import-api/support/04-limits.md

@@ -0,0 +1,18 @@
+## Limits
+
+Limits ensure that CARTO platform is not flooded with so many requests it does not have the time and resources to service them all.
+
+Currently, Import API is affected by a number of limits.
+
+
+### Limits Chart
+
+Below, you can find the values of the timeout limit by user account type. 
+
+|    |Free| Pro |Enterprise|
+|--- | --- | ---| ---| 
+|Maximum concurrent imports | 3 imports enqueued per request | 3 imports enqueued per request | 3 imports enqueued per request
+|Maximum row count | 500K | 500K | 1M
+|Maximum file size | 150MB | 500MB | 1GB
+|Maximum feature vertex count | 10K | 10K | 10K
+|Maximum number of tables | 2000 tables | 2000 tables | 2000 tables