972 lines
38 KiB
YAML
972 lines
38 KiB
YAML
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
|