FactualAPI


Top level object than provides an entry point into the Factual API.

Superclass: NSObject
Declared In: FactulAPI.h

Discussion

You need to specify the Factual API during initialization. The init call is non-blocking and does not perform any network IO. This class performs all network IO in an asynchronous manner and all API requests take a FactualAPIDelegate reference and return a FactulAPIRequest object. You can hold on to (retain) the Request object for future request identification purposes. All results (success and failuers) come through the delegate methods, each of which tag the corresponding Request context object as their first parameter. You can also use the Request object to safely cancel outstanding API requests. Once a request has failed or completed and has notified of this state transition, you can release your reference to the Request object and it will automatically be garbage collected (autorelease).

Each Request type in the Factual API has a corresponding return (Response) type. All information related to the query and resulting data is self contained in the response object and can be freely discarded or retained at the user's discretion.



Methods

-initWithAPIKey:
-submitRowData:facts:withDelegate:optionalRowId:optionalSource:optionalComment:optionalUserToken:
-queryTable:optionalQueryParams:withDelegate:
-getTableSchema:withDelegate:
-flagBadRow:rowId:optionalSource:optionalComment:withDelegate:

initWithAPIKey:


- (id) initWithAPIKey:(NSString*) apiKey; 
Discussion

Used to initialize the API. Pass in the API Key


submitRowData:facts:withDelegate:optionalRowId:optionalSource:optionalComment:optionalUserToken:


- (FactualAPIRequest*) submitRowData:(NSString*) tableId facts:(NSDictionary*) facts withDelegate:(id<FactualAPIDelegate>) delegate optionalRowId:(NSString*) rowId optionalSource:(NSString*) source optionalComment:(NSString*) comment optionalUserToken:(NSString*) tokenId; 
Parameters
tableId

This is the Factual Table Id for which you are submitting new or existing data. Mandatory Field.

facts

This contains a dictionary of key/value pairs representing the fields that you are inserting / updating. Supported data types are: NSString,NSNumber,NSNull and in some cases NSArray. Mandatory Field.

delegate

This is a reference to the delegate on which callbacks will be invoked. A reference to delegate is (retained) and will not be (released) until either the user explicitly cancels the request or either requestComplete:failedWithError: OR receivedSchemaResult:receivedUpdateResult: is called on the delegate.

rowId

(optional) This is an optional field that can be used to specify the existing rowID that the new edits to a recird apply to.

source

(optional) Use this optional field to specify attribution (such as a url) for the data you are submitting to Factual

comment

(optional) Use this optional field to attach a comment to the data you will be submitting to Fatual

tokenId

(optional) Use this optional field to specify an app specific end user token to associate with the data you are submitting to Factual. (see the Factual API documentation for more details)

Return Value

the FactualAPIRequest object associated with this API request.

Discussion

The primary way you update a Factual table. Factual is a consensus value based system, so updates or inserts have very loose requirements. You can submit a change in value for a particular field and row, or you can update or suggest an insert of a whole row. All updates are processed by the system and MAY produce a new record in some cases and not others. If updating an existing row, when possible, specify the row id for the row that is being operated on. If successful, this API will asynchronously notify you of the result of operation via calling the requestComplete:receivedUpdateResult: method on the delegate. See the documentation for the FactualUpdateResult class for more details.


queryTable:optionalQueryParams:withDelegate:


- (FactualAPIRequest*) queryTable:(NSString*) tableId optionalQueryParams:(FactualQuery*) queryParams withDelegate:(id<FactualAPIDelegate>) delegate; 
Parameters
tableId

The name of the Factual table to query.

queryParams

(optional) And optional FactualQuery object to use to restrict the server query and the returned recordset.

delegate

(optional) This is a reference to the delegate on which callbacks will be invoked. A reference to delegate is (retained) and will not be (released) until either the user explicitly cancels the request or either requestComplete:failedWithError: OR receivedSchemaResult:receivedQueryResult: is called on the delegate.

Return Value

the FactualAPIRequest object associated with this API request.

Discussion

Use this method to query a Factual table. You must specify the Factual table id. You can specify additional query parameters via the FactualQuery object, such as predicates (via FactualFilter), sort orders and row offsets and record limits. Upon successful execution you will recieve query results asynchronously via a call the requestComplete:receivedQueryResult: method on the delegate. Failures will result in a call to the requestComplete:failedWithError: method on the delegate. Please read the docs on FactualQueryResult for details about the data returned as a result of Query.


getTableSchema:withDelegate:


- (FactualAPIRequest*) getTableSchema:(NSString*) tableId withDelegate:(id<FactualAPIDelegate>) delegate; 
Parameters
tableId

The name of the Factual table to retreive schema info for.

delegate

This is a reference to the delegate on which callbacks will be invoked. A reference to delegate is (retained) and will not be (released) until either the user explicitly cancels the request or either requestComplete:failedWithError: OR receivedSchemaResult:schemaResult: is called on the delegate.

Return Value

the FactualAPIRequest object associated with this API request.

Discussion

Use this method to retrieve schema information about a Factual table. Schema information table level metadata as well as field level details such as column names, data types, and for enumerated values, a valid list of enumerations. Schema information is returned a call to the requestComplete:receivedSchemaResult: method on the passed in delegate. Please refer to the docs on FactualSchemaResult for more details about the information returned via a Table Schema query.


flagBadRow:rowId:optionalSource:optionalComment:withDelegate:


- (FactualAPIRequest*) flagBadRow:(NSString*) tableId rowId:(NSString*) rowId optionalSource:(NSString*) source optionalComment:(NSString*) comment withDelegate:(id<FactualAPIDelegate>) delegate; 
Parameters
tableId

The name of the Factual table in which the problem row is located

rowId

The id of the bad Row in the Factual Table

source

(optional) Use this optional field to specify attribution (such as a url) for the data you are submitting to Factual

comment

(optional) Use this optional field to attach a reason why you have flagged this row as bad

delegate

This is a reference to the delegate on which callbacks will be invoked. A reference to delegate is (retained) and will not be (released) until either the user explicitly cancels the request or either requestComplete:failedWithError: OR requestComplete: is called on the delegate.

Return Value

the FactualAPIRequest object associated with this API request.

Discussion

Use this method to mark a existing row as having bad or invalid data

Properties

apiKey
apiVersion

apiKey


@property (
    nonatomic,
    readonly) NSString* apiKey; 
Discussion

Returns the read-only api-key used to authenticate a connection to Factual


apiVersion


@property (
    nonatomic,
    readonly) NSInteger apiVersion; 
Discussion

Returns the version number of the Factual API for debugging purposes.

Last Updated: Friday, January 28, 2011