Giter VIP home page Giter VIP logo

liveactionmap's Introduction

Contributors Forks Stargazers Issues LinkedIn


Logo

Live Action Map (LAM)

An attempt to use open source data on Twitter to map areas with active conflict. Right now it is used for the Ukraine-Russia conflict, but in the future I hope it can be used for all sorts of dangerous situations.
Report Bug · Add Feature · Website Live! · Join Discord!

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Roadmap
  5. Contributing
  6. License

About The Project

There are many twitter accounts posting live tweets about locations with conflicts. However, it is difficult to keep track of the locations especially with multiple different sources pointing out different location every few minutes. To make sure people can stay safe and take care of themselves, I have aggregated all the tweets into a single map that is easily accessible.

This project is a work in progress. I am working on adding more features and improving the map.

Website Link Image

How it works:

  • Tweets are sourced using keywords, hashtags and prepositions, such as the phrase "shooting... near ... location".
  • Tweets can also be sourced from known twitter accounts by passing their usernames.
  • Tweets are parsed with NLP and the location is extracted from the tweet, this however is not perfect so we need to filter locations later on.
  • Some tweets might talk about other countries reactions like "The US.." or "Russia.." or "Moscow..", in that case we remove all the locations that are not in Ukraine.
  • Some tweets might talk about multiple locations like "Shooting near the location and the location". In that case both locations are added to the map. Multiple markers can be added to the same location.
  • Finally we add markers for each tweet.
  • Markers will cluster together when you zoom out.
  • A single marker looks like a red pin on a map.
  • A cluster appears as a circle with a number inside it, the color shifts from green to orange to red depending on the number of markers in the cluster.
  • We are not taking data directly because that may be vulnerable to trolling and spamming.
  • We are using the Twitter v2 API to get the tweets, however it does not support parsing location directly from tweets.

(back to top)

Getting Started

To get a local copy up and running follow these simple example steps.

Prerequisites

  • Python
  • tweepy
  • spaCy
  • folium
  • geopy
  • tqdm
  • geography3 (optional, needed for experimental feature)

Installation

Python

  1. Get a free twitter Bearer Token from developer.twitter.com. Remember to create a new app and get the bearer token.
  2. Clone the repo
    git clone https://github.com/kinshukdua/LiveActionMap.git
  3. Install all prerequisites
    pip install -r requirements.txt
  4. Download en_core_web, for more info see --> explosion/spaCy#4577
     python3 -m spacy download en_core_web_sm
  5. Create a .env file based on the .env.example
    cp .env.example .env
  6. Set the Twitter bearer token to your own in the .env file created in the previous step.

Docker

  1. Get a Twitter Bearer Token
  2. Download the docker-compose.yaml-file
    wget https://raw.githubusercontent.com/kinshukdua/LiveActionMap/main/docker/docker-compose.yaml
  3. Create a .env file based on the .env.example
    wget https://raw.githubusercontent.com/kinshukdua/LiveActionMap/main/.env.example -O .env 
  4. Start the stack
    docker-compose up -d
    

(back to top)

Usage

Simply edit hashtags, prepositions and keywords and run scrape.py.

python scrape.py

(back to top)

Roadmap

  • Add tweet scraping
  • Add map
  • Add map clustering
  • Create a server to host the generated map
  • Add better filtering
  • Add tweet link on map
  • Use NLP to indicate danger level
  • Add misinformation prevention algorithm
  • Multi-language Support
    • Ukranian
    • Russian

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

liveactionmap's People

Contributors

domiibunn avatar edubacco avatar gabrielecalarota avatar kinshukdua avatar krishna-sivakumar avatar laurin avatar rodrigoborgesdeoliveira avatar sahal-mulki avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

liveactionmap's Issues

Implement a ui

I think it would be a pretty good idea to implement a ui for this instead of just generating a PNG.

If needed i could spare some time in Vue. By all means i have a free weekend right now.

IP Blocking - Russia?

Should we block Russia from using the applet?

This might be actually helpful in order not to leak possible troop information,

Add SEO

Add some SEO tags to make the map easier to find online

Dynamic Fronted

How about I make a quick mockup with vuejs that would just read an api. That way once the project is evolved enough it would be enough to just hook one and the other together.

