FloodTags API (V2)

Download OpenAPI specification:Download

API to access FloodTags data, meant for the querying, export and editing of 'Tags' and 'Events', for the purpose of visualizing the data and implementing FloodTags data in custom front-end solutions.

Structure

The API consists of the following base endpoints:

/tags: Endpoints for querying, exporting and editing 'Tags'. 'Tags' are what we call individual online media reports, such as Tweets, News Articles and Youtube Video's
/events: Endpoints for querying, exporting and editing 'Events' that are detected based on online media data. For flood related data sources for example, these are flood-events, which are periods in time in which flooding occured.
/user: Endpoints related to retrieving information and authorizations for the currently logged-in user and editing user settings.

If you're looking to develop a custom solution based on the FloodTags API, it may also help to login to the FloodTags Dashboard, and use your browser's developer tools to inspect all requests to api.floodtags.com, to get an idea how the API can be used from a front-end.

Rate-Limits

Note that the API is designed for implementation in front-ends, and rate-limits apply. On average, you should not send more than 1 request every 2 seconds. To receive bulk data, please contact FloodTags at info@floodtags.com

Tags

Query Tags

Query the tags (Tweets, News Articles, Videos etc.) in the FloodTags database, and return the results in one or more representations (views)

Authorizations:

APIKeyAuthenticationSessionBasedAuthentication

query Parameters

