Skip to content

drupal-make
drupal-make

It's Riseup's twentieth year, help keep us going! If you can afford it, please contribute to our winter fundraising drive.

notes

Last edited by ekes
Page history

These notes largely based on the research and documentation for the Go Radar bindings.

General

The radar database consists of the following entities:

  • events : any kind of event, e.g. a party, workshop, etc.
  • groups : a group organizes events. Some groups just act as promoters and add events to the database without actually organzing them, e.g. "Stressfaktor". An event can be linked to multiple groups.
  • location : a place where an event happens.
  • taxonomy term : a category for events, groups and locations, e.g. "party", "workshop", "bar/cafe", etc. Any of the above entities can be linked to multiple taxonomy terms.

Each entity comes with a set of fields. All entities have a common field UUID which uniquely identifies an entity instance.

This documentation follows json only, it is possible to change to other formats including xml by altering the url extension, or the Accept header in the GET request.

Entity Endpoints

The rest API provides endpoints for each of those entities:

event: https://radar.squat.net/api/1.2/node/[uuid].json
file:  https://radar.squat.net/api/1.2/file/[uuid].json
group: https://radar.squat.net/api/1.2/node/[uuid].json
location: https://radar.squat.net/api/1.2/location/[uuid].json
term: https://radar.squat.net/api/1.2/taxonomy_term/[uuid].json

Entity parameters

The entity endpoints support two parameters:

  • fields: the fields to be returned.
  • language: use the specified language, if available.

By default, all available fields for an entity are returned. Alternatively, a comma-separated list of fields can be passed:

https://radar.squat.net/api/1.2/node/[uuid].json?fields=field1,field2,field3

The default language is english (or UND - undefined). To change the language pass an ISO language code like this:

https://radar.squat.net/api/1.2/node/[uuid].json?language=de

The corresponding go bindings for these endpoints provided by this package are named Event(), Group(), Location() and Term() and can be found below.

Search Endpoints

Anything you can search for on the website, for example on the https://radar.squat.net/en/events can be searched with the API, and more. The API supports searching the database for entities through the following endpoints:

event: https://radar.squat.net/api/1.2/search/events.json
group: https://radar.squat.net/api/1.2/search/groups.json
location: https://radar.squat.net/api/1.2/search/location.json
term: https://radar.squat.net/api/1.2/search/term.json

Without any parameters, events will return all events with an end time greater than (now - 2h). End time will be the same as start time if none is given. group, location and term will simply return all, up to the limit (default 500 presently).

In most cases you'd only want a subset of the data, therefore the API provides different means of filtering the results. See Facet and Filter below for info and examples on how to filter the results.

Apart from facets and filters, the search API supports the following other parameters:

  • keys: string used for full-text search.
  • fields: see Entity Parameters above, with the extension that reference fields can be auto resolved (see ResolveField below).
  • language: see Entity Parameters above.
  • limit: return at most n results, see Limit() below.
  • sort: sorts the results by the specified field in the given order (asc or desc), see Sort() below.

Result format

https://radar.squat.net/api/1.2/search/events.json?fields=title&limit=2

Will return a result a count and a facets list.

{
  "result": {
    "351420": {"title": "Migrant Sc\u00e8ne, Festival de la Cimade du 15 novembre au 08 d\u00e9cembre"},
    "351506": {"title": "Begehbarer tik-Adventskalender"}
  },
  "count": 7049,
  "facets": {
    "field_offline:field_address:postal_code": [{"filter": "13001", "count": 583, "formatted": "13001",.... 
    }],
    "city": [{"filter": "Marseille", "count": 906, "formatted": "Marseille"....
    }],
    "country": [{"filter": "FR", "count": 2238, "formatted": "FR"....
    }],
    "date": [{"filter": "1576778400", "count": 27, "formatted": "1576778400"...9437600"....
    }],
    "callout": [{"filter": "national-callout", "count": 2, "formatted": "1391"....
    }],
    "price": [{"filter": "free-121", "count": 957, "formatted": "free"....
    }],
    "tag": [{"filter": "sans-papiers", "count": 946, "formatted": "sans papiers"....
    }],
    "group": [{"filter": "1599", "count": 747, "formatted": "Stressfaktor"...
    }],
    "category": [{"filter": "book-shop-info-shop-library", "count": 2234, "formatted": "book 
shop/info shop/library"...
    }]
  }
}