Originally posted by @Krishna-Sivakumar in #24 (comment)

Dockerize for Scalability

I don't really know a lot about python but should dockerize the app for easier future scalability.

Analitics

It would be neat to see how many hits the site gets.

I'd recommend either google or unami(this is more gdpr complaint and can be self hosted on Heroku for free)

Domain name

I was trying to get a domain on freenom, but it doesn't let me register, for the time being I'll deploy it on my custom domain but if anyone has a spare domain lying around or if they can register a free "liveactionmap" domain on freenom that would be great.

Remove temporary tweets file after every x minutes.

Since we're no longer dependent on the cronjob, we need to remove the tweets in the python code itself. However deleting the file after each run as done in an earlier PR is not useful because there's too few data points, we can try to increase the number of results we get from Twitter but that's a separate issue.

Also let's make sure the schedule time for the scraping and removing tweets don't overlap (they are not multiples) otherwise the tweets file might be deleted while the bot is running outputting an empty map.

Self-host a Nominatim Service

Self-hosting a Nominatim service will help us cut down on time wasted doing API calls.
Map building takes the most time. And right now, most of the time while building the map is spent on doing 2 API calls to a public Nominatim service per tweet, which adds a lot of latency.

Since we already have a docker build, it doesn't hurt to add one or two more containers to our deployment.

Links to refer:
https://github.com/mediagis/nominatim-docker
https://nominatim.org/release-docs/latest/admin/Installation/

This will help us shift to a dynamic backend in the long run.

Add time to popup

I think it would be good to add the time of the tweet in the popup,

Cache Nominatim geocoding API

As getting the latitude and longitude of the found location seems to be the most time-consuming operation, it would probably make sense to cache the responses of the Nominatim API.

Add CI/CD and Tests

As the project grows, we need a way to make sure it is easy to test incoming PRs instead of me manually pulling and testing everything. The best way would be to setup a CI/CD pipeline using Github Actions. At the present moment we don't have any tests except the one introduced in #21. Ideally I would like to setup tests and then a CI/CD pipeline. However, the server running the website right now, is manually using cron jobs. I would instead like to wait for #16 to finish and then create a pipeline with the docker image.

Meanwhile, feel free to add tests and help me write a CI pipeline.

API: Markers

Create a GET API serving /api/markers providing a response containing all currently available markers.

Expected response

{
    "markers": [
        {
            "position": [
                49.038230248475905,
                31.450182690663947
            ],
            "title": "Twit Title with image",
            "content": "",
            "user": "Twitter User",
            "uri": "https://twitter/postUrl",
            "image": "imageURL",
            "timestamp": "unixtimestamp of tweet"
        },
        {
            "position": [
                48.038230248475905,
                31.450182690663947
            ],
            "title": "Twit Title without image",
            "content": "Twit Text",
            "user": "Twitter User",
            "uri": "https://twitter/postUrl",
            "timestamp": "unixtimestamp of tweet"
        }
    ],
    "timestamp": "unixTimeStamp"
}

Show safe locations

Show the location of places like subway stations where people can hide in case of a conflict.

Community: Discord server

It might be useful to aid development, implement an uptime monitor notification, and general future requests.

API: Zones

Create a GET API serving /api/zonesproviding a response containing all currently available markers.

Expected response

[
    {
        "positions": [
            [
                50.36429316995319,
                30.228621662109
            ],
            [
                50.51303377189189,
                30.28741424805162
            ],
            [
                50.60122461757218,
                30.787151228563896
            ],
            [
                50.44548234821721,
                30.77081995469095
            ]
        ],
        "color": "green",
        "title": "Safe Zone",
        "content": "Some safe zone over here"
    }
]

Persistently store scraped tweets

As discussed in #16, the current storage of scraped tweets is not optimal, because the newly scraped tweets will just be appended to the existing tweets.txt-file, creating a lot of duplicates.
Integrating a database is probably not necessary at this point, we could store the scraped tweets with their ID in a json-file and only add new ones in the run of the application.

Add blacklist

Add a blacklist for Twitter accounts spreading misinformation.

Add a .onion link

This is so people can access the site using tor, might make some people feel safer.

This would need a separate frontend that doesn't contain any tracking and no links to anything but out service

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.