views required	Array of strings non-empty Items Enum: "tags" "locations" "graph" "counts.words" "counts.hashtags" "counts.author.names" "counts.mentions.cause" "counts.mentions.impact" Example: views=tags,locations One or more representations in which to return the queried data. Please see the 'response schema' under the '200' response code below to find a description of each view.
sources	Array of strings non-empty Example: sources=spanish-flood-news,english-flood-news The data-sources for which to return data. Find the list of authorized sources for your account at /user?views=sources. (required if 'ids' is not provided)
date.since	string <date-time> Example: date.since=2020-02-02T12:34:33Z Beginning of time range for query (including/gte, required if 'event.id' or 'ids' is not provided)
date.until	string <date-time> Example: date.until=2020-02-02T12:35:33Z End of time range for query (excluding/lt, required if 'event.id' or 'ids' is not provided)
event.id	string Example: event.id=ev-992838847739 If given, only tags from this event are queried. In case no start and end-date are given, or these are outside the bounds of this event, the date.since and date.until parameters are automatically set to the start/end of the event
ids	Array of strings <= 50 items Example: ids=t-123456789,t-987654321-edited-4s3546d6w8 Query for tags with these ids (Note: url parameters, other than views/format-related ones, are ignored)
shareURLIds	Array of strings <= 10000 items Example: shareURLIds=t-123456789,t-987654321-edited-4s3546d6w8 Filter for ids that are in currently selected shareable URL.
filters	Array of strings Example: filters=high_keyword_score,class:transport Filters to apply to the query. Find the list of filters that can be used for each source at /user?views=sources.
contains	Array of strings Items Enum: "locations" "photos" "waterDepth" "labels" "share-url" Include only tags that contain these fields
labels	Array of strings Example: labels=Recent Flood,Damages Mentioned Query by these user-added labels. Note that if labels contain commas, these should be double encoded (e.g. %252C). To achieve this, first URL encode each label (e.g. with this function, then join the array using comma's, and then URL encode it again.
not.labels	Array of strings Example: not.labels=Incorrect Location,Unrelated Filter query results by exluding items that have these user-added labels. The same formatting conventions as for the 'labels' parameter apply.
location.id	string Example: location.id=g-8837749 Return only data that have a location with this ID
location.bbox	Array of numbers = 4 items Example: location.bbox=4.17698,52.01303,4.46404,52.11796 Return only data with locations within this bounding box (order:west,south,east,north)
location.parent.id	Array of strings <= 10 items Example: location.parent.id=g-8839948 Return only items that have locations with either these ids, or one of these IDs in their lists of parent locations
query	string Example: query=flood \| floods \| flooding Full-text query on the text field, in the syntax described here. Note that 'and' is the default operator, and FUZZY, SLOP and NEAR matching are disabled.
author.name	string Example: author.name=floodtags Return only tags from an author with this name (e.g. the 'screen name' for Tweets)
source.name	string Example: source.name=Washington Post Return only tags originating from the source with the given name
view.graph.interval	string^(\d+(ms\|s\|m\|h\|d))\|(1(M\|q\|y))$ Default: "1h" Example: view.graph.interval=1d Time interval of graph data in the format described here (`views=graph` only)
view.tags.limit	integer [ 0 .. 100 ] Default: 10 The number of results to show per page (`views=tags` only)
view.tags.skip	integer [ 0 .. 10000 ] Default: 0 The result at which to start the page (offset, `views=tags` only)

Responses

Response samples

200
400
401
403

Content type

application/json

Example

Succesful request

{"status": "success",
"total": 1,
"errors": [ ],
"data": {"tags": [{"id": "news-eventregistry-2024-12-564327493",
"text": "The body text of a tag about flooding",
"date": "2021-11-22T22:52:30.000Z",
"keywords": ["flooding"
],
"locations": [{"type": "Feature",
"geometry": {"type": "Point",
"coordinates": [180,
90
]
},
"properties": {"id": "g-123235",
"name": "Location name",
"type": "adm5",
"source": "geoparsing-enrichment",
"parents": ["g-1123556",
"g-4454565"
]
}
}
],
"media": {"photos": [{"url": "https://www.domain.tld/image.jpg",
"analysis": {"floodRelated": false
}
}
]
},
"score": {"keywords": 1.0556
},
"source": {"id": "12334565887",
"lang": "en",
"type": "news",
"url": "https://platform-website.com/news/local/12334565887",
"author": {"id": "platform_screen_name",
"name": "Full User Name"
}
},
"topics": ["flood"
],
"waterDepth": 30,
"labels": [ ]
}
],
"sources": ["english-flood-news",
"english-storms-news",
"english-hail-news"
],
"locations": [{"type": "Feature",
"geometry": {"type": "Point",
"coordinates": [180,
90
]
},
"properties": {"total": 1,
"id": "g-123235",
"name": "Location name",
"type": "adm5",
"parents": ["g-1123556",
"g-4454565"
]
}
}
],
"graph": {"dates": ["2021-11-22T00:00:00.000Z",
"2021-11-22T01:00:00.000Z",
"2021-11-22T02:00:00.000Z"
],
"counts": [15,
10,
12
]
},
"counts": {"words": {"flooding": 78,
"flooded": 56,
"bangalore": 16
},
"hashtags": {"#flooding": 96,
"#floods": 56,
"#bangalore": 45
},
"author.names": {"cityNews": 78,
"morningHerald": 90,
"peterPan": 1
}
}
}
}

Export Tags

Export the query results to a CSV or GeoJSON file

Authorizations:

APIKeyAuthenticationSessionBasedAuthentication

query Parameters

sources	Array of strings non-empty Example: sources=spanish-flood-news,english-flood-news The data-sources for which to return data. Find the list of authorized sources for your account at /user?views=sources. (required if 'ids' is not provided)
date.since	string <date-time> Example: date.since=2020-02-02T12:34:33Z Beginning of time range for query (including/gte, required if 'event.id' or 'ids' is not provided)
date.until	string <date-time> Example: date.until=2020-02-02T12:35:33Z End of time range for query (excluding/lt, required if 'event.id' or 'ids' is not provided)
event.id	string Example: event.id=ev-992838847739 If given, only tags from this event are queried. In case no start and end-date are given, or these are outside the bounds of this event, the date.since and date.until parameters are automatically set to the start/end of the event
ids	Array of strings <= 50 items Example: ids=t-123456789,t-987654321-edited-4s3546d6w8 Query for tags with these ids (Note: url parameters, other than views/format-related ones, are ignored)
shareURLIds	Array of strings <= 10000 items Example: shareURLIds=t-123456789,t-987654321-edited-4s3546d6w8 Filter for ids that are in currently selected shareable URL.
filters	Array of strings Example: filters=high_keyword_score,class:transport Filters to apply to the query. Find the list of filters that can be used for each source at /user?views=sources.
contains	Array of strings Items Enum: "locations" "photos" "waterDepth" "labels" "share-url" Include only tags that contain these fields
labels	Array of strings Example: labels=Recent Flood,Damages Mentioned Query by these user-added labels. Note that if labels contain commas, these should be double encoded (e.g. %252C). To achieve this, first URL encode each label (e.g. with this function, then join the array using comma's, and then URL encode it again.
not.labels	Array of strings Example: not.labels=Incorrect Location,Unrelated Filter query results by exluding items that have these user-added labels. The same formatting conventions as for the 'labels' parameter apply.
location.id	string Example: location.id=g-8837749 Return only data that have a location with this ID
location.bbox	Array of numbers = 4 items Example: location.bbox=4.17698,52.01303,4.46404,52.11796 Return only data with locations within this bounding box (order:west,south,east,north)
location.parent.id	Array of strings <= 10 items Example: location.parent.id=g-8839948 Return only items that have locations with either these ids, or one of these IDs in their lists of parent locations
query	string Example: query=flood \| floods \| flooding Full-text query on the text field, in the syntax described here. Note that 'and' is the default operator, and FUZZY, SLOP and NEAR matching are disabled.
author.name	string Example: author.name=floodtags Return only tags from an author with this name (e.g. the 'screen name' for Tweets)
source.name	string Example: source.name=Washington Post Return only tags originating from the source with the given name
format required	string Enum: "csv" "geojson" In which format to export the tag data

Responses

Response samples

200
400
401
403

Content type

application/geo+json

"string"

Edit Tags

Edit tags (Tweets, News Articles, Videos etc.) in the FloodTags system by changing one or more fields of the tag

Authorizations:

APIKeyAuthenticationSessionBasedAuthentication

query Parameters

ids

required

Array of strings <= 50 items

Example: ids=t-123456789,t-987654321-edited-4s3546d6w8

Apply the operation to tags with these ids

Request Body schema: application/json
required

The fields to replace in the body of the tags

non-empty

labels	Array of strings Array of labels. To delete, send an empty array
waterDepth	number or null A number in cm to indicate waterdepth. To delete, send null
	Array of objects or objects Array of locations, each one either with only an id, in order to keep an existing location, or with a full geometry and a name, to add a manually defined location

Responses

Request samples

Payload

Content type

application/json

{"labels": ["Flood Related",
"Contains Damage"
],
"waterDepth": 30,
"locations": [{"properties": {"id": "g-123456"
}
},
{"type": "Feature",
"geometry": {"type": "Point",
"coordinates": [4.33485067695305,
52.07393073093554
]
},
"properties": {"name": "FloodTags Office"
}
}
]
}

Response samples

200
400
401
403
404

Content type

application/json

Example

Request successful

{"status": "success",
"errors": [ ]
}

Delete Tags

Delete tags (Tweets, News Articles, Videos etc.) from the FloodTags system for your user or user-group

Authorizations:

APIKeyAuthenticationSessionBasedAuthentication

query Parameters

ids

required

Array of strings <= 50 items

Example: ids=t-123456789,t-987654321-edited-4s3546d6w8

Apply the operation to tags with these ids

Responses

Response samples

200
400
401
403
404

Content type

application/json

Example

Request successful

{"status": "success",
"errors": [ ]
}

Events

Query Events

Query the events detected by FloodTags, and return the results in one or more representations (views)

Authorizations:

APIKeyAuthenticationSessionBasedAuthentication

query Parameters

views required	Array of strings non-empty Items Enum: "events" "locations" Example: views=events One or more representations in which to return the queried data. Please see the 'response schema' under the '200' response code below to find a description of each view.
sources	Array of strings non-empty Example: sources=spanish-flood-news,english-flood-news The data-sources for which to return data. Find the list of authorized sources for your account at /user?views=sources. (required if 'ids' is not provided)
date.since	string <date-time> Example: date.since=2020-02-02T12:34:33Z Beginning of time range for query (including/gte, required if 'ids' is not provided)
date.until	string <date-time> Example: date.until=2020-02-02T12:35:33Z End of time range for query (excluding/lt, required if 'ids' is not provided)
ids	Array of strings <= 50 items Example: ids=ev-123456789,ev-987654321-edited-4s3546d6w8 Query for events with these ids (Note: url parameters, other than views/format-related ones, are ignored)
labels	Array of strings Example: labels=Recent Flood,Damages Mentioned Query by these user-added labels. Note that if labels contain commas, these should be double encoded (e.g. %252C). To achieve this, first URL encode each label (e.g. with this function, then join the array using comma's, and then URL encode it again.
not.labels	Array of strings Example: not.labels=Incorrect Location,Unrelated Filter query results by exluding items that have these user-added labels. The same formatting conventions as for the 'labels' parameter apply.
location.id	string Example: location.id=g-8837749 Return only data that have a location with this ID
location.bbox	Array of numbers = 4 items Example: location.bbox=4.17698,52.01303,4.46404,52.11796 Return only data with locations within this bounding box (order:west,south,east,north)
location.parent.id	Array of strings <= 10 items Example: location.parent.id=g-8839948 Return only items that have locations with either these ids, or one of these IDs in their lists of parent locations
view.events.limit	integer [ 0 .. 100 ] Default: 10 The number of results to show per page (Only for tag view)
view.events.skip	integer [ 0 .. 10000 ] Default: 0 The result at which to start for paging (offset)

Responses

Response samples

200
400
401
403

Content type

application/json

{"status": "success",
"errors": [ ],
"total": 1,
"data": {"events": [{"id": "ev-121123454654",
"start": "2021-05-10T12:33:12Z",
"end": "2021-05-11T12:59:59Z",
"counts": {"english-flood": 16,
"french-flood": 38
},
"location": {"type": "Feature",
"geometry": {"type": "Point",
"coordinates": [10.98361,
44.5444
]
},
"severeness": 7,
"properties": {"name": "Emilia-Romagna",
"id": "g-3177401",
"parents": ["g-3177401",
"g-3175395"
],
"type": "adm4"
}
},
"mergedFrom": ["ev-345223454653"
],
"labels": [ ]
}
],
"locations": [{"type": "Feature",
"geometry": {"type": "Point",
"coordinates": [10.98361,
44.5444
]
},
"properties": {"name": "Emilia-Romagna",
"id": "g-3177401",
"parents": ["g-3177401",
"g-3175395"
],
"type": "adm4",
"total": 1
}
}
]
}
}

Export Events

Export the query results to a CSV or GeoJSON file

Authorizations:

APIKeyAuthenticationSessionBasedAuthentication

query Parameters

sources	Array of strings non-empty Example: sources=spanish-flood-news,english-flood-news The data-sources for which to return data. Find the list of authorized sources for your account at /user?views=sources. (required if 'ids' is not provided)
date.since	string <date-time> Example: date.since=2020-02-02T12:34:33Z Beginning of time range for query (including/gte, required if 'ids' is not provided)
date.until	string <date-time> Example: date.until=2020-02-02T12:35:33Z End of time range for query (excluding/lt, required if 'ids' is not provided)
ids	Array of strings <= 50 items Example: ids=ev-123456789,ev-987654321-edited-4s3546d6w8 Query for events with these ids (Note: url parameters, other than views/format-related ones, are ignored)
labels	Array of strings Example: labels=Recent Flood,Damages Mentioned Query by these user-added labels. Note that if labels contain commas, these should be double encoded (e.g. %252C). To achieve this, first URL encode each label (e.g. with this function, then join the array using comma's, and then URL encode it again.
not.labels	Array of strings Example: not.labels=Incorrect Location,Unrelated Filter query results by exluding items that have these user-added labels. The same formatting conventions as for the 'labels' parameter apply.
location.id	string Example: location.id=g-8837749 Return only data that have a location with this ID
location.bbox	Array of numbers = 4 items Example: location.bbox=4.17698,52.01303,4.46404,52.11796 Return only data with locations within this bounding box (order:west,south,east,north)
location.parent.id	Array of strings <= 10 items Example: location.parent.id=g-8839948 Return only items that have locations with either these ids, or one of these IDs in their lists of parent locations
format required	string Enum: "csv" "geojson" In which format to export the event data

Responses

Response samples

200
400
401
403

Content type

application/geo+json

"string"

Edit Events

Edit events in the FloodTags system, by changing/adding one or more fields of an event (Currently only supports adding labels and changing name). Note that after editing, ongoing events are no longer updated (e.g. end-date extended)

Authorizations:

APIKeyAuthenticationSessionBasedAuthentication

query Parameters

ids

required

Array of strings <= 50 items

Example: ids=ev-123456789,ev-987654321-edited-4s3546d6w8

Apply the operation to events with these ids

Request Body schema: application/json
required

The fields to replace in the event data

non-empty

labels	Array of strings
name	string
end	string

Responses

Request samples

Payload

Content type

application/json

{"labels": ["Flood Related",
"Contains Damage"
]
}

Response samples

200
400
401
403
404

Content type

application/json

Example

Request successful

{"status": "success",
"errors": [ ],
"idUpdates": {"ev-123456789": "ev-123456789-edited-4s3546d6w8"
}
}

Delete Events

Delete events in the FloodTags system (For your user or user-group only)

Authorizations:

APIKeyAuthenticationSessionBasedAuthentication

query Parameters

ids

required

Array of strings <= 50 items

Example: ids=ev-123456789,ev-987654321-edited-4s3546d6w8

Apply the operation to events with these ids

Responses

Response samples

200
400
401
403
404

Content type

application/json

Example

Request successful

{"status": "success",
"errors": [ ]
}

User Data

Get the user-specific data of the current user (user information, settings etc.)

Authorizations:

APIKeyAuthenticationSessionBasedAuthentication

query Parameters

views

required

Array of strings non-empty

Items Enum: "info" "settings.dashboard" "settings.notifications" "settings.custom" "authorization" "sources" "labels.tags" "labels.events" "apikey"

Example: views=info,settings.dashboard

The type of data to return for the user. See response data for details about each

Responses

Response samples

200
400
401

Content type

application/json

{"status": "success",
"errors": [ ],
"data": {"info": {"name": "John Smith",
"email": "johnsmith@floodtags.com",
"organization": "FloodTags",
"country": "The Netherlands"
},
"authorization": {"date": {"since": "1970-01-01T00:00:00Z",
"until": "2100-01-01T00:00:00Z",
"ranges": [{"since": "1970-01-01T00:00:00Z",
"until": "1971-01-01T00:00:00Z"
},
{"since": "2023-01-01T00:00:00Z",
"until": "2100-01-01T00:00:00Z"
}
]
},
"sources": ["english-flood",
"indonesian-flood"
],
"functions": ["view",
"export",
"edit",
"delete"
]
},
"settings": {"dashboard": {"defaultQuery": {"sources": ["english-flood"
],
"date": {"since": "now - 48h",
"until": "now"
},
"labels": [ ],
"not": {"labels": [ ]
},
"contains": ["locations"
],
"filters": ["high_keyword_score",
"with_flood_related_photos"
],
"customFilters": ["Only churches"
]
},
"visibleSources": ["english-flood",
"french-flood",
"english-flood-news"
],
"customFilters": [{"name": "Only churches",
"query": "church | cathedral | mosque",
"visible": true
}
],
"baseMap": "OSM",
"showTermsOfService": false
}
},
"sources": [{"id": "english-flood",
"name": "English",
"language": "en",
"type": "twitter",
"filters": {"tags": [{"id": "only_detailed_locations",
"name": "Exclude Country Level",
"description": "Excludes tags that only have the country level location detected"
},
{"id": "only_most_detailed_locations",
"name": "Only Most Detailed Locations",
"description": "Show only the most detailed locations for each tag (e.g. if both a city and the country it's in are detected, only the city is shown)"
},
{"id": "high_keyword_score",
"name": "Flood Related",
"description": "Shows only Tags about floods, based on keyword analysis"
},
{"id": "with_flood_related_photos",
"name": "With Flood Photos",
"description": "Shows only tags that have one or more images that were classified as flood related by machine learning"
}
]
}
}
],
"labels": {"tags": ["support",
"damages"
],
"events": ["large",
"withCasualties"
]
}
}
}

Edit User Data

Edit the user data

Authorizations:

APIKeyAuthenticationSessionBasedAuthentication

query Parameters

operation

string

Default: "update"

Enum: "update" "replace"

Whether the request body should be used to update existing data, or completely replace it. If for example only 'settings.dashboard.defaultQuery' is in the request body, and this is set to 'update', only the lowest level keys that are given inside the 'settings.dashboard.defaultQuery' object are updated in the user data. If this is set to 'replace', the complete 'dashboard.settings' object is replaced, meaning it will only contain the 'defaultQuery' object with the provided contents.

Request Body schema: application/json
required

The fields to replace in the event data

non-empty

object (settingsSchema)

Responses

Request samples

Payload

Content type

application/json

{"settings": {"dashboard": {"defaultQuery": {"sources": ["english-flood"
],
"date": {"since": "now - 48h",
"until": "now"
},
"labels": [ ],
"not": {"labels": [ ]
},
"contains": ["locations"
],
"filters": ["high_keyword_score",
"with_flood_related_photos"
],
"customFilters": ["Only churches"
]
},
"visibleSources": ["english-flood",
"french-flood",
"english-flood-news"
],
"customFilters": [{"name": "Only churches",
"query": "church | cathedral | mosque",
"visible": true
}
],
"baseMap": "OSM",
"showTermsOfService": false
}
}
}

Response samples

200
400
401

Content type

application/json

{"status": "success",
"errors": [ ]
}

Request Feature

Request specific features and/or configurations from FloodTags

Authorizations:

APIKeyAuthenticationSessionBasedAuthentication

Request Body schema: application/json
required

A JSON object describing the request subject and details

Any of

subject

required

string

Value: "api-key"

The subject of the request

Responses

Request samples

Payload

Content type

application/json

{"subject": "additional-sources",
"details": "Facebook, Instagram, Youtube"
}

Response samples

200
400
401
429

Content type

application/json

{"status": "success",
"errors": [ ]
}

FloodTags API (V2)

Structure

Rate-Limits

Tags

Query Tags

Authorizations:

query Parameters

Responses

Response samples

Export Tags

Authorizations:

query Parameters

Responses

Response samples

Edit Tags

Authorizations:

query Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete Tags

Authorizations:

query Parameters

Responses

Response samples

Events

Query Events

Authorizations:

query Parameters

Responses

Response samples

Export Events

Authorizations:

query Parameters

Responses

Response samples

Edit Events

Authorizations:

query Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete Events

Authorizations:

query Parameters

Responses

Response samples

User Data

User Data

Authorizations:

query Parameters

Responses

Response samples

Edit User Data

Authorizations:

query Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Request Feature

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required