Detail of the result format, and fields below. The count is the number of results that match. The filters map to the facets (below). Each will give the human readable formatted name, the value that can be used in the facet and the number of results that match it.

Field references

When searching for an entity, the result may contain a field which is a reference to another entity. Normally, one would have to do another API call to fetch this referenced entity. The radar api, however, allows us to specify fields which should be resolved automatically.

In the radar rest api this is done like this

fields=referenceField:targetField

or even

fields=referenceField:anotherReference:targetField

Example

Search result for events showing the title and the field 'offline', which is a reference to the location entity.

Using the radar rest api

https://radar.squat.net/api/1.2/search/events.json?fields=title,offline

Result

"346823": {
    "offline": [
      {
        "uri": "https://radar.squat.net/api/1.2/location/8b8b63b2-64e5-4831-a91d-7f77bb510890",
        "id": "8b8b63b2-64e5-4831-a91d-7f77bb510890",
        "resource": "location",
        "title": "K19 Café Kreutzigerstr. 19  Berlin Deutschland"
      }
    ],
    "title": "CryptoParty"
  }

Clicking the uri will reveal the following structure of the location entity:

{
 "address": {
   "country": "DE",
   "name_line": "K19 Café",
   "first_name": "K19",
   "last_name": "Café",
   "organisation_name": null,
   "administrative_area": null,
   "sub_administrative_area": null,
   "locality": "Berlin",
   "dependent_locality": null,
   "postal_code": "10247",
   "thoroughfare": "Kreutzigerstr. 19",
   "premise": ""
 },
 "directions": "U-Bhf. Samariterstrasse",
 "map": {
   "geom": "POINT (13.4600646 52.5131015)",
   "geo_type": "point",
   "lat": "52.513101500000",
   "lon": "13.460064600000",
   "left": "13.460064600000",
   "top": "52.513101500000",
   "right": "13.460064600000",
   "bottom": "52.513101500000",
   "srid": null,
   "latlon": "52.513101500000,13.460064600000",
   "schemaorg_shape": ""
 },
 "timezone": "Europe/Berlin",
 "squat": null,
 "id": "225",
 "type": "location",
 "title": "K19 Café Kreutzigerstr. 19  Berlin Deutschland",
 "uuid": "8b8b63b2-64e5-4831-a91d-7f77bb510890",
 "feed_nid": null
}

We can now resolve the address Field (or any of the others) like this

https://radar.squat.net/api/1.2/search/events.json?fields=title,offline,offline:address

Result

"346823": {
    "offline": [
      {
        "uri": "https://radar.squat.net/api/1.2/location/8b8b63b2-64e5-4831-a91d-7f77bb510890",
        "id": "8b8b63b2-64e5-4831-a91d-7f77bb510890",
        "resource": "location",
        "title": "K19 Café Kreutzigerstr. 19  Berlin Deutschland",
        "address": {
          "country": "DE",
          "name_line": "K19 Café",
          "first_name": "K19",
          "last_name": "Café",
          "organisation_name": null,
          "administrative_area": null,
          "sub_administrative_area": null,
          "locality": "Berlin",
          "dependent_locality": null,
          "postal_code": "10247",
          "thoroughfare": "Kreutzigerstr. 19",
          "premise": ""
        }
      }
    ],
    "title": "CryptoParty"
  }

Facets

Facets provide an easy way to filter results by entity properties.

For each entity there's a predefined set of facets.

Events:
	// operator: and
	"field_offline:field_address:postal_code"
	// Always starts with an uppercase letter, e.g. Berlin
	// operator: and
	"city"
	// Uppercase country code, e.g. DE for Germany
	// operator: and
	"country"
	// The date must be in the format YY YY-MM or YYYY-MM-DD
	// operator: or
	"date"
	// price category, e.g. "free-121"
	"price"
	// Topic tag, e.g. "sport", "vegan"
	// operator: and
	"tag"
	// operator: or
	"group"
	// Spaces and slashes should be replaced by a dash, e.g. "work space/diy" =>
	// "work-space-diy"
	// operator: and
	"category"

