Developers

We would like to express our deep gratitude to the following projects PHP, Yii Framework, MySQL, Nginx, Memcached, Sphinx Search thanks to them Factopedia was created.

If you like to make Factopedia better, then join us. Right now you can help us to translate Factopedia into your native language, or fill the encyclopedia with the necessary content. To create new objects, you can use our RESTful API, which is available by the url https://api.factopedia.org. If you want to participate in Factopedia development, please contact us.

Contents

  1. Authorization
  2. Data format
  3. Endpoints
    1. General principles
    2. /objects
      1. GET /objects listing of objects
      2. POST /objects creating new object
      3. PUT /objects/123 updating object
    3. /properties
    4. /properties-categories
    5. /units
    6. /comparisons
      1. GET /comparisons listing of comparisons
      2. POST /comparisons creating new comparison
  4. API realization on different languages
    1. PHP
      Perl
      Python

Authorization

Only registered users can use API so register or login. User authorization occurs using HTTP Basic Access Authentication as a username use your API token which you will find in your profile.Password field leave blank.
To automatically make API calls, add a header Authorization to the request headers with data Basic {credentials} where {credentials} - base64 encoded {token}:, a colon at the end is required.

Data format

If the request contains a header
Accept: application/json; q=1.0, */*; q=0.1
Data will be returned in JSON format, otherwise in XML

Endpoints

  1. /objects
  2. Getting objects data, creating and updating objects
  3. /properties
  4. Getting properties data, creating properties
  5. /units
  6. Getting units data, creating units
  7. /comparisons
  8. Objects comparisons, creating and updating comparisons

General principles

All the listing calls GET can be extended with additional parameters

    expand: getting additional data;
    filter: filter results, searching *;
    sort: sorting listing *;

* available only on endpoints which returns collections

each endpoint has its own values of expand parameter, see possible values in the endpoint description.

filter has the following format


filter[name]{[operator]}=value

{} operator is optional

sort has the following format


sort=name

name - field name. Default sort is ASC, from smaller to larger, if you want to sort in reverse order use "-" before field name, for example sort=-name

/objects

Endpoints

GET /objects: listing of objects, by pages;
POST /objects: creating new object;
GET /objects/123: object 123 data;
PATCH /objects/123 or PUT /objects/123: updating object 123;

GET /objects listing of objects, by pages

Please read general principles of listing commands. This command do not support filter parameter, instead you can filter objects with additional parameteres:

name
parentId
lang
property

This allows you to search objects by name, in certain categories and by property value. `property` can be used only with `parentId`for searching objects in categories. It is an array where keys are property id, and the value is an miltidimentional array with filter options (see example below to make a correct filtering by properties values). By defaul objects sorted by name, but it's also possible to sort by object property, for example `sort=-67_object` this means that objects will be sorted in DESC order '-' minus sign in the beggining, by the property with id = '67' and type = 'object' Possible values for additional parameters

expand


properties
suggestedProperties
parents
children
countChildren
images

Usage example

GET /objects?expand=properties,suggestedProperties,parents,children&sort=-67_object&name=example&parentId=123&lang=en&property[65][int][][>=]=1980&property[65][int][][<=]=1981&property[62][int][][%3D]=7&property[62][int][][%3D]=8

POST /objects creating new object

First check out the related help section that describes objects creation. Data can be sent in www-url-form-encode format if you are not sending images, and in multipart/form-data format if you are sending or not sending images

name: object name (*);
lang: language, two-letter format (*);
descriptions: object description;
main_image: md5 checksum of image file;
aliases[]: other object names;
parents[][Objects][id]:  parent object (category);
children[][Objects][id]:  children objects, objects descended from this object;
Objects[imageFiles][]: image files;

objectsPropertiesValues[n][ObjectsPropertiesValues][name]: each property data, n - property ID, possible values of name field see in /properties endpoint description
    required fields:
    objectsPropertiesValues[n][ObjectsPropertiesValues][property_id]: property ID, property need to be added to the data base before linking the property with any object. To check is property already exists or create a new property you can with /properties endpoint
    possible field values type:
    int, dec, range_int, range_dec, bool, text, object, array, array_of_objects, dynamic
Links[n][url]: link for the property, n - property ID;


For example:
POST /objects

?name=foo
&lang=en
&description=bar
&aliases[]=foobar
&aliases[]=barfoo
&parents[][Objects][id]=123
&children[][Objects][id]=234
&objectsPropertiesValues[12][ObjectsPropertiesValues][property_id]=12
&objectsPropertiesValues[12][ObjectsPropertiesValues][category_id]=11
&objectsPropertiesValues[12][ObjectsPropertiesValues][unit_id]=21
&objectsPropertiesValues[12][ObjectsPropertiesValues][type]=int
&objectsPropertiesValues[12][ObjectsPropertiesValues][value]=4321
&objectsPropertiesValues[12][ObjectsPropertiesValues][order_by]=1
&objectsPropertiesValues[13][ObjectsPropertiesValues][property_id]=13
&objectsPropertiesValues[12][ObjectsPropertiesValues][category_id]=11
&objectsPropertiesValues[13][ObjectsPropertiesValues][unit_id]=31
&objectsPropertiesValues[13][ObjectsPropertiesValues][type]=bool
&objectsPropertiesValues[13][ObjectsPropertiesValues][value]=1
&objectsPropertiesValues[13][ObjectsPropertiesValues][order_by]=2
&objectsPropertiesValues[14][ObjectsPropertiesValues][property_id]=14
&objectsPropertiesValues[14][ObjectsPropertiesValues][type]=array_of_objects
&objectsPropertiesValues[14][ObjectsPropertiesValues][value][0]=31
&objectsPropertiesValues[14][ObjectsPropertiesValues][value][1]=219
&objectsPropertiesValues[14][ObjectsPropertiesValues][value][2]=42229
&objectsPropertiesValues[15][ObjectsPropertiesValues][property_id]=15
&objectsPropertiesValues[15][ObjectsPropertiesValues][type]=array_of_objects
&objectsPropertiesValues[15][ObjectsPropertiesValues][value][0]=31
&objectsPropertiesValues[15][ObjectsPropertiesValues][value][1]=219
&objectsPropertiesValues[15][ObjectsPropertiesValues][value][2]=42229
&objectsPropertiesValues[15][ObjectsPropertiesValues][valueArrayOfObjects][3][Objects][name]=NewObjectName // Will try to create a new object in the same category as other objects that already exists
&objectsPropertiesValues[15][ObjectsPropertiesValues][value][3]=
&objectsPropertiesValues[16][ObjectsPropertiesValues][property_id]=16
&objectsPropertiesValues[16][ObjectsPropertiesValues][type]=array
&objectsPropertiesValues[16][ObjectsPropertiesValues][value][0]=value1
&objectsPropertiesValues[16][ObjectsPropertiesValues][value][1]=value2
&objectsPropertiesValues[16][ObjectsPropertiesValues][value][2]=value3
&Links[12][url]=http://www.example.com
&Links[13][url]=http://www.example1.com

* Mandatory data

GET /objects/123 getting object data

Check out GET /objects command description, this command accept the same parameters. Additional parameters:

format: format of returned data. It is used to immediately generate data for an object editing command PUT /objects/123. Possible values: api

Usage example

GET /objects/123
GET /objects/123?format=api

PUT /objects/123 updating object

See POST /objects command description, this command accept the same parameters. Attention when editing at least one field, you must send all other unchanged fields as well. To get POST data for any object, add parameter format=api to the request GET /object/123

/properties

Getting and adding properties to the database. Check out general principles chapter, for general information about commands returning collections.

Endpoints


GET /properties: listing of properties, by pages;
POST /properties: creating new property;
GET /properties/123: information about property 123;

Usage example:

GET /properties?filter[name]=foo&lang=en
GET /properties?filter[name][like]=bar&lang=en&sort=name
POST /properties&name=foo&lang=en

/properties-categories

Getting and adding categories of properties to the database. Check out general principles chapter, for general information about commands returning collections.

Endpoints


GET /properties-categories: listing of properties categories, by pages;
POST /properties-categories: creating new category;
GET /properties-categories/123: information about category 123;

Usage example:

GET /properties-categories?filter[name]=foo&lang=en
GET /properties-categories?filter[name][like]=bar&lang=en&sort=name
POST /properties-categories&name=foo&lang=en

/units

Getting and adding units to the database. Check out general principles chapter, for general information about commands returning collections.

Endpoints


GET /units: listing of units, by pages;
POST /units: creating new unit;
GET /units/123: information about unit 123;

Usage example:

GET /units?filter[name]=foo&lang=en
GET /units?filter[name][like]=bar&lang=en&sort=-name
POST /units&name=foo&lang=en

/comparisons

Endpoints

GET /comparisons: listing of comparisons, by pages;
POST /comparisons: creating new comparison;
GET /comparisons/123: information about comparison 123;
PATCH /comparisons/123 or PUT /comparisons/123: updating comparison 123;

GET /comparisons listing of comparisons, by pages

Check out general principles chapter, for general information about commands returning collections. Possible values for additional parameters

expand


sortings
sortings.property
objects

Usage example

GET /comparisons?expand=sortings.property,objects&filter[name][like]=Foobar&filter[lang]=en&sort=-id

POST /comparisons adding new comparison

First check out the relevant help section which describes objects comparison. Data can be sent in www-url-form-encode format.

name: comparison name;
lang: language, two-letter format (*);
descriptions: description;

comparisonsSortings[n][ComparisonsSortings][name]: data for each property, n - property ID, possible field values name:
    comparisonsSortings[n][ComparisonsSortings][property_id] *: property ID
    comparisonsSortings[n][ComparisonsSortings][order] *: sorting order (1-10)
    comparisonsSortings[n][ComparisonsSortings][direction]: sorting direction (asc, desc)


For example:
POST /comparisons

?objects[][Objects][id]=123
&objects[][Objects][id]=456
&name=Foo bar
&lang=en
&comparisonsSortings[34][ComparisonsSortings][property_id]=34
&comparisonsSortings[34][ComparisonsSortings][order]=1
&comparisonsSortings[34][ComparisonsSortings][direction]=asc
&comparisonsSortings[35][ComparisonsSortings][property_id]=35
&comparisonsSortings[35][ComparisonsSortings][order]=1
&comparisonsSortings[35][ComparisonsSortings][direction]=desc

* Mandatory data

Help · Contact us · Disclaimer · Contributors · Developers · Donate