airtable

package module
v0.3.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 14, 2025 License: MIT Imports: 11 Imported by: 28

README

Golang Airtable API

GoDoc Go codecov Go Report Mentioned in Awesome Go

A simple #golang package to access the Airtable API.

Table of contents

Installation

The Golang Airtable API has been tested compatible with Go 1.13 on up.

go get github.com/mehanizm/airtable

Basic usage

Initialize client

You should get your_api_token in the airtable account page

client := airtable.NewClient("your_api_token")

You can use custom http client here

client.SetCustomClient(http.DefaultClient)
Custom context

Each method below can be used with custom context. Simply use MethodNameContext call and provide context as first argument.

List bases
bases, err := client.GetBases().WithOffset("").Do()
Get base schema
schema, err := client.GetBaseSchema("your_database_ID").Do()
Get table

To get the your_database_ID you should go to main API page and select the database.

table := client.GetTable("your_database_ID", "your_table_name")
List records

To get records from the table you can use something like this

records, err := table.GetRecords().
	FromView("view_1").
	WithFilterFormula("AND({Field1}='value_1',NOT({Field2}='value_2'))").
	WithSort(sortQuery1, sortQuery2).
	ReturnFields("Field1", "Field2").
	InStringFormat("Europe/Moscow", "ru").
	Do()
if err != nil {
	// Handle error
}
Add records
recordsToSend := &airtable.Records{
    Records: []*airtable.Record{
        {
            Fields: map[string]any{
                "Field1": "value1",
                "Field2": true,
            },
        },
    },
}
receivedRecords, err := table.AddRecords(recordsToSend)
if err != nil {
	// Handle error
}
Get record by ID
record, err := table.GetRecord("recordID")
if err != nil {
	// Handle error
}
Update records

To partial update one record

res, err := record.UpdateRecordPartial(map[string]any{"Field_2": false})
if err != nil {
	// Handle error
}

To full update records

toUpdateRecords := &airtable.Records{
    Records: []*airtable.Record{
        {
            Fields: map[string]any{
                "Field1": "value1",
                "Field2": true,
            },
        },
        {
            Fields: map[string]any{
                "Field1": "value1",
                "Field2": true,
            },
        },
    },
}
updatedRecords, err := table.UpdateRecords(toUpdateRecords)
if err != nil {
	// Handle error
}
Delete record
res, err := record.DeleteRecord()
if err != nil {
	// Handle error
}
Bulk delete records

To delete up to 10 records

records, err := table.DeleteRecords([]string{"recordID1", "recordsID2"})
if err != nil {
	// Handle error
}

Special thanks

Inspired by Go Trello API

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotDateTime = errors.New("field is not date time")

Functions

func FromDateTime added in v0.2.7 

func FromDateTime(t time.Time) any

func ToDateTime added in v0.2.7 

func ToDateTime(field any) (time.Time, error)

Types

type Attachment added in v0.3.3 

type Attachment struct {
	ContentType string `json:"contentType"`
	File        string `json:"file"`
	FileName    string `json:"filename"`
}

type Base added in v0.2.8 

type Base struct {
	ID              string `json:"id"`
	Name            string `json:"name"`
	PermissionLevel string `json:"permissionLevel"`
}

Base type of airtable base.

type BaseConfig added in v0.2.8 

type BaseConfig struct {
	// contains filtered or unexported fields
}

Table represents table object.

func (*BaseConfig) Do added in v0.2.8 

func (b *BaseConfig) Do() (*Tables, error)

Do send the prepared

func (*BaseConfig) DoContext added in v0.3.1 

func (b *BaseConfig) DoContext(ctx context.Context) (*Tables, error)

Do send the prepared with custom context

func (*BaseConfig) GetTables added in v0.3.1 

func (b *BaseConfig) GetTables() (*Tables, error)

GetTables get tables from a base with url values params https://airtable.com/developers/web/api/get-base-schema

func (*BaseConfig) GetTablesContext added in v0.3.1 

func (b *BaseConfig) GetTablesContext(ctx context.Context) (*Tables, error)

getTablesContext get tables from a base with url values params with custom context

type Bases added in v0.2.8 