Groups:
	//operator: none
	"offline:map"
	// For some reason values need to start with a lowercase here, e.g. berlin
	// operator: and
	"city"
	// Uppercase country code, e.g. DE for Germany
	// operator: and
	"country"
	// operator: and
	"squated"
	// Group is listed by this group.
	// operator: and
	"radar_group_listed_by"
	// If the group is active
	// operator: or
	"field_active"
	// topic / tag
	// operator: and
	"topic"
	// Spaces and slashes should be replaced by a dash, e.g. "work space/diy" =>
	// "work-space-diy"
	// operator: and
	"category"
	// operator: and
	"title"

Facets can be passed to the server by using the facets parameter:

https://radar.squat.net/api/1.2/search/events.json?facets[facet][]=value

Example

https://radar.squat.net/api/1.2/search/events.json?facets[city][]=Berlin

Multiple facets can be passed, even the same with different values. When passing the same facet with different values the logical operation (AND, OR) depends on the actual facet. This is in the list of facets, it's also usually visible from doing a search and using the facets on the front end.

Example

category operator is AND, this call returns events which have both the bar/cafe AND theater category
https://radar.squat.net/api/1.2/search/events.json?facets[category][]=bar-cafe&facets[category][]=theater
group operator is OR, this call returns events organized by group 339006 OR 1599
https://radar.squat.net/api/1.2/search/events.json?facets[group][]=339006&fields=*&facets[group][]=1599

Filters

Filters provide a somewhat more complex way to filter results. Note: filtering only works on indexed fields.

Filters can be passed to the server by using the filter parameter:

https://radar.squat.net/api/1.2/search/events.json?filter[~operator][field][~comparator]=value

Possible operators are

  • ~and: all filters with ~and must evaluate to true
  • ~or: at least one of the ~or filters must evaluate to true

Comparators:

  • ~e: equals
  • ~ne: not equal
  • ~gt: greater than
  • ~gte: greater or equal than
  • ~lt: less than
  • ~lte: less or equal than

Note: filtering also works on resolved fields.

Example

Get all events in Berlin

https://radar.squat.net/api/1.2/search/events.json?filter[~and][field_offline:field_address:locality][~eq]=Berlin

Note: most of the equal filters, like in this example, can be be done with Facets in a simpler manner (see Facets).

One of the more interesting things you can do is filtering for a time period

Get all events in Berlin with a start date between 2020-11-03 00:00:00 and 2020-11-25 00:00:00

https://radar.squat.net/api/1.2/search/events.json?facets[city][]=Berlin&filter[~and][search_api_aggregation_1][~gt]=1604358000&filter[~or][search_api_aggregation_1][~lt]=1606258800

Limitations

Filters can't be grouped, i.e. things like (cond1 AND cond2) OR cond3 are not possible.

A field can't be used in more than one equals filter, i.e. you can't filter for events in Berlin OR Amsterdam because that would require using the field locality twice.

filter[~and][field_offline:field_address:locality][~eq]=Berlin&filter[~or][field_offline:field_address:locality

This is where there will usually be facets to cover the requirement.

Available fields

Authentication

For retrieving entities, and searching, you don't need to authenticate. To post you will. To post via the API it's best to ask radar@squat.net for permission for the account to be used, as this can be restricted at any time.

To authenticate at the moment you need to get a cookie and token using the username and password associated with the account.

POST https://radar.squat.net/api/1.2/user/login 
Content-Type: application/json
Accept: application/json
Content: { 'username' => USERNAME, 'password' => PASSWORD }

For which you will get a response including the required cookie and in the body of the response the token for to be used in all future requests as the X-CSRF-Token header.

Posting entities

The end points are the same as for retrieving entities. If you POST to /api/1.2/node you will get a UUID assigned to a new entity. If you PUT to /api/1.2/node/[uuid] you can set the UUID of the entity.

POST https://radar.squat.net/api/1.2/
Content-Type: application/json
Accept: application/json
Cookie: see above
X-CSRF-Token: see above
Content: {

}