Alle artikels
Print

What can I use this call for?

The filter API gives you the ability to query a specific app. It’s is up to you which filters, ordering, options you use. The sky is the limit.

Request

An example to explain the syntax:

[GET] apps/{{APP ID}}_{{APP TOKEN}}/filters/flat?
 {{APP FIELD 1}}=...
 &{{APP FIELD 2}}=...
 &{{META ATTRIBUTE 1}}=...
 &sort_by={{APP FIELD}}
 &sort_order=ASC
 &limit=30
 &offset=0
 &detail={{APP FIELD ID 1}},{{APP FIELD ID 2}}
 &detail_token={{LINKED APP TOKEN 1}},{{LINKED APP TOKEN 2}}

See demo examples at the bottom of the page for working examples.

Response

Array with item objects like:

{
  items: [
    meta:{ 
     "item_id":3001,
     "app_item_id":5,
     "external_id": "aedff832-9eb8-4417-ae53-5c204a7f9641",
     "created_at":"2015-11-07T14:53:57.000Z",
     "updated_at":"2015-11-07T14:55:05.000Z"
    },
    "values":{ 
      "activity-info-title":"Basketball for dumies",
      "activity-info-seo-url":"basketball-for-dumies",
      "activity-periods":[{ 
        "app_id":1002,
        "item_id":3001,
        "title":"July week 1"
      }]
    },
  ],
  linked_items: {
    "1002": {"meta": {... July week 1 ...},       "values": {}, "incoming": []},
    "1003": {"meta": {... B01 (01 - 07 jul) ...}, "values": {}, "incoming": []}
  },
  errors: {error_code: "error message"},
}

How to filter?

Filters are passed as url parameters

  • key = app field external_id or podio_id. We suggest to use the first as it is more developer friendly. It is also possible to filter on selected meta keywords
  • value = depends on the app_field.data_type

App

Value: (an array of) item podio_id(s)

?period=1001
?period=1001,1002
?period[]=1001&period[]=1002
?period=0 // for null value

Category

Value: (an array of) category id(s) (these number can be found through App info API call)

?gender=1
?gender=1,2
?gender[]=1&gender[]=2
?gender=0 // for null value

Text

Value: string, case insensitive but needs to be exact match. “PIECE of TEXT” == “piece of text”, but “piece-of-text.” != “piece of text”

?seo-url-name=ponykamp-zomer-2005

Date & date calculations

Provide “from” and/or “to” value.
Values are either absolute or relative dates. See examples below. (notice: never use “+” in relative dates, so [to]=30d is correct but [to]=+30d is not).

?start-date[from]=2015-07-01
?start-date[from]=2015-07-01&start-date[to]=2015-07-01
?start-date[from]=-2w&start-date[to]=1y   # -2w = today -14 days, 1y = today +365 dagen
?start-date[from]=-2wr&start-date[to]=1yr # r = rounding, -1w = last week monday
                                          # 1yr = next year 31/12

Number, number calculation, money, progress & duration

Provide “from” and/or “to”.

?age[from]=4
?age[to]=12
?age[from]=4&age[to]=12

Map

Exacte match on adres.

?map-location=Groenestraat 7, 9000 Gent, België

Image, email, phone & embed

It is not possible to filter on these datatypes.

Meta data

  • created_on: filter like date
  • last_edit_on: filter like date
  • item_id: (array of) podio_id(s)
?item_id=341537941
?item_id=341537941,341543429
?item_id[]=341537941&item_id[]=341543429
  • external_id: (array of) external_ids (s)
?exeternal_id=dedff832-9eb8-4417-ae53-5c204a7f9641
?external_id=dedff832-9eb8-4417-ae53-5c204a7f9641,2c638f15-6c1c-4985-ae34-785504702788
?external_id[]=dedff832-9eb8-4417-ae53-5c204a7f9641&external_id[]=2c638f15-6c1c-4985-ae34-785504702788
  • app_item_id: (array of) app item id(s)
?app_item_id=1
?app_item_id=1,2
?app_item_id[]=1&app_item_id[]=2

Sorting

happens through two url parameters

  • sort_by: app fields or metadata attribute. Default = meta created_on
  • sort_order: ASC / DESC. By default DESC

Be careful, the default DESC is not a standard convention. Be sure to provide “ASC” when you want A-Z. As an example:

?sort_by=created_on # returns created_on DESC, so newest to oldest items
?sort_by=seo-url-name&sort_order=ASC

Special return formats

  • Booleans (true / false) don’t exist in our data model, they’ll always be returned as the enumerable value e.g. [“Yes”]
  • Single enumerable values are always presented as an array. So You’ll get [“Female”] for gender, and never “Female”
  • Location addresses receive their data from a google maps component, you’ll have access to value, formatted, street_number, street_name, postal_code, city, state, country, lat, lng. (PS: in API v2 street_number, street_name replaces “street_address”)

Joining tables

Ask items from multiple apps at the same time by following the links between items. In the detail parameter you provide the app_field id you wish to follow and in detail token you provide. Do not worry about the direction of the relation. KampAdmin will pick it up from either side.

When following multiple app fields use comma to separate them

?detail={{APP FIELD ID}}
?detail=2001,2002

detail_token: when you are requesting items from other apps through the “detail” parameter you also need to provide the other app token to show you are granted access to these items.

?detail_token={{APP ID}}_{{APP TOKEN}}
?detail_token=1001_dj39dj2s,1002_fj39ds

The order in which you provide the tokens is irrelevant, as long as all linked apps are covered you are good to go.

Examples

As an integrator you will typically do these two filter queries

Filter activities based on search parameters

On the website we have a form where they provide the filters which should return the matching activities. For the activities app, let’s send the following information

  • Filters: activity-public=yes (id 2) + category = sport (id 405630497
  • Sorting: internal-start-date ASC
  • detail: join on the theme app (via relation id 119751745).
  • detail_info: app token for outgoing app (15518273_9500df21b = themes app)

This gives us an url like:

https://momentum-podio-api.herokuapp.com/api_v2/apps/15518274_ce69a87fc/filters/flat?
  activity-public=2
  &activity-category=405630497
  &sort_by=internal-start-date
  &sort_order=ASC

See the response

In dit artikel: