Search Submitted Events

Search events submitted by your organization.

For example, you can use this to display a list of events submitted via Loop Links within your application to your users. See also the Events API documentation for more detail on many of the parameters mentioned below.

Request

HTTP Request

GET https://api.predicthq.com/v1/loop/events

Query Parameters

Parameter Description

Parameter	Description
`q` string	Full-text search of event information. E.g. `?q=hotel+a`
`link_id` string	Comma-separated list of link ids. Allows you to filter on events submitted via a specific Loop Link link id. E.g. `?link_id=m4Dk4g4DRA8Yqbp2PC54`
`event_id` string	Comma-separated list of event ids. Allows you to retrieve specific events. E.g. `?event_id=5uRg7CqGu7DTtu4Rfk`
`user_id` string	Comma-separated list of user ids that submitted events. E.g. `?user_id=hw8Dsmv4Djg`
`state` string	Comma separated list of event states. Possible values: `active` `predicted` `cancelled` `postponed` `archived`
`category` string	Comma separated list of event categories. E.g. `?category=expos,festivals`
`label` string	Comma separated list of event labels. E.g. `?label=community,food,music`
`country` string	Comma separated list of country codes. E.g. `?country=NZ,US`
`start.*` string	The date from and/or to the event starts. Must be used with suffixes `lt`, `lte`, `gt` or `gte`. E.g. `?start.gt=2023-03-04&start.lte=2023-05-01`
`end.*` string	The date from and/or to the event ends. Must be used with suffixes `lt`, `lte`, `gt` or `gte` E.g. `?end.gt=2023-03-04&end.lte=2023-05-01`
`active.*` string	The date from and/or to the event is active. Must be used with suffixes `lt`, `lte`, `gt` or `gte`. E.g. `?active.gt=2023-03-04&active.lte=2023-05-01`
`created.*` string	The date from and/or to the event has been created. Must be used with suffixes `lt`, `lte`, `gt` or `gte`. E.g. `?created.gt=2023-03-04&created.lte=2023-05-01`
`updated.*` string	The date from and/or to the event has been updated. Must be used with suffixes `lt`, `lte`, `gt` or `gte`. E.g. `?updated.gt=2023-03-04&updated.lte=2023-05-01`
`private.include` string	Whether or not to include private events. Rejected & pending submitted events will always be private. Possible values: `true`, `false`, `only`.E.g `?private.include=only` `true`: private and public events `false` (default): only public events `only`: only private events
`org_review` string	Filter for submitted events approved, rejected or yet to be treated by the related org. Possible values: `pending`, `approved`, `rejected`. E.g `?org_review=approved`
`phq_review` string	Filter for submitted events approved, rejected or yet to be treated by PHQ. Possible values: `pending`, `approved`, `rejected`. E.g `?phq_review=approved`
`sort` string	Comma-separated list of sort options. Prefix the field name with `-` for reverse order. Possible values: `created` `updated` `version` `relevance` E.g. `?sort=-updated` Defaults to `?sort=relevance,-updated`
`limit` number	The maximum number of results to return. The default limit is `10`. E.g. `?limit=10`
`offset` number	The number of results to skip. The default is `0`. E.g. `?offset=20`

q string

Full-text search of event information. E.g. ?q=hotel+a

link_id string

Comma-separated list of link ids. Allows you to filter on events submitted via a specific Loop Link link id. E.g. ?link_id=m4Dk4g4DRA8Yqbp2PC54

event_id string

Comma-separated list of event ids. Allows you to retrieve specific events. E.g. ?event_id=5uRg7CqGu7DTtu4Rfk

user_id string

Comma-separated list of user ids that submitted events. E.g. ?user_id=hw8Dsmv4Djg

state string

Comma separated list of event states. Possible values:

active
predicted
cancelled
postponed
archived

category string

Comma separated list of event categories. E.g. ?category=expos,festivals

label string

Comma separated list of event labels. E.g. ?label=community,food,music

country string

Comma separated list of country codes. E.g. ?country=NZ,US

start.* string

The date from and/or to the event starts. Must be used with suffixes lt, lte, gt or gte. E.g. ?start.gt=2023-03-04&start.lte=2023-05-01

end.* string

The date from and/or to the event ends. Must be used with suffixes lt, lte, gt or gte E.g. ?end.gt=2023-03-04&end.lte=2023-05-01

active.* string