type Bases struct {
	Bases  []*Base `json:"bases"`
	Offset string  `json:"offset,omitempty"`
}

Base type of airtable bases.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client client for airtable api.

func NewClient 

func NewClient(apiKey string) *Client

NewClient airtable client constructor your API KEY you can get on your account page https://airtable.com/account

func (*Client) GetBaseSchema added in v0.2.8 

func (c *Client) GetBaseSchema(dbId string) *BaseConfig

GetBase return Base object.

func (*Client) GetBases added in v0.2.8 

func (c *Client) GetBases() *GetBasesConfig

GetBases prepare step to get bases.

func (*Client) GetBasesWithParams added in v0.2.8 

func (at *Client) GetBasesWithParams(params url.Values) (*Bases, error)

GetBasesWithParams get bases with url values params https://airtable.com/developers/web/api/list-bases

func (*Client) GetBasesWithParamsContext added in v0.3.1 

func (at *Client) GetBasesWithParamsContext(ctx context.Context, params url.Values) (*Bases, error)

getBasesWithParamsContext get bases with url values params with custom context

func (*Client) GetTable 

func (c *Client) GetTable(dbName, tableName string) *Table

GetTable return table object.

func (*Client) SetBaseURL added in v0.2.5 

func (at *Client) SetBaseURL(baseURL string) error

func (*Client) SetCustomClient added in v0.3.1 

func (at *Client) SetCustomClient(client *http.Client)

Set custom http client for custom usage

func (*Client) SetRateLimit 

func (at *Client) SetRateLimit(customRateLimit int)

SetRateLimit rate limit setter for custom usage Airtable limit is 5 requests per second (we use 4) https://airtable.com/{yourDatabaseID}/api/docs#curl/ratelimits

type Field added in v0.2.8 

type Field struct {
	ID          string         `json:"id"`
	Type        string         `json:"type"`
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Options     map[string]any `json:"options"`
}

type FieldAttachmentDetails added in v0.3.3 

type FieldAttachmentDetails struct {
	// Airtable's attachment ID
	Id       string `json:"id"`
	URL      string `json:"url"`
	FileName string `json:"filename"`
	// In bytes
	Size int `json:"size"`
	// Content-Type value
	Type string `json:"type"`
}

type FieldAttachments added in v0.3.3 

type FieldAttachments struct {

	// Parent record's ID of the attached file.
	Id          string `json:"id"`
	CreatedTime string `json:"createdTime"`
	// Mapped array of attachments attached to this field.
	//
	// Key is the ID of the record's attachment field and the value is the list of attached files.
	Attachments map[string][]FieldAttachmentDetails `json:"fields"`
	// contains filtered or unexported fields
}

type GetBasesConfig added in v0.2.8 

type GetBasesConfig struct {
	// contains filtered or unexported fields
}

GetBasesConfig helper type to use in. step by step get bases.

func (*GetBasesConfig) Do added in v0.2.8 

func (gbc *GetBasesConfig) Do() (*Bases, error)

Do send the prepared get records request.

func (*GetBasesConfig) DoContext added in v0.3.2 

func (gbc *GetBasesConfig) DoContext(ctx context.Context) (*Bases, error)

DoContext send the prepared get records request with context.

func (*GetBasesConfig) WithOffset added in v0.2.8 

func (gbc *GetBasesConfig) WithOffset(offset string) *GetBasesConfig

WithOffset Pagination will stop when you've reached the end of your bases.

type GetRecordsConfig 

type GetRecordsConfig struct {
	// contains filtered or unexported fields
}

GetRecordsConfig helper type to use in. step by step get records.

func (*GetRecordsConfig) Do 

func (grc *GetRecordsConfig) Do() (*Records, error)

Do send the prepared get records request.

func (*GetRecordsConfig) DoContext added in v0.3.2 

func (grc *GetRecordsConfig) DoContext(ctx context.Context) (*Records, error)

DoContext send the prepared get records request with context.

func (*GetRecordsConfig) FromView 

func (grc *GetRecordsConfig) FromView(viewNameOrID string) *GetRecordsConfig

FromView add view parameter to get records.

func (*GetRecordsConfig) InStringFormat 

func (grc *GetRecordsConfig) InStringFormat(timeZone, userLocale string) *GetRecordsConfig

