11 |
12 | ## API Endpoints
13 |
14 | There are currently two endpoints exposed:
15 | + `http://road-network-api.herokuapp.com/intersections` returns a JSON array of `intersections`.
16 | + `http://road-network-api.herokuapp.com/road_edges` returns a JSON array of `road_edges`.
17 |
18 | **Note that each of the above endpoints takes one parameter, an integer `$offset`, which corresponds to SQL's OFFSET command. This is due to the fact that each call returns a maximum of 5,000 rows for performance reasons.**
19 |
20 | Example using jQuery's [$.ajax method](http://api.jquery.com/jquery.ajax/):
21 |
22 | ````javascript
23 | $.ajax({
24 | url: 'http://road-network-api.herokuapp.com/intersections',
25 | data: {
26 | '$offset': 5000
27 | }
28 | })
29 |
30 | // Returns:
31 | // [
32 | // {
33 | // "id": 5001,
34 | // "latitude": "37.727738",
35 | // "longitude": "-122.463601"
36 | // },
37 | // {
38 | // "id": 5002,
39 | // "latitude": "37.728234",
40 | // "longitude": "-122.463943"
41 | // },
42 | // {
43 | // "id": 5003,
44 | // "latitude": "37.709892",
45 | // "longitude": "-122.456826"
46 | // } ...
47 | // ]
48 | ````
49 |
50 | ## Constructing the Road Network
51 |
52 | The logic that constructs these road networks is based on a fundamental principle: that any two intersecting roads will share at least one exact geographic coordinate. Open Street Maps abides by [this principle](http://wiki.openstreetmap.org/wiki/Node#Nodes_on_Ways). Therefore, intersections may be extracted from a city's road system by finding the coordinates that appear more than once (i.e. the point is shared by two different roads).
53 |
54 | ````ruby
55 | # Finding intersections in San Francisco, from an Open Street Maps GeoJSON file
56 | file = File.read('san-francisco_california_roads.geojson')
57 | roads = JSON.parse(file)['features']
58 |
59 | # Initialize hash to count how many times each coordinate appears, with a default value of 0 for each coordinate
60 | coord_frequencies = Hash.new { |hash, key| hash[key] = 0 }
61 |
62 | roads.each do |road|
63 | road['geometry']['coordinates'].each do |coord|
64 | coord_frequencies[coord.to_s] += 1
65 | end
66 |
67 | # Add 1 to start point and end point of each road, so that they will be counted as intersections
68 | road_start = road['geometry']['coordinates'].first
69 | road_end = road['geometry']['coordinates'].last
70 | [road_start, road_end].each { |coord| coord_frequencies[coord.to_s] += 1 }
71 | end
72 |
73 | # Finally, extract all coordinates that appeared more than once
74 | intersections = coord_frequencies.select { |_, frequency| frequency > 1 }.keys
75 | ````
76 |
77 | ### Connecting Adjacent Intersections
78 |
79 | Two intersections should be connected if and only if the following two conditions are met:
80 | 1. They share the same road.
81 | 2. There are no other intersections along that road between them. Only intersections that are immediately adjacent to one another should be connected.
82 |
83 | In order to connect appropriate intersections, iterate over each road's list of coordinates and check whether that coordinate is an intersection. If it is, then connect it to the **previous** intersection that you found on that road.
84 |
85 | ````ruby
86 | # Example using Open Street Maps GeoJSON file
87 | file = File.read('san-francisco_california_roads.geojson')
88 | roads = JSON.parse(file)['features']
89 |
90 | roads.each do |road|
91 | prev_intersection = nil
92 | road['geometry']['coordinates'].each do |longitude, latitude|
93 | # A separate is_intersection? helper method was implemented to deal with nuanced comparisons of BigDecimal types
94 | if is_intersection?(latitude, longitude)
95 | this_intersection = Intersection.where(latitude: latitude, longitude: longitude).first
96 | # Special condition in the case that the first coordinate on the road is an intersection, i.e. there is not yet any prev_intersection
97 | if prev_intersection
98 | RoadEdge.create!(
99 | intersection1_id: prev_intersection.id,
100 | intersection2_id: this_intersection.id,
101 | street_name: road['properties']['name']
102 | )
103 | end
104 | # Save this intersections as the new previous intersection
105 | prev_intersection = this_intersection
106 | end
107 | end
108 | end
109 | ````
110 |
111 | ## Database Schema
112 |
113 | The [database](./db/schema.rb) consists of three tables: `intersections`, `road_edges`, and `road_points`. The schema for each table is structured as follows:
114 |
115 | ````ruby
116 | # Table name: intersections
117 | # =========================
118 | # id :integer not null, primary key
119 | # latitude :decimal(10, 6) not null
120 | # longitude :decimal(10, 6) not null
121 |
122 | # Table name: road_edges
123 | # =========================
124 | # id :integer not null, primary key
125 | # intersection1_id :integer not null, foreign key
126 | # intersection2_id :integer not null, foreign key
127 | # street_name :string
128 |
129 | # Table name: road_points
130 | # =========================
131 | # id :integer not null, primary key
132 | # latitude :decimal(10, 6) not null
133 | # longitude :decimal(10, 6) not null
134 | # road_edge_id :integer not null, foreign key
135 | ````
136 |
--------------------------------------------------------------------------------
/Rakefile:
--------------------------------------------------------------------------------
1 | # Add your own tasks in files placed in lib/tasks ending in .rake,
2 | # for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
3 |
4 | require File.expand_path('../config/application', __FILE__)
5 |
6 | Rails.application.load_tasks
7 |
--------------------------------------------------------------------------------
/app/assets/images/.keep:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/djfletcher/RoadNetworkAPI/0d3ae893bef422f19d22999f1c54a5a7f8c50482/app/assets/images/.keep
--------------------------------------------------------------------------------
/app/assets/images/Grid.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/djfletcher/RoadNetworkAPI/0d3ae893bef422f19d22999f1c54a5a7f8c50482/app/assets/images/Grid.png
--------------------------------------------------------------------------------
/app/assets/images/Mid-Range-View.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/djfletcher/RoadNetworkAPI/0d3ae893bef422f19d22999f1c54a5a7f8c50482/app/assets/images/Mid-Range-View.png
--------------------------------------------------------------------------------
/app/assets/images/San-Francisco-Full.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/djfletcher/RoadNetworkAPI/0d3ae893bef422f19d22999f1c54a5a7f8c50482/app/assets/images/San-Francisco-Full.png
--------------------------------------------------------------------------------
/app/assets/images/Union-Square.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/djfletcher/RoadNetworkAPI/0d3ae893bef422f19d22999f1c54a5a7f8c50482/app/assets/images/Union-Square.png
--------------------------------------------------------------------------------
/app/assets/javascripts/application.js:
--------------------------------------------------------------------------------
1 | // This is a manifest file that'll be compiled into application.js, which will include all the files
2 | // listed below.
3 | //
4 | // Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
5 | // or any plugin's vendor/assets/javascripts directory can be referenced here using a relative path.
6 | //
7 | // It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
8 | // compiled file.
9 | //
10 | // Read Sprockets README (https://github.com/rails/sprockets#sprockets-directives) for details
11 | // about supported directives.
12 | //
13 | //= require jquery
14 | //= require jquery_ujs
15 | //= require_tree .
16 |
--------------------------------------------------------------------------------
/app/assets/javascripts/intersections.coffee:
--------------------------------------------------------------------------------
1 | # Place all the behaviors and hooks related to the matching controller here.
2 | # All this logic will automatically be available in application.js.
3 | # You can use CoffeeScript in this file: http://coffeescript.org/
4 |
--------------------------------------------------------------------------------
/app/assets/javascripts/pathless.coffee:
--------------------------------------------------------------------------------
1 | # Place all the behaviors and hooks related to the matching controller here.
2 | # All this logic will automatically be available in application.js.
3 | # You can use CoffeeScript in this file: http://coffeescript.org/
4 |
--------------------------------------------------------------------------------
/app/assets/javascripts/road_edges.coffee:
--------------------------------------------------------------------------------
1 | # Place all the behaviors and hooks related to the matching controller here.
2 | # All this logic will automatically be available in application.js.
3 | # You can use CoffeeScript in this file: http://coffeescript.org/
4 |
--------------------------------------------------------------------------------
/app/assets/stylesheets/application.css:
--------------------------------------------------------------------------------
1 | /*
2 | * This is a manifest file that'll be compiled into application.css, which will include all the files
3 | * listed below.
4 | *
5 | * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
6 | * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
7 | *
8 | * You're free to add application-wide styles to this file and they'll appear at the bottom of the
9 | * compiled file so the styles you add here take precedence over styles defined in any styles
10 | * defined in the other CSS/SCSS files in this directory. It is generally better to create a new
11 | * file per style scope.
12 | *
13 | *= require_tree .
14 | *= require_self
15 | */
16 |
--------------------------------------------------------------------------------
/app/assets/stylesheets/intersections.scss:
--------------------------------------------------------------------------------
1 | // Place all the styles related to the Intersections controller here.
2 | // They will automatically be included in application.css.
3 | // You can use Sass (SCSS) here: http://sass-lang.com/
4 |
--------------------------------------------------------------------------------
/app/assets/stylesheets/pathless.scss:
--------------------------------------------------------------------------------
1 | // Place all the styles related to the Pathless controller here.
2 | // They will automatically be included in application.css.
3 | // You can use Sass (SCSS) here: http://sass-lang.com/
4 |
--------------------------------------------------------------------------------
/app/assets/stylesheets/road_edges.scss:
--------------------------------------------------------------------------------
1 | // Place all the styles related to the road_edges controller here.
2 | // They will automatically be included in application.css.
3 | // You can use Sass (SCSS) here: http://sass-lang.com/
4 |
--------------------------------------------------------------------------------
/app/controllers/application_controller.rb:
--------------------------------------------------------------------------------
1 | class ApplicationController < ActionController::Base
2 | # Prevent CSRF attacks by raising an exception.
3 | # For APIs, you may want to use :null_session instead.
4 | protect_from_forgery with: :exception
5 | end
6 |
--------------------------------------------------------------------------------
/app/controllers/concerns/.keep:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/djfletcher/RoadNetworkAPI/0d3ae893bef422f19d22999f1c54a5a7f8c50482/app/controllers/concerns/.keep
--------------------------------------------------------------------------------
/app/controllers/intersections_controller.rb:
--------------------------------------------------------------------------------
1 | class IntersectionsController < ApplicationController
2 |
3 | def index
4 | @intersections = Intersection.offsetted(params[:$offset].to_i)
5 | render json: @intersections
6 | end
7 |
8 | end
9 |
--------------------------------------------------------------------------------
/app/controllers/pathless_controller.rb:
--------------------------------------------------------------------------------
1 | class PathlessController < ApplicationController
2 |
3 | def index
4 | msg = {
5 | status: 303,
6 | message: "Please try any of the following urls: 'http://road-network-api.herokuapp.com/intersections', 'http://road-network-api.herokuapp.com/road_edges'"
7 | }
8 | render json: msg
9 | end
10 |
11 | end
12 |
--------------------------------------------------------------------------------
/app/controllers/road_edges_controller.rb:
--------------------------------------------------------------------------------
1 | class RoadEdgesController < ApplicationController
2 |
3 | def index
4 | @road_edges = RoadEdge.offsetted(params[:$offset].to_i)
5 | render json: @road_edges
6 | end
7 |
8 | end
9 |
--------------------------------------------------------------------------------
/app/helpers/application_helper.rb:
--------------------------------------------------------------------------------
1 | module ApplicationHelper
2 | end
3 |
--------------------------------------------------------------------------------
/app/helpers/intersections_helper.rb:
--------------------------------------------------------------------------------
1 | module IntersectionsHelper
2 | end
3 |
--------------------------------------------------------------------------------
/app/helpers/pathless_helper.rb:
--------------------------------------------------------------------------------
1 | module PathlessHelper
2 | end
3 |
--------------------------------------------------------------------------------
/app/helpers/road_edges_helper.rb:
--------------------------------------------------------------------------------
1 | module RoadEdgesHelper
2 | end
3 |
--------------------------------------------------------------------------------
/app/mailers/.keep:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/djfletcher/RoadNetworkAPI/0d3ae893bef422f19d22999f1c54a5a7f8c50482/app/mailers/.keep
--------------------------------------------------------------------------------
/app/models/.keep:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/djfletcher/RoadNetworkAPI/0d3ae893bef422f19d22999f1c54a5a7f8c50482/app/models/.keep
--------------------------------------------------------------------------------
/app/models/concerns/.keep:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/djfletcher/RoadNetworkAPI/0d3ae893bef422f19d22999f1c54a5a7f8c50482/app/models/concerns/.keep
--------------------------------------------------------------------------------
/app/models/intersection.rb:
--------------------------------------------------------------------------------
1 | # == Schema Information
2 | #
3 | # Table name: intersections
4 | #
5 | # id :integer not null, primary key
6 | # latitude :decimal(10, 6) not null
7 | # longitude :decimal(10, 6) not null
8 | #
9 |
10 | class Intersection < ActiveRecord::Base
11 |
12 | has_many :road_edges1,
13 | class_name: :RoadEdge,
14 | foreign_key: :intersection1_id,
15 | primary_key: :id
16 |
17 | has_many :road_edges2,
18 | class_name: :RoadEdge,
19 | foreign_key: :intersection2_id,
20 | primary_key: :id
21 |
22 | def self.within_box(northeast, southwest)
23 | Intersection.where(
24 | latitude: southwest[:latitude]..northeast[:latitude],
25 | longitude: southwest[:longitude]..northeast[:longitude]
26 | )
27 | end
28 |
29 | def self.offsetted(num_rows)
30 | Intersection.offset(num_rows).limit(5000)
31 | end
32 |
33 | # simple breadth first search
34 | def self.path(from_id, to_id)
35 | # predecessors is a hash where each key is an intersection that points
36 | # to the intersection immediately before it in the search
37 | predecessors = {}
38 | q = Queue.new
39 | q << Intersection.find_by_id(from_id)
40 | until q.empty?
41 | intersection = q.deq
42 | # need to write helper method to extract path from predecessors hash
43 | intersection.neighboring_intersections.each do |neighbor|
44 | # check whether this neighbor has already been visited
45 | if !predecessors[neighbor]
46 | predecessors[neighbor] = intersection
47 | return Intersection.extract_path_as_array(neighbor, predecessors) if neighbor.id == to_id
48 | q << neighbor
49 | end
50 | end
51 | end
52 |
53 | raise "No path from intersection with id #{from_id} to intersection with id #{to_id}"
54 | end
55 |
56 | def road_edges
57 | self.road_edges1 + self.road_edges2
58 | end
59 |
60 | def neighboring_intersections
61 | road_edges.map(&:intersections).flatten.uniq(&:id)
62 | end
63 |
64 | def neighbor(road_edge)
65 | return self if road_edge.circular?
66 | if road_edge.intersection1_id == self.id
67 | Intersection.find_by_id(road_edge.intersection2_id)
68 | elsif road_edge.intersection2_id == self.id
69 | Intersection.find_by_id(road_edge.intersection1_id)
70 | else
71 | raise "Intersection with id #{self.id} is not part of RoadEdge with id #{road_edge.id}"
72 | end
73 | end
74 |
75 | def to_coordinate_hash
76 | { longitude: self.longitude.to_f, latitude: self.latitude.to_f }
77 | end
78 |
79 | private
80 | def self.extract_path_as_array(target, predecessors)
81 | path = [target]
82 | current_intersection = target
83 | while predecessors[current_intersection]
84 | # debugger
85 | path.unshift(predecessors[current_intersection])
86 | current_intersection = predecessors[current_intersection]
87 | end
88 |
89 | path
90 | end
91 |
92 | end
93 |
--------------------------------------------------------------------------------
/app/models/road_edge.rb:
--------------------------------------------------------------------------------
1 | # == Schema Information
2 | #
3 | # Table name: road_edges
4 | #
5 | # id :integer not null, primary key
6 | # intersection1_id :integer not null
7 | # intersection2_id :integer not null
8 | # street_name :string
9 | # length :float
10 | #
11 |
12 | class RoadEdge < ActiveRecord::Base
13 |
14 | has_many :road_points
15 |
16 | belongs_to :intersection1,
17 | class_name: :Intersection,
18 | foreign_key: :intersection1_id,
19 | primary_key: :id
20 |
21 | belongs_to :intersection2,
22 | class_name: :Intersection,
23 | foreign_key: :intersection2_id,
24 | primary_key: :id
25 |
26 |
27 | def self.offsetted(num_rows)
28 | RoadEdge.offset(num_rows).limit(5000)
29 | end
30 |
31 | def self.offsetted_intersection_pairs(num_rows)
32 | all_intersections = Intersection.all.index_by(&:id)
33 | RoadEdge.offsetted(num_rows).map do |edge|
34 | [all_intersections[edge.intersection1_id], all_intersections[edge.intersection2_id]]
35 | end
36 | end
37 |
38 | def self.offsetted_intersection_pairs_by_id(num_rows)
39 | RoadEdge.offsetted(num_rows).map(&:intersection_ids)
40 | end
41 |
42 | def self.edge_between_intersections(intersection1, intersection2)
43 | # This method assumes both coordinates are passed in as ActiveRecord relation objects
44 | id1 = intersection1.id
45 | id2 = intersection2.id
46 | intersection1.road_edges.each do |edge|
47 | if edge.intersection1_id == id1 && edge.intersection2_id == id2 ||
48 | edge.intersection1_id == id2 && edge.intersection2_id == id1
49 | return edge
50 | end
51 | end
52 |
53 | nil
54 | end
55 |
56 | def self.edge_between_intersection_coordinates(raw_coord1, raw_coord2)
57 | # This method assumes that both coordinates are passed in as hashes, not ActiveRecord relation objects
58 | parsed_coord1 = RoadPoint.to_big_decimal(raw_coord1)
59 | parsed_coord2 = RoadPoint.to_big_decimal(raw_coord2)
60 |
61 | intersection1 = Intersection.where(
62 | latitude: parsed_coord1[:latitude],
63 | longitude: parsed_coord1[:longitude]
64 | ).first
65 | raise "[#{raw_coord1[:longitude]},#{raw_coord1[:latitude]}] is not an intersection" if intersection1.nil?
66 |
67 | intersection2 = Intersection.where(
68 | latitude: parsed_coord2[:latitude],
69 | longitude: parsed_coord2[:longitude]
70 | ).first
71 | raise "[#{raw_coord2[:longitude]},#{raw_coord2[:latitude]}] is not an intersection" if intersection2.nil?
72 |
73 | RoadEdge.edge_between_intersections(intersection1, intersection2)
74 | end
75 |
76 | def intersections
77 | [self.intersection1, self.intersection2]
78 | end
79 |
80 | def intersection_ids
81 | [self.intersection1_id, self.intersection2_id]
82 | end
83 |
84 | def circular?
85 | # A circular road edge has the same intersection at both ends
86 | self.intersection1_id == self.intersection2_id
87 | end
88 |
89 | end
90 |
--------------------------------------------------------------------------------
/app/models/road_point.rb:
--------------------------------------------------------------------------------
1 | # == Schema Information
2 | #
3 | # Table name: road_points
4 | #
5 | # id :integer not null, primary key
6 | # latitude :decimal(10, 6) not null
7 | # longitude :decimal(10, 6) not null
8 | # road_edge_id :integer not null
9 | #
10 |
11 | class RoadPoint < ActiveRecord::Base
12 |
13 | belongs_to :road_edge
14 |
15 | def self.to_big_decimal(coordinate)
16 | bd_lat = BigDecimal.new(coordinate[:latitude], 10).truncate(6)
17 | bd_lng = BigDecimal.new(coordinate[:longitude], 10).truncate(6)
18 | { latitude: bd_lat, longitude: bd_lng }
19 | end
20 |
21 | def intersections
22 | self.road_edge.intersections
23 | end
24 |
25 | end
26 |
--------------------------------------------------------------------------------
/app/views/layouts/application.html.erb:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | You may have mistyped the address or the page may have moved.
63 |If you are the application owner check the logs for more information.
65 |Maybe you tried to change something you didn't have access to.
63 |If you are the application owner check the logs for more information.
65 |If you are the application owner check the logs for more information.
64 |