The date from and/or to the event is active. Must be used with suffixes lt, lte, gt or gte. E.g. ?active.gt=2023-03-04&active.lte=2023-05-01

created.* string

The date from and/or to the event has been created. Must be used with suffixes lt, lte, gt or gte. E.g. ?created.gt=2023-03-04&created.lte=2023-05-01

updated.* string

The date from and/or to the event has been updated. Must be used with suffixes lt, lte, gt or gte. E.g. ?updated.gt=2023-03-04&updated.lte=2023-05-01

private.include string

Whether or not to include private events. Rejected & pending submitted events will always be private. Possible values: true, false, only.E.g ?private.include=only

true: private and public events
false (default): only public events
only: only private events

org_review string

Filter for submitted events approved, rejected or yet to be treated by the related org. Possible values: pending, approved, rejected. E.g ?org_review=approved

phq_review string

Filter for submitted events approved, rejected or yet to be treated by PHQ. Possible values: pending, approved, rejected. E.g ?phq_review=approved

sort string

Comma-separated list of sort options. Prefix the field name with - for reverse order. Possible values:

created
updated
version
relevance

E.g. ?sort=-updated Defaults to ?sort=relevance,-updated

limit number

The maximum number of results to return. The default limit is 10. E.g. ?limit=10

offset number

The number of results to skip. The default is 0. E.g. ?offset=20

Response

Response Fields

Field Description

Field	Description
`count` number	Total number of results found.
`events` array	List of results where each item is a Submitted Event. Please refer to the Submitted Event Response Fields section below for the structure of each record.

count number

Total number of results found.

events array

List of results where each item is a Submitted Event.

Please refer to the Submitted Event Response Fields section below for the structure of each record.

Submitted Event Response Fields

Field Description

Field	Description
`event_id` string	The unique identifier of the event. E.g. `z13B3870YOgv`
`link_id` string	Loop Link ID that was used to submit this event. Will only be available on submissions that were made with a Loop Link.
`create_dt` string	The creation date time for the record in ISO 8601 format format. E.g. `2022-04-26T11:46:24+00:00`
`update_dt` string	The last update date time for the record in ISO 8601 format format. E.g. `2022-04-26T11:46:24+00:00`
`version` number	Version number of the record. This number increments automatically every time the record is updated.
`phq_review` string	Current review status. All submissions go through a moderation process. This field refers to the PredictHQ moderators. Possible values: `pending` `approved` `rejected`
`org_review` string	Current review status for customer-initiated reviews. Some organizations are able to review submissions before they're moderated by PredictHQ staff. Possible values: `pending` `approved` r`ejected`
`phq_auto_approved` boolean	Indicates whether or not the record was automatically approved. Some organizations are able to have their submissions enter our automatic review process after a period of time with consistent high quality level of submissions.
`event.title` string	The title of the event. E.g. `Katy Perry`
`event.description` string	A description of the event. E.g. `See Katy Perry in concert [...]`
`event.category` string	The category of the event. Please see Search Events for a list of possible categories. E.g. `concerts`
`event.state` string	The publication state of the event. Please see Search Events for a list of possible states.
`event.metadata` array	List of metadata associated with the event. E.g. `{ "metadata": [ { "maximum_attendance": 5000 }, { "attendance": 3215 } ] }`
`event.dates` object	Event dates. E.g. `{ "dates": { "fixed_date": { "start_date": "2023-06-02", "end_date": "2023-06-04" } } }`
`event.labels` array	List of labels for the event. E.g. `{ "labels": [ "festival", "food", "music" ] }`
`event.lat` string	Latitude for the event. E.g. `38.901544`
`event.lon` string	Longitude for the event. E.g. `-119.7030036`
`event.address` string	Address for the event. E.g. `859 U.S. Highway 395 North`
`event.formatted_address`string	Full formatted address for the event. E.g. `859 U.S. Highway 395 North Gardnerville, Nevada 89410 United States of America`
`event.city` string	City of the event.
`event.region` string	Region of the event.
`event.postcode` string	Postcode of the event.
`event.country` string	Country code in ISO 3166-1 alpha-2 format.
`event.geometry` object	Geographic location of the event. Represented in GeoJSON format. E.g. `{ "geometry": { "type": "Point", "coordinates": [ -119.703022, 38.9012446 ] } }`

event_id string