InStringFormat add parameter to get records in string format. it require timezone https://support.airtable.com/hc/en-us/articles/216141558-Supported-timezones-for-SET-TIMEZONE and user locale data https://support.airtable.com/hc/en-us/articles/220340268-Supported-locale-modifiers-for-SET-LOCALE

func (*GetRecordsConfig) MaxRecords added in v0.2.0 

func (grc *GetRecordsConfig) MaxRecords(maxRecords int) *GetRecordsConfig

MaxRecords The maximum total number of records that will be returned in your requests. If this value is larger than pageSize (which is 100 by default), you may have to load multiple pages to reach this total. See the Pagination section below for more.

func (*GetRecordsConfig) PageSize added in v0.2.0 

func (grc *GetRecordsConfig) PageSize(pageSize int) *GetRecordsConfig

PageSize The number of records returned in each request. Must be less than or equal to 100. Default is 100. See the Pagination section below for more.

func (*GetRecordsConfig) ReturnFields 

func (grc *GetRecordsConfig) ReturnFields(fieldNames ...string) *GetRecordsConfig

ReturnFields set returning field names.

func (*GetRecordsConfig) WithFieldsById added in v0.3.4 

func (grc *GetRecordsConfig) WithFieldsById() *GetRecordsConfig

WithFieldsById returns the Record fields by field ID instead of names.

func (*GetRecordsConfig) WithFilterFormula 

func (grc *GetRecordsConfig) WithFilterFormula(filterFormula string) *GetRecordsConfig

WithFilterFormula add filter to request.

func (*GetRecordsConfig) WithOffset added in v0.2.0 

func (grc *GetRecordsConfig) WithOffset(offset string) *GetRecordsConfig

WithOffset Pagination will stop when you've reached the end of your table. If the maxRecords parameter is passed, pagination will stop once you've reached this maximum.

func (*GetRecordsConfig) WithSort 

func (grc *GetRecordsConfig) WithSort(sortQueries ...struct {
	FieldName string
	Direction string
},
) *GetRecordsConfig

WithSort add sorting to request.

type HTTPClientError 

type HTTPClientError struct {
	StatusCode int
	Err        error
}

HTTPClientError custom error to handle with response status.

func (*HTTPClientError) Error 

func (e *HTTPClientError) Error() string

type PerformUpsert added in v0.3.3 

type PerformUpsert struct {
	FieldsToMergeOn []string `json:"fieldsToMergeOn"`
}

type Record 

type Record struct {
	ID          string         `json:"id,omitempty"`
	Fields      map[string]any `json:"fields"`
	CreatedTime string         `json:"createdTime,omitempty"`
	Deleted     bool           `json:"deleted,omitempty"`

	// The Airtable API will perform best-effort automatic data conversion
	// from string values if the typecast parameter is passed in.
	// Automatic conversion is disabled by default to ensure data integrity,
	// but it may be helpful for integrating with 3rd party data sources.
	Typecast bool `json:"typecast,omitempty"`
	// contains filtered or unexported fields
}

Record base time of airtable record fields.

func (*Record) DeleteRecord 

func (r *Record) DeleteRecord() (*Record, error)

DeleteRecord delete one record.

func (*Record) DeleteRecordContext added in v0.3.1 

func (r *Record) DeleteRecordContext(ctx context.Context) (*Record, error)

DeleteRecordContext delete one record with custom context

func (*Record) UpdateRecordPartial 

func (r *Record) UpdateRecordPartial(changedFields map[string]any) (*Record, error)

UpdateRecordPartial updates partial info on record.

func (*Record) UpdateRecordPartialContext added in v0.3.1 

func (r *Record) UpdateRecordPartialContext(ctx context.Context, changedFields map[string]any) (*Record, error)

UpdateRecordPartialContext updates partial info on record with custom context

type Records 

