GAPMAP

A helper library that makes pathing simple in the real world. Point to Point distance finding and even Placename finding.

Roadmap

• Placename finder (City, Country)
• Airport finder
• Euclidean Distances
• Radius around point generation
• GIS based Pathing
• GIS Based timing
• Map Generation
• Hotswapping hosted maps

Installation

pip install gapmap or download the latest binary from the releases tab

Usage

1. Get City by name
2. Distance between cities
3. Radius around coords
4. Is out of radius
5. Airport Finder

Get City by name

from gapmap import get_city_by_name

# this is not case sensitive
# Expanded returns continent and country information also
city = get_city_by_name("edinburgh", expanded=True)

# The returning object could be one of just the city information itself or an array of cities
cities = city.get('cities', None)

if cities is None:
    print(city)
else:
    print(cities)

This will return

{
  "id": 2650225,
  "name": "Edinburgh",
  "countrycode": "GB",
  "latitude": 55.95206,
  "longitude": -3.19648,
  "population": 506520,
  "timezone": "Europe/London",
  "country": {
    "id": 2635167,
    "name": "United Kingdom",
    "iso": "GB",
    "iso3": "GBR",
    "isonumeric": 826,
    "fips": "UK",
    "continentcode": "EU",
    "capital": "London"
  },
  "continent": {
    "id": 6255148,
    "name": "Europe",
    "bounding": {
      "north": 80.76416015625,
      "south": 27.6377894797159,
      "east": 41.73303985595703,
      "west": -24.532675386662543
    }
  }
}

Distance between cities

from gapmap import distance_between_cities

distance = distance_between_cities("edinburgh", "glasgow")

This will return

{
  "distances": {
    "miles": 41.67,
    "km": 67.07,
    "meters": 67065.32,
    "yards": 73343.5
  },
  "from": {
    "id": 2650225,
    "name": "Edinburgh",
    "countrycode": "GB",
    "latitude": 55.95206,
    "longitude": -3.19648,
    "population": 506520,
    "timezone": "Europe/London"
  },
  "to": {
    "id": 2648579,
    "name": "Glasgow",
    "countrycode": "GB",
    "latitude": 55.86515,
    "longitude": -4.25763,
    "population": 626410,
    "timezone": "Europe/London"
  }
}

Radius around coords

This will provide a circular radius around the given latitude and longitude the radius from point to circle is in miles. There is an optional radial step that you can draw at each degree around the circle or you can step it up to whatever you want 1-359 the default step is every 10 degrees

from gapmap import radius_around_coords

radius = radius_around_coords(55.95206, -3.19648, radial_step=10)

This will return

{
  "id": 2650225,
  "name": "Edinburgh",
  "countrycode": "GB",
  "latitude": 55.95206,
  "longitude": -3.19648,
  "population": 506520,
  "timezone": "Europe/London",
  "range": 15,
  "radius": [
    {
      "latitude": 55.95219485590659,
      "longitude": -3.19648,
      "bearing": 0
    },
    {
      "latitude": 55.952192807135276,
      "longitude": -3.1964381744369734,
      "bearing": 0.17453292519943295
    },
    {
      "latitude": 55.95218672307282,
      "longitude": -3.196397619735461,
      "bearing": 0.3490658503988659
    },
    {
      "latitude": 55.95217678858224,
      "longitude": -3.196359568140929,
      "bearing": 0.5235987755982988
    },
    {
      "latitude": 55.95216330552083,
      "longitude": -3.1963251758402738,
      "bearing": 0.6981317007977318
    },
    {
      "latitude": 55.95214668356804,
      "longitude": -3.196295487830642,
      "bearing": 0.8726646259971648
    },
    {
      "latitude": 55.95212742777716,
      "longitude": -3.1962714061671837,
      "bearing": 1.0471975511965976
    },
    {
      "latitude": 55.95210612322911,
      "longitude": -3.1962536625545614,
      "bearing": 1.2217304763960306
    },
    {
      "latitude": 55.95208341725465,
      "longitude": -3.1962427961150164,
      "bearing": 1.3962634015954636
    },
    {
      "latitude": 55.95205999976514,
      "longitude": -3.196239137008431,
      "bearing": 1.5707963267948966
    },
    {
      "latitude": 55.95203658228979,
      "longitude": -3.196242796401961,
      "bearing": 1.7453292519943295
    },
    {
      "latitude": 55.95201387635612,
      "longitude": -3.196253663093841,
      "bearing": 1.9198621771937625
    },
    {
      "latitude": 55.951992571870555,
      "longitude": -3.196271406893753,
      "bearing": 2.0943951023931953
    },
    {
      "latitude": 55.95197331615633,
      "longitude": -3.196295488656866,
      "bearing": 2.2689280275926285
    },
    {
      "latitude": 55.95195669428511,
      "longitude": -3.1963251766664977,
      "bearing": 2.443460952792061
    },
    {
      "latitude": 55.95194321130033,
      "longitude": -3.1963595688674986,
      "bearing": 2.6179938779914944
    },
    {
      "latitude": 55.951933276872246,
      "longitude": -3.19639762027474,
      "bearing": 2.792526803190927
    },
    {
      "latitude": 55.95192719285057,
      "longitude": -3.1964381747239186,
      "bearing": 2.9670597283903604
    },
    {
      "latitude": 55.951925144093416,
      "longitude": -3.19648,
      "bearing": 3.141592653589793
    },
    {
      "latitude": 55.95192719285057,
      "longitude": -3.196521825276082,
      "bearing": 3.3161255787892263
    },
    {
      "latitude": 55.951933276872246,
      "longitude": -3.1965623797252603,
      "bearing": 3.490658503988659
    },
    {
      "latitude": 55.95194321130033,
      "longitude": -3.196600431132502,
      "bearing": 3.6651914291880923
    },
    {
      "latitude": 55.95195669428511,
      "longitude": -3.1966348233335022,
      "bearing": 3.839724354387525
    },
    {
      "latitude": 55.95197331615633,
      "longitude": -3.1966645113431342,
      "bearing": 4.014257279586958
    },
    {
      "latitude": 55.951992571870555,
      "longitude": -3.1966885931062468,
      "bearing": 4.1887902047863905
    },
    {
      "latitude": 55.95201387635612,
      "longitude": -3.196706336906159,
      "bearing": 4.363323129985824
    },
    {
      "latitude": 55.95203658228979,
      "longitude": -3.1967172035980393,
      "bearing": 4.537856055185257
    },
    {
      "latitude": 55.95205999976514,
      "longitude": -3.1967208629915693,
      "bearing": 4.71238898038469
    },
    {
      "latitude": 55.95208341725465,
      "longitude": -3.1967172038849836,
      "bearing": 4.886921905584122
    },
    {
      "latitude": 55.95210612322911,
      "longitude": -3.1967063374454385,
      "bearing": 5.061454830783556
    },
    {
      "latitude": 55.95212742777716,
      "longitude": -3.1966885938328167,
      "bearing": 5.235987755982989
    },
    {
      "latitude": 55.95214668356804,
      "longitude": -3.196664512169358,
      "bearing": 5.410520681182422
    },
    {
      "latitude": 55.95216330552083,
      "longitude": -3.1966348241597267,
      "bearing": 5.585053606381854
    },
    {
      "latitude": 55.95217678858224,
      "longitude": -3.1966004318590713,
      "bearing": 5.759586531581287
    },
    {
      "latitude": 55.95218672307282,
      "longitude": -3.1965623802645395,
      "bearing": 5.934119456780721
    },
    {
      "latitude": 55.952192807135276,
      "longitude": -3.196521825563027,
      "bearing": 6.1086523819801535
    }
  ]
}