The unique identifier of the event. E.g. z13B3870YOgv

link_id string

Loop Link ID that was used to submit this event. Will only be available on submissions that were made with a Loop Link.

create_dt string

The creation date time for the record in ISO 8601 format format.

E.g. 2022-04-26T11:46:24+00:00

update_dt string

The last update date time for the record in ISO 8601 format format.

E.g. 2022-04-26T11:46:24+00:00

version number

Version number of the record. This number increments automatically every time the record is updated.

phq_review string

Current review status. All submissions go through a moderation process. This field refers to the PredictHQ moderators. Possible values:

pending
approved
rejected

org_review string

Current review status for customer-initiated reviews. Some organizations are able to review submissions before they're moderated by PredictHQ staff. Possible values:

pending
approved
rejected

phq_auto_approved boolean

Indicates whether or not the record was automatically approved. Some organizations are able to have their submissions enter our automatic review process after a period of time with consistent high quality level of submissions.

event.title string

The title of the event. E.g. Katy Perry

event.description string

A description of the event.

E.g. See Katy Perry in concert [...]

event.category string

The category of the event.

Please see Search Events for a list of possible categories.

E.g. concerts

event.state string

The publication state of the event. Please see Search Events for a list of possible states.

event.metadata array

List of metadata associated with the event.

E.g.

{
  "metadata": [
    {
      "maximum_attendance": 5000
    },
    {
      "attendance": 3215
    }
  ]
}

event.dates object

Event dates. E.g.

{
  "dates": {
    "fixed_date": {
      "start_date": "2023-06-02",
      "end_date": "2023-06-04"
    }
  }
}

event.labels array

List of labels for the event.

E.g.

{
  "labels": [
    "festival",
    "food",
    "music"
  ]
}

event.lat string

Latitude for the event.

E.g. 38.901544

event.lon string

Longitude for the event. E.g. -119.7030036

event.address string

Address for the event. E.g. 859 U.S. Highway 395 North

event.formatted_addressstring

Full formatted address for the event.

E.g.

859 U.S. Highway 395 North
Gardnerville, Nevada 89410
United States of America

event.city string

City of the event.

event.region string

Region of the event.

event.postcode string

Postcode of the event.

event.country string

Country code in ISO 3166-1 alpha-2 format.

event.geometry object

Geographic location of the event. Represented in GeoJSON format.

E.g.

{
  "geometry": {
    "type": "Point",
    "coordinates": [
      -119.703022,
      38.9012446
    ]
  }
}

Example response

Below is an example response:

{
  "count": 1,
  "events": [
    {
      "event_id": "tae8Mie8keiceicoMae2ie",
      "link_id": "ber7ntO0ZHuFVCfrSNsN",
      "create_dt": "2023-02-16T00:52:11.112355+00:00",
      "update_dt": "2023-05-09T02:05:51.695054Z",
      "version": 1,
      "phq_review": "approved",
      "org_review": "pending",
      "phq_auto_approved": false,
      "event": {
        "title": "Hotel A event",
        "description": "The 2023 edition of Hotel A festival.",
        "category": "festivals",
        "state": "active",
        "metadata": [
          {
            "maximum_attendance": 5000
          },
          {
            "attendance": 3215
          }
        ],
        "dates": {
          "fixed_date": {
            "start_date": "2023-06-02",
            "end_date": "2023-06-04"
          }
        },
        "labels": [
          "festival",
          "food",
          "music"
        ],
        "lat": "38.901544",
        "lon": "-119.7030036",
        "address": "859 U.S. Highway 395 North",
        "formatted_address": "859 U.S. Highway 395 North\nGardnerville, Nevada 89410\nUnited States of America",
        "city": "Gardnerville",
        "region": "Nevada",
        "postcode": "89410",
        "country": "US",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -119.703022,
            38.9012446
          ]
        }
      }
    }
  ]
}

Examples

curl -X GET https://api.predicthq.com/v1/loop/events?phq_review=approved \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

import requests

response = requests.get(
    url="https://api.predicthq.com/v1/loop/events",
    headers={
      "Authorization": "Bearer $ACCESS_TOKEN",
      "Accept": "application/json"
    },
    params={
        "phq_review": "approved"
    }
)

print(response.json())

Guides

Below are some guides relevant to this API:

Integrate with Loop Links

PreviousLoop Submissions NextLoop Feedback

Last updated 9 months ago