type Records struct {
	Records []*Record `json:"records"`
	Offset  string    `json:"offset,omitempty"`

	// The Airtable API will perform best-effort automatic data conversion
	// from string values if the typecast parameter is passed in.
	// Automatic conversion is disabled by default to ensure data integrity,
	// but it may be helpful for integrating with 3rd party data sources.
	Typecast bool `json:"typecast,omitempty"`
	// fieldsToMergeOn will be used as an external ID to match records for updates.
	// For records where no match is found, a new Airtable record will be created.
	// https://airtable.com/developers/web/api/update-multiple-records#request-performupsert
	PerformUpsert *PerformUpsert `json:"performUpsert,omitempty"`
}

Records base type of airtable records.

type Table 

type Table struct {
	// contains filtered or unexported fields
}

Table represents table object.

func (*Table) AddRecords 

func (t *Table) AddRecords(records *Records) (*Records, error)

AddRecords method to add lines to table (up to 10 in one request) https://airtable.com/{yourDatabaseID}/api/docs#curl/table:{yourTableName}:create

func (*Table) AddRecordsContext added in v0.3.1 

func (t *Table) AddRecordsContext(ctx context.Context, records *Records) (*Records, error)

AddRecordsContext method to add lines to table (up to 10 in one request) with custom context

func (*Table) DeleteRecords 

func (t *Table) DeleteRecords(recordIDs []string) (*Records, error)

DeleteRecords delete records by recordID up to 10 ids in one request.

func (*Table) DeleteRecordsContext added in v0.3.1 

func (t *Table) DeleteRecordsContext(ctx context.Context, recordIDs []string) (*Records, error)

DeleteRecordsContext delete records by recordID with custom context

func (*Table) GetRecord 

func (t *Table) GetRecord(recordID string) (*Record, error)

GetRecord get record from table https://airtable.com/{yourDatabaseID}/api/docs#curl/table:{yourTableName}:retrieve

func (*Table) GetRecordContext added in v0.3.1 

func (t *Table) GetRecordContext(ctx context.Context, recordID string) (*Record, error)

GetRecordContext get record from table with custom context

func (*Table) GetRecords 

func (t *Table) GetRecords() *GetRecordsConfig

GetRecords prepare step to get records.

func (*Table) GetRecordsWithParams 

func (t *Table) GetRecordsWithParams(params url.Values) (*Records, error)

GetRecordsWithParams get records with url values params https://airtable.com/{yourDatabaseID}/api/docs#curl/table:{yourTableName}:list

func (*Table) GetRecordsWithParamsContext added in v0.3.1 

func (t *Table) GetRecordsWithParamsContext(ctx context.Context, params url.Values) (*Records, error)

GetRecordsWithParamsContext get records with url values params with custom context

func (*Table) UpdateRecords 

func (t *Table) UpdateRecords(records *Records) (*Records, error)

UpdateRecords full update records.

func (*Table) UpdateRecordsContext added in v0.3.1 

func (t *Table) UpdateRecordsContext(ctx context.Context, records *Records) (*Records, error)

UpdateRecordsContext full update records with custom context.

func (*Table) UpdateRecordsPartial added in v0.2.0 

func (t *Table) UpdateRecordsPartial(records *Records) (*Records, error)

UpdateRecordsPartial partial update records.

func (*Table) UpdateRecordsPartialContext added in v0.3.1 

func (t *Table) UpdateRecordsPartialContext(ctx context.Context, records *Records) (*Records, error)

UpdateRecordsPartialContext partial update records with custom context.

func (*Table) UploadAttachment added in v0.3.3 

func (t *Table) UploadAttachment(recordID string, attachmentFieldIdOrName string, data Attachment) (*FieldAttachments, error)

func (*Table) UploadAttachmentContext added in v0.3.3 

func (t *Table) UploadAttachmentContext(ctx context.Context, recordID string, attachmentFieldIdOrName string, data Attachment) (*FieldAttachments, error)

type TableSchema added in v0.2.8 

type TableSchema struct {
	ID             string   `json:"id"`
	PrimaryFieldID string   `json:"primaryFieldId"`
	Name           string   `json:"name"`
	Description    string   `json:"description"`
	Fields         []*Field `json:"fields"`
	Views          []*View  `json:"views"`
}

type Tables added in v0.2.8 

type Tables struct {
	Tables []*TableSchema `json:"tables"`
}

type View added in v0.2.8 

type View struct {
	ID   string `json:"id"`
	Type string `json:"type"`
	Name string `json:"name"`
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.