Is out of radius

A helper function to determine if something is out of radius. This is currently straight line.

from gapmap import is_out_of_radius

## Input tuple or dict (55.95206, -3.19648) or object with latitude and longitude in the root { "latitude: ..., "longitude": ....}
## is_out_of_radius(pointA, pointB, radius) - Radius is in miles
radius = is_out_of_radius((55.95206, -3.19648), (55.86515, -4.25763), 40)

This will return

{
  "distance": {
    "miles": 41.67,
    "km": 67.07,
    "meters": 67065.32,
    "yards": 73343.5
  },
  "out_of_radius": false
}

Airport finder

A helper function to find airports in a given area

from gapmap import find_airports_near_position

airports = find_airports_near_position(55.95206, -3.19648, radius=70)

This will return

[
  {
    "id": "EGPF",
    "iata": "GLA",
    "icao": "EGPF",
    "name": "Glasgow International Airport",
    "elevation": 26,
    "timezone": "Europe/London",
    "distance_from_point": 48,
    "coords": {
      "latitude": 55.8718986511,
      "longitude": -4.4330601692
    },
    "country": "GB",
    "city": "Glasgow",
    "subdomain": "Scotland"
  },
  {
    "id": "EGPH",
    "iata": "EDI",
    "icao": "EGPH",
    "name": "Edinburgh Airport",
    "elevation": 135,
    "timezone": "Europe/London",
    "distance_from_point": 7,
    "coords": {
      "latitude": 55.9500007629,
      "longitude": -3.3724999428
    },
    "country": "GB",
    "city": "Edinburgh",
    "subdomain": "Scotland"
  },
  {
    "id": "EGPN",
    "iata": "DND",
    "icao": "EGPN",
    "name": "Dundee Airport",
    "elevation": 17,
    "timezone": "Europe/London",
    "distance_from_point": 35,
    "coords": {
      "latitude": 56.4524993896,
      "longitude": -3.0258300304
    },
    "country": "GB",
    "city": "Dundee",
    "subdomain": "Scotland"
  },
  {
    "id": "EGPT",
    "iata": "PSL",
    "icao": "EGPT",
    "name": "Perth/Scone Airport",
    "elevation": 397,
    "timezone": "Europe/London",
    "distance_from_point": 34,
    "coords": {
      "latitude": 56.439201355,
      "longitude": -3.3722200394
    },
    "country": "GB",
    "city": "Perth",
    "subdomain": "Scotland"
  },
  {
    "id": "EGQL",
    "iata": "ADX",
    "icao": "EGQL",
    "name": "RAF Leuchars",
    "elevation": 38,
    "timezone": "Europe/London",
    "distance_from_point": 32,
    "coords": {
      "latitude": 56.3728981018,
      "longitude": -2.8684399128
    },
    "country": "GB",
    "city": "St. Andrews",
    "subdomain": "Scotland"
  }
]

Euclidean Distance

This can simply be described as stright line distance or as the crow flys. This will not be accurate in terms of finding ranges where there is a route to be adhered to. Its more of an indication rather than guidance. But can help build a picture between points. For example you could levy a percentage of overage to be applied that could guestimate that an area is out of range. However this is exponentially bad when the direct line distance is great. It might be good for something within 20 miles but not at 100 miles. A great starting resource would be to read Euclidean Distance Formula - CUEMATH

Purpose

The purpose of this library is to grow it into a trusted framework of getting real world distance finding for land, sea and air using real world restrictions. The ability to create pathing in a unified form to work with the likes of Google Maps and Mapbox

End Goal

To create a machine/ai learned process that predict routing, pathing and distance. But got to start somewhere