Diff for "EggFormats" - The PEAK Developers' Center

Diff for "EggFormats"

UserPreferences

The PEAK Developers' Center

FrontPage

RecentChanges

TitleIndex

WordIndex

SiteNavigation

HelpContents

Ignore changes in the amount of whitespace

Differences between version dated 2009-11-06 20:32:30 and 2009-11-06 20:49:19

Deletions are marked like this.

Additions are marked like this.

Support browsers that contribute to open source, try Firefox or Google Chrome.

googletransitdatafeed

GoogleTransitDataFeed

Project Home

Downloads

Wiki

Issues

Source

Checkout | Browse | Changes |

r977 r978›

Source path: svn/ wiki/ files/ FeedSpecHistory/ transit_feed_specification-20080807.htm

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html>

<head>

<title>Google Transit Feed Specification - Google Transit Feed Specification - Google Code</title>

var _tocPath_ = '/html/transit/spec/_toc.ezt';

//--></script>

</head>

<a href="#gc-pagecontent-anchor">Skip to page content</a>

<a href="#gc-toc-anchor">Skip to main navigation</a>

</div>

<a class="dropdown" href="/">English</a>

|

<a href="/more/#products-products-android">Site Directory</a>

</div>

</a></div>

</noscript>

<tbody>

<tr>

</td>

</td>

</tr>

<tr>

<td colspan="2" class="greytext">e.g. "ajax apis" or "open source"</td>

</tr>

</tbody>

</table>

</form>

</div>

</div>

</div>

<h1>Google Transit Feed Specification</h1>

</ul>

</div>

<ul>

<li>

<h1>For Riders</h1>

<ul>

<li><a href="http://www.google.com/transit">Google Transit Trip Planner</a></li>

<li><a href="http://maps.google.com/support/bin/topic.py?topic=12356">About Public Transit in Google Maps</a></li>

<li><a href="http://groups.google.com/group/googletransit/">Google Transit Group</a></li>

<li><a href="http://maps.google.com">Google Maps</a></li>

<li><a href="http://earth.google.com/">Google Earth </a>

</li>

</ul>

</li>

<li><h1>For Feed Developers</h1>

<ul>

<li><a href="./transit_feed_specification.html" id="transitfeedspec_lnk">Google Transit Feed Specification</a></li>

<li><a href="http://code.google.com/p/googletransitdatafeed/wiki/FeedSpecHistory">Revision History</a>

<li><a href="http://code.google.com/p/googletransitdatafeed/">Open Source GTFS Feed Tools </a></li>

<li><a href="http://spreadsheets.google.com/pub?key=puMHBiWYEbXT0UxQGLDpuBA&gid=11">Example Feed </a></li>

<li><a href="http://groups.google.com/group/gtfs-changes/">GTFS Changes Group</a></li>

</ul>

</li>

<li><h1>Public GTFS Feeds </h1>

<ul>

<li><a href="http://developer.trimet.org/schedule/GTFS/">Portland TriMet</a></li>

<li><a href="http://www.dart.org/transitdata/">Dallas DART</a></li>

<li><a href="http://www.octa.net/google/">Orange County OCTA</a></li>

<li><a href="http://iportal.sacrt.com/GTFS/SRTD/">Sacramento RT</a></li>

<li><a href="http://www.capmetro.org/gisdata/google_transit.zip">Austin Capital Metro</a></li>

<li><a href="http://www.transitinfosolutions.com/transit_feeds/humboldt/">Humboldt County Transit Authority</a></li>

<li><a href="http://code.google.com/p/googletransitdatafeed/wiki/PublicFeeds">More Public Feeds...</a></li>

</ul>

</li>

</ul>

<a class="hidden" href="#gc-topnav-anchor">More Google Transit Feed Specification resource links</a>

</div>

<h1 class="page_title">Google Transit Feed Specification</h1>

Revised August 7, 2008

The transit trip planning feature in Google Maps enables users to create efficient travel itineraries using public transportation schedules. This document explains how you can provide public transportation schedules to Google so that those schedules can be incorporated into Google Maps and other Google applications that show geographic data. This document explains the types of files that comprise a transit feed and defines the fields used in all of those files.

<h1>Table of Contents</h1>

<a class="hidden" href="#transitFeedSubmit">Skip over contents</a>

<li><a href="#transitFeedSubmit">Submitting a Transit Feed to Google </a></li>

<li><a href="#transitTermDefinitions">Term Definitions</a></li>

<li><a href="#transitFeedFiles">Requirements </a>

<li><a href="#transitFileRequirements">File Requirements</a></li>

<li><a href="#transitTestingFeeds">Testing Your Feeds</a></li>

<li><a href="#transitUpdatingFeeds">Updating Your Feeds</a></li>

<li><a href="#transitPostingFeeds">Requirements for Posting Your Feeds to Google Maps </a></li>

</ol></li>

<li><a href="#Google_Transit_Feed_Field_Definitions"> Field Definitions</a>

<li><a href="#agency_txt___Field_Definitions">agency.txt</a></li>

<li><a href="#stops_txt___Field_Definitions">stops.txt</a></li>

<li><a href="#routes_txt___Field_Definitions">routes.txt</a></li>

<li><a href="#trips_txt___Field_Definitions">trips.txt</a></li>

<li><a href="#stop_times_txt___Field_Definitions">stop_times.txt</a></li>

<li><a href="#calendar_txt___Field_Definitions">calendar.txt</a></li>

<li><a href="#calendar_dates_txt___Field_Definitions">calendar_dates.txt</a></li>

<li><a href="#fare_attributes_txt___Field_Definitions">fare_attributes.txt</a></li>

<li><a href="#fare_rules_txt___Field_Definitions">fare_rules.txt</a></li>

<li><a href="#shapes_txt___Field_Definitions">shapes.txt</a></li>

<li><a href="#frequencies_txt___Field_Definitions">frequencies.txt</a></li>

<li><a href="#transfers_txt___Field_Definitions">transfers.txt</a></li>

</ol>

</li>

<li><a href="#transitFeedSampleData">Sample Data</a></li>

<li><a href="#transitAgencyExample">Demo Transit Agency Example </a></li>

<li><a href="#transitScreenshots">Displaying Transit Data to Maps Users</a></li>

</ol>

</div>

<h1><a name="transitFeedSubmit" id="transitFeedSubmit"></a>Submitting a Transit Feed to Google </h1>

If you're at a public agency that oversees public transportation for your city and would like your data to be included, these are the steps in submitting a transit feed to Google:

<ol>

<li>The agency prepares transit data as a zip file in the Google Transit Feed Spec (GTFS) format.</li>

<li>The agency <a href="#transitTestingFeeds">tests</a> the GTFS zip file to ensure that it is valid, and that the schedules are accurate. </li>

<li>The agency hosts the transit data zip files on a standard web server and sends an e-mail to <a href="mailto:maps-transit-content@google.com">maps-transit-content@google.com</a>. The e-mail must contain a link to the location of the transit data zip file and the Google account IDs that should have access to the preview. To create a free Google account ID, click here: <a href="https://www.google.com/accounts/NewAccount" title="Go to create an account">https://www.google.com/accounts/NewAccount</a>.</li>

<li>Google sends the agency a link to an online data use agreement. </li>

<li>Google fetches the validated transit files from the agency's web server.</li>

<li>Google builds a preview of the agency's data in Google Maps. </li>

<li>The agency reviews the preview data and iterates with Google to resolve any issues.</li>

<li>Google and the agency agree to go live with the transit data, and decide how often Google will check the transit agency's web server for feed updates. </li>

<li>Transit data from the agency goes live on google.com.</li>

<li>Google fetches new files from the agency's web server on a regular basis, and updates Google Maps and other geographic applications at Google with the latest feed. </li>

</ol>

<h1><a name="transitTermDefinitions" id="transitTermDefinitions"></a>Term Definitions</h1>

This section defines terms that are used throughout this document.

<ul>

<li>Field required - The field column must be included in your feed, and a value must be provided for each record. Some required fields permit an empty string as a value. To enter an empty string, just omit any text between the commas for that field. Note that 0 is interpreted as "a string of value 0", and is not an empty string. Please see the field definition for details.</li>

<li> Field optional - The field column may be omitted from your feed. If you choose to include an optional column, each record in your feed must have a value for that column. You may include an empty string as a value for records that do not have values for the column. Some optional fields permit an empty string as a value. To enter an empty string, just omit any text between the commas for that field. Note that 0 is interpreted as "a string of value 0", and is not an empty string. </li>

<li> Dataset unique - The field contains a value that maps to a single distinct entity within the column. For example, if a route is assigned the ID 1A, then no other route may use that route ID. However, you may assign the ID 1A to a location because locations are a different type of entity than routes.</li>

</ul>

<h1><a name="transitFeedFiles" id="transitFeedFiles"></a>Requirements </h1>

Google accepts transit feeds that contain the following files:

<ul>

<li> <a href="#agency_txt___Field_Definitions">agency.txt</a> - Required. This file contains information about one or more transit agencies that provide the data in this feed.</li>

<li> <a href="#stops_txt___Field_Definitions">stops.txt</a> - Required. This file contains information about individual locations where vehicles pick up or drop off passengers.</li>

<li> <a href="#routes_txt___Field_Definitions">routes.txt</a> - Required. This file contains information about a transit organization's routes. A route is a group of trips that are displayed to riders as a single service.</li>

<li> <a href="#trips_txt___Field_Definitions">trips.txt</a> - Required. This file lists all trips and their routes. A trip is a sequence of two or more stops that occurs at specific time.</li>

<li> <a href="#stop_times_txt___Field_Definitions">stop_times.txt</a> - Required. This file lists the times that a vehicle arrives at and departs from individual stops for each trip.</li>

<li> <a href="#calendar_txt___Field_Definitions">calendar.txt</a> - Required. This file defines dates for service IDs using a weekly schedule. Specify when service starts and ends, as well as days of the week where service is available. </li>

<li> <a href="#calendar_dates_txt___Field_Definitions">calendar_dates.txt</a> - Optional. This file lists exceptions for the service IDs defined in the calendar.txt file. If calendar_dates.txt includes ALL dates of service, this file may be specified instead of calendar.txt. </li>

<li><a href="#fare_attributes_txt___Field_Definitions">fare_attributes.txt</a> - Optional. This file defines fare information for a transit organization's routes. </li>

<li><a href="#fare_rules_txt___Field_Definitions">fare_rules.txt</a> - Optional. This file defines the rules for applying fare information for a transit organization's routes.</li>

<li> <a href="#shapes_txt___Field_Definitions">shapes.txt</a> - Optional. This file defines the rules for drawing lines on a map to represent a transit organization's routes.</li>

<li> <a href="#frequencies_txt___Field_Definitions">frequencies.txt</a> - Optional. This file defines the headway (time between trips) for routes with variable frequency of service.</li>

<li> <a href="#transfers_txt___Field_Definitions">transfers.txt</a> - Optional. This file defines the rules for making connections at transfer points between routes. </li>

</ul>

<h2><a name="transitFileRequirements" id="transitFileRequirements"></a>File Requirements</h2>

The following requirements apply to the format and contents of your files:

<ul>

<li>

All files in a Google Transit Feed Spec (GTFS) feed must be saved as comma-delimited text. Remove any extra spaces between fields. </li>

<li>

The first line of your feeds must contain field names. Each subsection of the <a href="#Google_Transit_Feed_Field_Definitions"> Field Definitions</a> section corresponds to one of the files in a transit feed and lists the field names you may use in that file.</li>

<li>

All field names are case-sensitive.</li>

<li>

Field values may not contain tabs, carriage returns or new lines. </li>

<li>

Field values that contain quotation marks or commas must be enclosed within quotation marks. In addition, each quotation mark in the field value must be preceded with a quotation mark. This is consistent with the manner in which Microsoft Excel outputs comma-delimited (CSV) files. For more information on the CSV file format, see <a href="http://en.wikipedia.org/wiki/Comma-separated_values">http://en.wikipedia.org/wiki/Comma-separated_values</a>.

The following example demonstrates how a field value would appear in a comma-delimited file:

<ul>

<li>Original field value: <code>Contains "quotes", commas and text</code></li>

<li>Field value in CSV file:<code> "Contains ""quotes"", commas and text"</code></li>

</ul>

</li>

<li>Field values should not contain HTML tags, comments or escape sequences.</li>

<li>Files should be encoded in UTF-8 to support all Unicode characters.</li>

<li>Name your feed files using the following naming conventions:

<ul>

<li>agency.txt</li>

<li>stops.txt</li>

<li>routes.txt</li>

<li>trips.txt</li>

<li>stop_times.txt</li>

<li>calendar.txt</li>

<li>calendar_dates.txt</li>

<li>fare_rules.txt</li>

<li>fare_attributes.txt</li>

<li>shapes.txt</li>

<li>frequencies.txt</li>

<li>transfers.txt</li>

</ul>

</li>

<li>Zip the files in your feed. Name the zip file google_transit.zip. <a href="#transitPostingFeeds">Post</a> the zip file in a directory named YYYYMMDD, where YYYYMMDD is the earliest date of valid service included in any of the files. </li>

</ul>

<h2><a name="transitTestingFeeds" id="transitTestingFeeds"></a>Testing Your Feeds</h2>

Two Open Source tools are available for testing feeds in the GTFS format:

<ul>

<li>Use the <a href="http://code.google.com/p/googletransitdatafeed/wiki/FeedValidator">feedvalidator</a> tool to verify that your feed data file matches the specification defined in this document. </li>

<li>Use the <a href="http://code.google.com/p/googletransitdatafeed/wiki/ScheduleViewer">schedule_viewer</a> application to see your feed data represented on a map. This is not representative of how your data will look in other applications; it is a basic tool for testing. Examine routes and schedules to ensure that the data feed correctly represents your system. </li>

</ul>

Before requesting a preview of your feed in Google Transit, please use both these tools and correct any errors that you find. This helps Google to set up a preview as quickly as possible.

<h2><a name="transitUpdatingFeeds" id="transitUpdatingFeeds"></a>Updating Your Feeds</h2>

These guidelines apply to feed updates:

<ul><li> You may simultaneously post more than one zip file if each zip file contains all of the data for a unique date range. In other words, different zip files cannot contain data for overlapping service dates.

Note: As described in the previous section, each zip file that you post should reside in a different directory on your server.

</li>

<li>

When Google fetches a new file, the data in that file will overwrite all data previously stored for your agency. As a result, please ensure that your files provide complete data for a service date range. As noted in the previous section, you can provide multiple zip files as long as the files do not contain data for overlapping service dates. </li>

</ul>

<h2><a name="transitPostingFeeds" id="transitPostingFeeds"></a>Requirements for Posting Your Feeds to Google Maps </h2>

These requirements apply to the location of your feeds:

<ul>

<li>

You will need to provide the URL location of your feed. Google Maps can download feeds using either HTTP or HTTPS. You will also need to provide a login and password if they are needed to retrieve your feed.</li>

<li>

Your IT/Networking teams should know that Google Maps periodically fetches transit feed data from the location that you specify, so that they do not change file permissions for your feed or otherwise block or break the data fetching process.</li>

</ul>

<h1><a name="Google_Transit_Feed_Field_Definitions" id="Google_Transit_Feed_Field_Definitions"></a>Field Definitions</h1>

<h2 class="first""><a name="agency_txt___Field_Definitions" id="agency_txt___Field_Definitions"></a>agency.txt </h2>

<table>

<tr><th scope="col" abbr="field" width="15%">Field Name</th>

<th scope="col" abbr="details">Details</th>

</tr>

<tr>

<td scope="row" class="attr"><a name="agency_id_feed_data" id="agency_id_feed_data"></a>agency_id</td>

<td >Optional. The agency_id field is an ID that uniquely identifies a transit agency. A transit feed may represent data from more than one agency. The agency_id is dataset unique. This field is optional for transit feeds that only contain data for a single agency. </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="agency_name_feed_data" id="agency_name_feed_data"></a>agency_name</td>

<td >Required. The agency_name field contains the full name of the transit agency. Google Maps will display this name. </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="agency_url_feed_data" id="agency_url_feed_data"></a>agency_url</td>

<td >Required. The agency_url field contains the URL of the transit agency. The value must be a fully qualified URL that includes http:// or https://, and any special characters in the URL must be correctly escaped. See <a href="http://www.w3.org/Addressing/URL/4_URI_Recommentations.html">http://www.w3.org/Addressing/URL/4_URI_Recommentations.html</a> for a description of how to create fully qualified URL values.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="agency_timezone_feed_data" id="agency_timezone_feed_data"></a>agency_timezone</td>

<td >Required. The agency_timezone field contains the timezone where the transit agency is located. Timezone names never contain the space character but may contain an underscore. Please refer to <a href="http://en.wikipedia.org/wiki/List_of_tz_zones">http://en.wikipedia.org/wiki/List_of_tz_zones</a> for a list of valid values.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="agency_lang_feed_data" id="agency_lang_feed_data"></a>agency_lang</td>

<td >Optional. The agency_lang field contains a two-letter ISO 639-1 code for the primary language used by this transit agency. The language code is case-insensitive (both en and EN are accepted). This setting defines capitalization rules and other language-specific settings for all text contained in this transit agency's feed. Please refer to <a href="http://www.loc.gov/standards/iso639-2/php/code_list.php" title="the ISO 639-2 code list">http://www.loc.gov/standards/iso639-2/php/code_list.php</a> for a list of valid values.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="agency_phone_feed_data" id="agency_phone_feed_data"></a>agency_phone</td>

<td >Optional. The agency_phone field contains a single voice telephone number for the specified agency. This field is a string value that presents the telephone number as typical for the agency's service area. It can and should contain punctuation marks to group the digits of the number. Dialable text (for example, TriMet's "503-238-RIDE") is permitted, but the field must not contain any other descriptive text. </td>

</tr>

</table>

<h2><a name="stops_txt___Field_Definitions" id="stops_txt___Field_Definitions"></a>stops.txt </h2>

<table>

<tr><th scope="col" abbr="field" width="15%">Field Name</th>

<th scope="col" abbr="details">Details</th>

</tr>

<tr>

<td >Required. The stop_id field contains an ID that uniquely identifies a stop or station. Multiple routes may use the same stop. The stop_id is dataset unique.</td>

</tr>

<tr>

<td >Optional. The stop_code field contains short text or a number that uniquely identifies the stop for passengers. Stop codes are often used in phone-based transit information systems or printed on stop signage to make it easier for riders to get a stop schedule or real-time arrival information for a particular stop.

The stop_code field should only be used for stop codes that are displayed to passengers. For internal codes, use stop_id. This field should be left blank for stops without a code.</td>

</tr>

<tr>

<td >Required. The stop_name field contains the name of a stop or station. Please use a name that people will understand in the local and tourist vernacular. </td>

</tr>

<tr>

<td >Optional. The stop_desc field contains a description of a stop. Please provide useful, quality information. Do not simply duplicate the name of the stop.</td>

</tr>

<tr>

<td >Required. The stop_lat field contains the latitude of a stop or station. The field value must be a valid WGS 84 latitude.</td>

</tr>

<tr>

<td >Required. The stop_lon field contains the longitude of a stop or station. The field value must be a valid WGS 84 longitude value from -180 to 180.</td>

</tr>

<tr>

<td >Optional. The zone_id field defines the fare zone for a stop ID. Zone IDs are required if you want to provide fare information using <a href="#fare_rules_txt___Field_Definitions">fare_rules.txt</a>. If this stop ID represents a station, the zone ID is ignored. </td>

</tr>

<tr>

<td >Optional. The stop_url field contains the URL of a web page about a particular stop. This should be different from the agency_url and the route_url fields.

The value must be a fully qualified URL that includes http:// or https://, and any special characters in the URL must be correctly escaped. See <a href="http://www.w3.org/Addressing/URL/4_URI_Recommentations.html">http://www.w3.org/Addressing/URL/4_URI_Recommentations.html</a> for a description of how to create fully qualified URL values. </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="location_type_feed_data" id="location_type_feed_data"></a>location_type</td>

<td >Optional. The location_type field identifies whether this stop ID represents a stop or station. If no location type is specified, or the location_type is blank, stop IDs are treated as stops. Stations may have different properties from stops when they are represented on a map or used in trip planning.

The location type field can have the following values:

<li>0 or blank - Stop. A location where passengers board or disembark from a transit vehicle. </li>

<li>1 - Station. A physical structure or area that contains one or more stop. </li>

</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="parent_station_feed_data" id="parent_station_feed_data"></a>parent_station</td>

<td >Optional. For stops that are physically located inside stations, the parent_station field identifies the station associated with the stop. To use this field, stops.txt must also contain a row where this stop ID is assigned location type=1.

<th scope="col">This stop ID represents... </th>

<th scope="col">This entry's location type...</th>

<th scope="col">This entry's parent_station field contains...</th>

</tr>

<tr>

<td scope="row">A stop located inside a station.</td>

<td>0 or blank </td>

<td>The stop ID of the station where this stop is located.

The stop referenced by parent_station must have location_type=1.</td>

</tr>

<tr>

<td scope="row">A stop located outside a station. </td>

<td>0 or blank </td>

<td>A blank value. The parent_station field doesn't apply to this stop. </td>

</tr>

<tr>

<td scope="row">A station.</td>

<td>A blank value. Stations can't contain other stations. </td>

</tr>

</table>

</td>

</tr>

</table>

<h2><a name="routes_txt___Field_Definitions" id="routes_txt___Field_Definitions"></a>routes.txt </h2>

<table>

<tr><th scope="col" abbr="field" width="15%">Field Name</th>

<th scope="col" abbr="details">Details</th>

</tr>

<tr>

<td scope="row" class="attr"><a name="route_id_feed_data" id="route_id_feed_data"></a>route_id</td>

<td >Required. The route_id field contains an ID that uniquely identifies a route. The route_id is dataset unique.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="agency_name_ref_feed_data" id="agency_name_ref_feed_data"></a>agency_id</td>

<td >Optional. The agency_id field defines an agency for the specified route. This value is referenced from the <a href="#agency_txt___Field_Definitions">agency.txt</a> file. Use this field when you are providing data for routes from more than one agency. </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="route_short_name_feed_data" id="route_short_name_feed_data"></a>route_short_name</td>

<td >Required. The route_short_name contains the short name of a route. This will often be a short, abstract identifier like "32", "100X", or "Green" that riders use to identify a route, but which doesn't give any indication of what places the route serves. If the route does not have a short name, please specify a route_long_name and use an empty string as the value for this field.

See a Google Maps screenshot highlighting the <a href="#transitShortNameScreenshot">route_short_name</a>.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="route_long_name_feed_data" id="route_long_name_feed_data"></a>route_long_name</td>

<td >Required. The route_long_name contains the full name of a route. This name is generally more descriptive than the route_short_name and will often include the route's destination or stop. If the route does not have a long name, please specify a route_short_name and use an empty string as the value for this field.

See a Google Maps screenshot highlighting the <a href="#transitLongNameScreenshot">route_long_name</a>.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="route_desc_feed_data" id="route_desc_feed_data"></a>route_desc</td>

<td >Optional. The route_desc field contains a description of a route. Please provide useful, quality information. Do not simply duplicate the name of the route. For example, "A trains operate between Inwood-207 St, Manhattan and Far Rockaway-Mott Avenue, Queens at all times. Also from about 6AM until about midnight, additional A trains operate between Inwood-207 St and Lefferts Boulevard (trains typically alternate between Lefferts Blvd and Far Rockaway)." </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="route_type_feed_data" id="route_type_feed_data"></a>route_type</td>

<td >Required. The route_type field describes the type of transportation used on a route. Valid values for this field are:

<ul>

<li>0 - Tram, Streetcar, Light rail. Any light rail or street level system within a metropolitan area. </li>

<li>1 - Subway, Metro. Any underground rail system within a metropolitan area. </li>

<li>2 - Rail. Used for intercity or long-distance travel. </li>

<li>3 - Bus. Used for short- and long-distance bus routes. </li>

<li>4 - Ferry. Used for short- and long-distance boat service. </li>

<li>5 - Cable car. Used for street-level cable cars where the cable runs beneath the car. </li>

<li>6 - Gondola, Suspended cable car. Typically used for aerial cable cars where the car is suspended from the cable. </li>

<li>7 - Funicular. Any rail system designed for steep inclines. </li>

</ul>

See a Google Maps screenshot highlighting the <a href="#transitRouteTypeScreenshot">route_type</a>.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="route_url_feed_data" id="route_url_feed_data"></a>route_url</td>

<td >Optional. The route_url field contains the URL of a web page about that particular route. This should be different from the agency_url.

</tr>

<tr>

<td scope="row" class="attr"><a name="route_color_feed_data" id="route_color_feed_data"></a>route_color</td>

<td >Optional. In systems that have colors assigned to routes, the route_color field defines a color that corresponds to a route. The color must be provided as a six-character hexadecimal number, for example, 00FFFF. If no color is specified, the default route color is white (FFFFFF).

If the route_color makes overlaid text difficult to read, specify a contrasting text color with the route_text_color field. </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="route_text_color_feed_data" id="route_text_color_feed_data"></a>route_text_color</td>

<td >Optional. The route_text_color field can be used to specify a legible color to use for text drawn against a background of route_color. The color must be provided as a six-character hexadecimal number, for example, FFD700. If no color is specified, the default text color is black (000000).</td>

</tr>

</table>

<h2><a name="trips_txt___Field_Definitions" id="trips_txt___Field_Definitions"></a>trips.txt </h2>

<table>

<tbody>

<tr><th scope="col" abbr="field" width="15%">Field Name</th>

<th scope="col" abbr="details">Details</th>

</tr>

<tr>

<td scope="row" class="attr"><a name="route_id_ref_feed_data" id="route_id_ref_feed_data"></a>route_id</td>

<td >Required. The route_id field contains an ID that uniquely identifies a route. This value is referenced from the <a href="#routes_txt___Field_Definitions">routes.txt</a> file.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="service_id_ref_feed_data" id="service_id_ref_feed_data"></a>service_id</td>

<td >Required. The service_id contains an ID that uniquely identifies a set of dates when service is available for one or more routes. This value is referenced from the <a href="#calendar_txt___Field_Definitions">calendar.txt</a> or <a href="#calendar_dates_txt___Field_Definitions">calendar_dates.txt</a> file.</td>

</tr>

<tr>

<td >Required. The trip_id field contains an ID that identifies a trip. The trip_id is dataset unique. </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="trip_headsign_feed_data" id="trip_headsign_feed_data"></a>trip_headsign</td>

<td >Optional. The trip_headsign field contains the text that appears on a sign that identifies the trip's destination to passengers. Use this field to distinguish between different patterns of service in the same route. If the headsign changes during a trip, you can override the trip_headsign by specifying values for the the <a href="#stop_headsign_feed_data">stop_headsign</a> field in <a href="#stop_times_txt___Field_Definitions">stop_times.txt</a>

See a Google Maps screenshot highlighting the <a href="#transitTripHeadsignScreenshot">headsign</a>.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="direction_id_feed_data" id="direction_id_feed_data"></a>direction_id</td>

<td >Optional. The direction_id field contains a binary value that indicates the direction of travel for a trip. Use this field to distinguish between bi-directional trips with the same <a href="#route_id_feed_data">route_id</a>. This field is not used in routing; it provides a way to separate trips by direction when publishing time tables. You can specify names for each direction with the trip_headsign field.

<ul>

<li>0 - travel in one direction (e.g. outbound travel) </li>

<li>1 - travel in the opposite direction (e.g. inbound travel)

</li>

</ul>

For example, you could use the trip_headsign and direction_id fields together to assign a name to travel in each direction on trip "1234", the trips.txt file would contain these rows for use in time tables:

<code>trip_id, ... ,trip_headsign,direction_id

1234, ... , to Airport,0

1234, ... , to Downtown,1 </code></td>

</tr>

<tr>

<td scope="row" class="attr"><a name="block_id_feed_data" id="block_id_feed_data"></a>block_id</td>

<td >Optional. The block_id field identifies the block to which the trip belongs. A block consists of two or more sequential trips made using the same vehicle, where a passenger can transfer from one trip to the next just by staying in the vehicle. The block_id must be referenced by two or more trips in trips.txt. </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="shape_id_feed_data" id="shape_id_feed_data"></a>shape_id</td>

<td >Optional. The shape_id field contains an ID that defines a shape for the trip. This value is referenced from the <a href="#shapes_txt___Field_Definitions">shapes.txt</a> file. The shapes.txt file allows you to define how a line should be drawn on the map to represent a trip. </td>

</tr>

</tbody>

</table>

<h2><a name="stop_times_txt___Field_Definitions" id="stop_times_txt___Field_Definitions"></a>stop_times.txt </h2>

<table>

<tbody>

<tr><th scope="col" abbr="field" width="15%">Field Name</th>

<th scope="col" abbr="details">Details</th>

</tr>

<tr>

<td >Required. The trip_id field contains an ID that identifies a trip. This value is referenced from the <a href="#trips_txt___Field_Definitions">trips.txt</a> file.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="arrival_time_feed_data" id="arrival_time_feed_data"></a>arrival_time</td>

<td >Required. The arrival_time specifies the arrival time at a specific stop for a specific trip on a route. The time is measured from midnight at the beginning of the service date. For times occurring after midnight on the service date, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. If you don't have separate times for arrival and departure at a stop, enter the same value for arrival_time and departure_time.

You must specify arrival times for the first and last stops in a trip. If this stop isn't a time point, use an empty string value for the arrival_time and departure_time fields. Stops without arrival times will be scheduled based on the nearest preceding timed stop. To ensure accurate routing, please provide arrival and departure times for all stops that are time points. Do not interpolate stops.

Times must be eight digits in HH:MM:SS format (H:MM:SS is also accepted, if the hour begins with 0). Do not pad times with spaces. The following columns list stop times for a trip and the proper way to express those times in the

arrival_time

field:

<table>

<tr>

<th scope="col">arrival_time value</th>

</tr>

<tr>

</tr>

<tr>

</tr>

<tr>

</tr>

<tr>

</tr>

</table>

Note: Trips that span multiple dates will have stop times greater than 24:00:00. For example, if a trip begins at 10:30:00 p.m. and ends at 2:15:00 a.m. on the following day, the stop times would be 22:30:00 and 26:15:00. Entering those stop times as 22:30:00 and 02:15:00 would not produce the desired results.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="departure_time_feed_data" id="departure_time_feed_data"></a>departure_time</td>

<td >Required. The departure_time specifies the departure time from a specific stop for a specific trip on a route. The time is measured from midnight at the beginning of the service date. For times occurring after midnight on the service date, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. If you don't have separate times for arrival and departure at a stop, enter the same value for arrival_time and departure_time.

You must specify departure times for the first and last stops in a trip. If this stop isn't a time point, use an empty string value for the arrival_time and departure_time fields. Stops without arrival times will be scheduled based on the nearest preceding timed stop. To ensure accurate routing, please provide arrival and departure times for all stops that are time points. Do not interpolate stops.

Times must be eight digits in HH:MM:SS format (H:MM:SS is also accepted, if the hour begins with 0). Do not pad times with spaces. The following columns list stop times for a trip and the proper way to express those times in the

departure_time

field:

<table>

<tr>

<th width="173" scope="col">departure_time value</th>

</tr>

<tr>

</tr>

<tr>

</tr>

<tr>

</tr>

<tr>

</tr>

</table>

</tr>

<tr>

<td >Required. The stop_id field contains an ID that uniquely identifies a stop. Multiple routes may use the same stop. The stop_id is referenced from the <a href="#stops_txt___Field_Definitions">stops.txt</a> file. If location_type is used in stops.txt, all stops referenced in stop_times.txt must have location_type of 0.

Where possible, stop_id values should remain consistent between feed updates. In other words, stop A with stop_id 1 should have stop_id 1 in all subsequent data updates. If a stop is not a time point, enter blank values for arrival_time and departure_time. </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="stop_sequence_feed_data" id="stop_sequence_feed_data"></a>stop_sequence</td>

<td >Required. The stop_sequence field identifies the order of the stops for a particular trip. The values for stop_sequence must be non-negative integers, and they must increase along the trip.

For example, the first stop on the trip could have a stop_sequence of 1, the second stop on the trip could have a stop_sequence of 23, the third stop could have a stop_sequence of 40, and so on.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="stop_headsign_feed_data" id="stop_headsign_feed_data"></a>stop_headsign</td>

<td >Optional. The stop_headsign field contains the text that appears on a sign that identifies the trip's destination to passengers. Use this field to override the default <a href="#trip_headsign_feed_data">trip_headsign</a> when the headsign changes between stops. If this headsign is associated with an entire trip, use <a href="#trip_headsign_feed_data">trip_headsign</a> instead.

See a Google Maps screenshot highlighting the <a href="#transitTripHeadsignScreenshot">headsign</a>.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="pickup_type_feed_data" id="pickup_type_feed_data"></a>pickup_type</td>

<td >Optional. The pickup_type field indicates whether passengers are picked up at a stop as part of the normal schedule or whether a pickup at the stop is not available. This field also allows the transit agency to indicate that passengers must call the agency or notify the driver to arrange a pickup at a particular stop. Valid values for this field are:

<ul><li>0 - Regularly scheduled pickup</li><li>1 - No pickup available</li><li>2 - Must phone agency to arrange pickup</li><li>3 - Must coordinate with driver to arrange pickup</li></ul>The default value for this field is 0.</td>

</tr>

<tr>

<td >Optional. The drop_off_type field indicates whether passengers are dropped off at a stop as part of the normal schedule or whether a drop off at the stop is not available. This field also allows the transit agency to indicate that passengers must call the agency or notify the driver to arrange a drop off at a particular stop. Valid values for this field are:

<ul><li>0 - Regularly scheduled drop off</li><li>1 - No drop off available</li><li>2 - Must phone agency to arrange drop off</li>

<li>3 - Must coordinate with driver to arrange drop off</li>

</ul>

The default value for this field is 0.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="shape_dist_traveled_feed_data" id="shape_dist_traveled_feed_data"></a>shape_dist_traveled</td>

<td >Optional. When used in the stop_times.txt file, the shape_dist_traveled field positions a stop as a distance from the first shape point. The shape_dist_traveled field represents a real distance traveled along the route in units such as feet or kilometers. For example, if a bus travels a distance of 5.25 kilometers from the start of the shape to the stop, the shape_dist_traveled for the stop ID would be entered as "5.25". This information allows the trip planner to determine how much of the shape to draw when showing part of a trip on the map. The values used for shape_dist_traveled must increase along with stop_sequence: they cannot be used to show reverse travel along a route.

The units used for shape_dist_traveled in the stop_times.txt file must match the units that are used for this field in the <a href="#shapes_txt___Field_Definitions">shapes.txt</a> file.

</td>

</tr>

</tbody>

</table>

<h2><a name="calendar_txt___Field_Definitions" id="calendar_txt___Field_Definitions"></a>calendar.txt </h2>

<table>

<tbody>

<tr><th scope="col" abbr="field" width="15%">Field Name</th>

<th scope="col" abbr="details">Details</th>

</tr>

<tr>

<td scope="row" class="attr"><a name="service_id_feed_data" id="service_id_feed_data"></a>service_id</td>

<td >Required. The service_id contains an ID that uniquely identifies a set of dates when service is available for one or more routes. This value is dataset unique. It is referenced by the <a href="#trips_txt___Field_Definitions">trips.txt</a> file.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="monday_feed_data" id="monday_feed_data"></a>monday</td>

<td >Required. The monday field contains a binary value that indicates whether the service is valid for all Mondays.

<ul><li>A value of 1 indicates that service is available for all Mondays in the date range. (The date range is specified using the <a href="#start_date_feed_data">start_date</a> and <a href="#end_date_feed_data">end_date</a> fields.)</li>

<li>A value of 0 indicates that service is not available on Mondays in the date range.</li></ul>

Note: You may list exceptions for particular dates, such as holidays, in the <a href="#calendar_dates_txt___Field_Definitions">calendar_dates.txt</a> file.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="tuesday_feed_data" id="tuesday_feed_data"></a>tuesday</td>

<td >Required. The tuesday field contains a binary value that indicates whether the service is valid for all Tuesdays.

<ul><li>A value of 1 indicates that service is available for all Tuesdays in the date range. (The date range is specified using the <a href="#start_date_feed_data">start_date</a> and <a href="#end_date_feed_data">end_date</a> fields.)</li>

<li>A value of 0 indicates that service is not available on Tuesdays in the date range.</li>

</ul>

Note: You may list exceptions for particular dates, such as holidays, in the <a href="#calendar_dates_txt___Field_Definitions">calendar_dates.txt</a> file.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="wednesday_feed_data" id="wednesday_feed_data"></a>wednesday</td>

<td >Required. The wednesday field contains a binary value that indicates whether the service is valid for all Wednesdays.

<ul><li>A value of 1 indicates that service is available for all Wednesdays in the date range. (The date range is specified using the <a href="#start_date_feed_data">start_date</a> and <a href="#end_date_feed_data">end_date</a> fields.)</li>

<li>A value of 0 indicates that service is not available on Wednesdays in the date range.</li>

</ul>

Note: You may list exceptions for particular dates, such as holidays, in the <a href="#calendar_dates_txt___Field_Definitions">calendar_dates.txt</a> file.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="thursday_feed_data" id="thursday_feed_data"></a>thursday</td>

<td >Required. The thursday field contains a binary value that indicates whether the service is valid for all Thursdays.<ul><li>A value of 1 indicates that service is available for all Thursdays in the date range. (The date range is specified using the <a href="#start_date_feed_data">start_date</a> and <a href="#end_date_feed_data">end_date</a> fields.)</li>

<li>A value of 0 indicates that service is not available on Thursdays in the date range.</li>

</ul>

Note: You may list exceptions for particular dates, such as holidays, in the <a href="#calendar_dates_txt___Field_Definitions">calendar_dates.txt</a> file.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="friday_feed_data" id="friday_feed_data"></a>friday</td>

<td >Required. The friday field contains a binary value that indicates whether the service is valid for all Fridays.

<ul><li>A value of 1 indicates that service is available for all Fridays in the date range. (The date range is specified using the <a href="#start_date_feed_data">start_date</a> and <a href="#end_date_feed_data">end_date</a> fields.)</li>

<li>A value of 0 indicates that service is not available on Fridays in the date range.</li>

</ul>

Note: You may list exceptions for particular dates, such as holidays, in the <a href="#calendar_dates_txt___Field_Definitions">calendar_dates.txt</a> file</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="saturday_feed_data" id="saturday_feed_data"></a>saturday</td>

<td >Required. The saturday field contains a binary value that indicates whether the service is valid for all Saturdays.

<ul><li>A value of 1 indicates that service is available for all Saturdays in the date range. (The date range is specified using the <a href="#start_date_feed_data">start_date</a> and <a href="#end_date_feed_data">end_date</a> fields.)</li>

<li>A value of 0 indicates that service is not available on Saturdays in the date range.</li>

</ul>

Note: You may list exceptions for particular dates, such as holidays, in the <a href="#calendar_dates_txt___Field_Definitions">calendar_dates.txt</a> file.

</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="sunday_feed_data" id="sunday_feed_data"></a>sunday</td>

<td >Required. The sunday field contains a binary value that indicates whether the service is valid for all Sundays.

<ul><li>A value of 1 indicates that service is available for all Sundays in the date range. (The date range is specified using the <a href="#start_date_feed_data">start_date</a> and <a href="#end_date_feed_data">end_date</a> fields.)</li>

<li>A value of 0 indicates that service is not available on Sundays in the date range.</li>

</ul>

Note: You may list exceptions for particular dates, such as holidays, in the <a href="#calendar_dates_txt___Field_Definitions">calendar_dates.txt</a> file.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="start_date_feed_data" id="start_date_feed_data"></a>start_date</td>

<td >Required. The start_date field contains the start date for the service.The start_date field's value should be in YYYYMMDD format.</td>

</tr>

<tr>

<td >Required. The end_date field contains the end date for the service. This date is included in the service interval.The end_date field's value should be in YYYYMMDD format.</td>

</tr>

</tbody>

</table>

<h2><a name="calendar_dates_txt___Field_Definitions" id="calendar_dates_txt___Field_Definitions"></a>calendar_dates.txt </h2>

This file is optional. The calendar_dates table allows you to explicitly activate or disable service IDs by date. You can use it in two ways.

<ul>

<li>Recommended: Use calendar_dates.txt in conjunction with calendar.txt, where calendar_dates.txt defines any exceptions to the default service categories defined in the calendar.txt file. If your service is generally regular, with a few changes on explicit dates (for example, to accomodate special event services, or a school schedule), this is a good approach. </li>

<li>Alternate: Omit calendar.txt, and include ALL dates of service in calendar_dates.txt. If your schedule varies most days of the month, or you want to programmatically output service dates without specifying a normal weekly schedule, this approach may be preferable. </li>

</ul>

<table>

<tbody>

<tr><th scope="col" abbr="field" width="15%">Field Name</th>

<th scope="col" abbr="details">Details</th>

</tr>

<tr>

<td scope="row" class="attr"><a name="service_id_ref2_feed_data" id="service_id_ref2_feed_data"></a>service_id</td>

<td >Required. The service_id contains an ID that uniquely identifies a set of dates when a service exception is available for one or more routes. If the same service_id value appears in both files, the information in calendar_dates.txt modifies the service information specified in <a href="#calendar_txt___Field_Definitions">calendar.txt</a>. This field is referenced by the <a href="#trips_txt___Field_Definitions">trips.txt</a> file.</td>

</tr>

<tr>

<td >Required. The date field specifies a particular date when service availability is different than the norm. You can use the <a href="#exception_type_feed_data">exception_type</a> field to indicate whether service is available on the specified date.The date field's value should be in YYYYMMDD format.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="exception_type_feed_data" id="exception_type_feed_data"></a>exception_type</td>

<td >Required. The exception_type indicates whether service is available on the date specified in the <a href="#date_feed_data">date</a> field.

<ul><li>A value of 1 indicates that service has been added for the specified date.</li>

<li>A value of 2 indicates that service has been removed for the specified date.</li>

</ul>

For example, suppose a route has one set of trips available on holidays and another set of trips available on all other days. You could have one <a href="#service_id_feed_data">service_id</a> that corresponds to the regular service schedule and another <a href="#service_id_feed_data">service_id</a> that corresponds to the holiday schedule. For a particular holiday, you would use the <a href="#calendar_dates_txt___Field_Definitions">calendar_dates</a> file to add the holiday to the holiday <a href="#service_id_feed_data">service_id</a> and to remove the holiday from the regular <a href="#service_id_feed_data">service_id</a> schedule.</td>

</tr>

</tbody>

</table>

<h2><a name="fare_attributes_txt___Field_Definitions" id="fare_attributes_txt___Field_Definitions"></a>fare_attributes.txt </h2>

<table>

<tr><th scope="col" abbr="field" width="15%">Field Name</th>

<th scope="col" abbr="details">Details</th>

</tr>

<tr>

<td >Required. The fare_id field contains an ID that uniquely identifies a fare class. The fare_id is dataset unique.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="price_feed_data" id="price_feed_data"></a>price</td>

<td >Required. The price field contains the fare price, in the unit specified by currency_type. </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="currency_type_feed_data" id="currency_type_feed_data"></a>currency_type</td>

<td >Required. The currency_type field defines the currency used to pay the fare. Please use the ISO 4217 alphabetical currency codes which can be found at the following URL: <a href="http://www.iso.org/iso/en/prods-services/popstds/currencycodeslist.html">http://www.iso.org/iso/en/prods-services/popstds/currencycodeslist.html</a>.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="payment_method_feed_data" id="payment_method_feed_data"></a>payment_method</td>

<td >Required. The payment_method field indicates when the fare must be paid. Valid values for this field are:

<ul>

<li>0 - Fare is paid on board. </li>

<li>1 - Fare must be paid before boarding. </li>

</ul></td>

</tr>

<tr>

<td scope="row" class="attr"><a name="transfers_feed_data" id="transfers_feed_data"></a>transfers</td>

<td >Required. The transfers field specifies the number of transfers permitted on this fare. Valid values for this field are:

<ul>

<li>0 - No transfers permitted on this fare. </li>

<li>1 - Passenger may transfer once. </li>

<li>2 - Passenger may transfer twice. </li>

<li>(empty) - If this field is empty, unlimited transfers are permitted. </li>

</ul></td>

</tr>

<tr>

<td scope="row" class="attr"><a name="transfer_duration_data" id="transfer_duration_data"></a>transfer_duration</td>

<td >Optional. The transfer_duration field specifies the length of time in seconds before a transfer expires.

When used with a transfers value of 0, the transfer_duration field indicates how long a ticket is valid for a fare where no transfers are allowed. Unless you intend to use this field to indicate ticket validity, transfer_duration should be omitted or empty when transfers is set to 0.</td>

</tr>

</table>

<h2><a name="fare_rules_txt___Field_Definitions" id="fare_rules_txt___Field_Definitions"></a>fare_rules.txt - Field Definitions</h2>

This file is optional. The fare_rules table allows you to specify how fares in fare_attributes.txt apply to an itinerary. Most fare structures use some combination of the following rules:

<ul>

<li>Fare depends on origin or destination stations. </li>

<li>Fare depends on which zones the itinerary passes through. </li>

<li>Fare depends on which route the itinerary uses. </li>

</ul>

For examples that demonstrate how to specify a fare structure with fare_rules.txt and fare_attributes.txt, see <a href="http://code.google.com/p/googletransitdatafeed/wiki/FareExamples">FareExamples</a> in the GoogleTransitDataFeed open source project wiki.

<table>

<tr><th scope="col" abbr="field" width="15%">Field Name</th>

<th scope="col" abbr="details">Details</th>

</tr>

<tr>

<td >Required. The fare_id field contains an ID that uniquely identifies a fare class. This value is referenced from the <a href="#fare_attributes_txt___Field_Definitions">fare_attributes.txt</a> file.</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="route_id_ref2_feed_data" id="route_id_ref2_feed_data"></a>route_id</td>

<td >Optional. The route_id field associates the fare ID with a route. Route IDs are referenced from the <a href="#routes_txt___Field_Definitions">routes.txt</a> file. If you have several routes with the same fare attributes, create a row in fare_rules.txt for each route.

For example, if fare class "b" is valid on route "TSW" and "TSE", the fare_rules.txt file would contain these rows for the fare class:

</tr>

<tr>

<td scope="row" class="attr"><a name="origin_id_feed_data" id="origin_id_feed_data"></a>origin_id</td>

<td >Optional. The origin_id field associates the fare ID with an origin <a href="#zone_id_feed_data">zone ID</a>. Zone IDs are referenced from the <a href="#stops_txt___Field_Definitions">stops.txt</a> file. If you have several origin IDs with the same fare attributes, create a row in fare_rules.txt for each origin ID.

For example, if fare class "b" is valid for all travel originating from either zone "2" or zone "8", the fare_rules.txt file would contain these rows for the fare class:

</tr>

<tr>

<td scope="row" class="attr"><a name="destination_id_data" id="dest_id_data"></a>destination_id</td>

<td >Optional. The destination_id field associates the fare ID with a destination <a href="#zone_id_feed_data">zone ID</a>. Zone IDs are referenced from the <a href="#stops_txt___Field_Definitions">stops.txt</a> file. If you have several destination IDs with the same fare attributes, create a row in fare_rules.txt for each destination ID.

For example, you could use the origin_ID and destination_ID fields together to specify that fare class "b" is valid for travel between zones 3 and 4, and for travel between zones 3 and 5, the fare_rules.txt file would contain these rows for the fare class:

</tr>

<tr>

<td scope="row" class="attr"><a name="contains_id_data" id="contains_id_data"></a>contains_id</td>

<td >Optional. The contains_id field associates the fare ID with a <a href="#zone_id_feed_data">zone ID</a>, referenced from the <a href="#stops_txt___Field_Definitions">stops.txt</a> file. The fare ID is then associated with itineraries that pass through every contains_id zone.

For example, if fare class "c" is associated with all travel on the GRT route that passes through zones 5, 6, and 7 the fare_rules.txt would contain these rows:

<code>c,GRT,,,5

c,GRT,,,6</code>

Because all contains_id zones must be matched for the fare to apply, an itinerary that passes through zones 5 and 6 but not zone 7 would not have fare class "c". For more detail, see <a href="http://code.google.com/p/googletransitdatafeed/wiki/FareExamples">FareExamples</a> in the GoogleTransitDataFeed project wiki. </td>

</tr>

</table>

<h2><a name="shapes_txt___Field_Definitions" id="shapes_txt___Field_Definitions"></a>shapes.txt </h2>

<table>

<tr><th scope="col" abbr="field" width="15%">Field Name</th>

<th scope="col" abbr="details">Details</th>

</tr>

<tr>

<td scope="row" class="attr"><a name="shape_id_ref_feed_data" id="shape_id_ref_feed_data"></a>shape_id</td>

<td >Required. The shape_id field contains an ID that uniquely identifies a shape. </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="shape_pt_lat_feed_data" id="shape_pt_lat_feed_data"></a>shape_pt_lat</td>

<td >Required. The shape_pt_lat field associates a shape point's latitude with a shape ID. The field value must be a valid WGS 84 latitude. Each row in shapes.txt represents a shape point in your shape definition.

For example, if the shape "A_shp" has three points in its definition, the shapes.txt file might contain these rows to define the shape:

<code>A_shp,37.61956,-122.48161,0

A_shp,37.64430,-122.41070,6

A_shp,37.65863,-122.30839,11</code></td>

</tr>

<tr>

<td scope="row" class="attr"><a name="shape_pt_lon_feed_data" id="shape_pt_lon_feed_data"></a>shape_pt_lon</td>

<td >Required. The shape_pt_lon field associates a shape point's longitude with a shape ID. The field value must be a valid WGS 84 longitude value from -180 to 180. Each row in shapes.txt represents a shape point in your shape definition.

For example, if the shape "A_shp" has three points in its definition, the shapes.txt file might contain these rows to define the shape:

<code>A_shp,37.61956,-122.48161,0

A_shp,37.64430,-122.41070,6

A_shp,37.65863,-122.30839,11 </code></td>

</tr>

<tr>

<td scope="row" class="attr"><a name="shape_pt_sequence_feed_data" id="shape_pt_sequence_feed_data"></a>shape_pt_sequence</td>

<td >Required. The shape_pt_sequence field associates the latitude and longitude of a shape point with its sequence order along the shape. The values for shape_pt_sequence must be non-negative integers, and they must increase along the trip.

For example, if the shape "A_shp" has three points in its definition, the shapes.txt file might contain these rows to define the shape:

<code>A_shp,37.61956,-122.48161,0

A_shp,37.64430,-122.41070,6

A_shp,37.65863,-122.30839,11

</code></td>

</tr>

<tr>

<td scope="row" class="attr"><a name="shape_dist_traveled_shapes_data" id="shape_dist_traveled_shapes_data"></a>shape_dist_traveled</td>

<td >Optional. When used in the shapes.txt file, the shape_dist_traveled field positions a shape point as a distance traveled along a shape from the first shape point. The shape_dist_traveled field represents a real distance traveled along the route in units such as feet or kilometers. This information allows the trip planner to determine how much of the shape to draw when showing part of a trip on the map. The values used for shape_dist_traveled must increase along with shape_pt_sequence: they cannot be used to show reverse travel along a route.

The units used for shape_dist_traveled in the shapes.txt file must match the units that are used for this field in the <a href="#stop_times_txt___Field_Definitions">stop_times.txt</a> file.

For example, if a bus travels along the three points defined above for A_shp, the additional shape_dist_traveled values (shown here in kilometers) would look like this:

<code>A_shp,37.61956,-122.48161,0,0

A_shp,37.64430,-122.41070,6,6.8310

A_shp,37.65863,-122.30839,11,15.8765</code>

</td>

</tr>

</table>

<h2><a name="frequencies_txt___Field_Definitions" id="frequencies_txt___Field_Definitions"></a>frequencies.txt </h2>

The frequencies file is optional. This table is intended to represent schedules that don't have a fixed list of stop times. When trips are defined in frequencies.txt, the trip planner ignores the absolute values of the <a href="#arrival_time_feed_data">arrival_time</a> and <a href="#departure_time_feed_data">departure_time</a> fields for those trips in <a href="#stop_times_txt___Field_Definitions">stop_times.txt</a>. Instead, the stop_times table defines the sequence of stops and the time difference between each stop.

<table>

<tbody>

<tr><th scope="col" abbr="field" width="15%">Field Name</th>

<th scope="col" abbr="details">Details</th>

</tr>

<tr>

<td >Required. The trip_id contains an ID that identifies a trip on which the specified frequency of service applies. Trip IDs are referenced from the <a href="#trips_txt___Field_Definitions">trips.txt</a> file. </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="frequencies_start_time_feed_data" id="headway_start_time_feed_data"></a>start_time</td>

<td >Required. The start_time field specifies the time at which service begins with the specified frequency. For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. E.g. 25:35:00. </td>

</tr>

<tr>

<td >Required. The end_time field indicates the time at which service changes to a different frequency (or ceases) at the first stop in the trip. For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. E.g. 25:35:00. </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="frequencies_secs_feed_data" id="headway_secs_feed_data"></a>headway_secs</td>

<td >Required. The headway_secs field indicates the time between departures from the same stop (headway) for this trip type, during the time interval specified by start_time and end_time. The headway value must be entered in seconds.

Periods in which headways are defined (the rows in frequencies.txt) shouldn't overlap for the same trip, since it's hard to determine what should be inferred from two overlapping headways. However, a headway period may begin at the exact same time that another one ends, for instance:

<code>A, 05:00:00, 07:00:00, 600

B, 07:00:00, 12:00:00, 1200 </code>

</td>

</tr>

</tbody>

</table>

<h2><a name="transfers_txt___Field_Definitions" id="transfers_txt___Field_Definitions"></a>transfers.txt </h2>

The transfers file is optional. Trip planners normally calculate transfer points based on the relative proximity of stops in each route. For potentially ambiguous stop pairs, or transfers where you want to specify a particular choice, use transfers.txt to define additional rules for making connections between routes.

<table>

<tbody>

<tr>

<th scope="col" abbr="field" width="15%">Field Name</th>

<th scope="col" abbr="details">Details</th>

</tr>

<tr>

<td >Required. The from_stop_id field contains a stop ID that identifies a stop or station where a connection between routes begins. Stop IDs are referenced from the <a href="#stops_txt___Field_Definitions">stops.txt</a> file. If the stop ID refers to a station that contains multiple stops, this transfer rule applies to all stops in that station. </td>

</tr>

<tr>

<td >Required. The to_stop_id field contains a stop ID that identifies a stop or station where a connection between routes ends. Stop IDs are referenced from the <a href="#stops_txt___Field_Definitions">stops.txt</a> file. If the stop ID refers to a station that contains multiple stops, this transfer rule applies to all stops in that station. </td>

</tr>

<tr>

<td scope="row" class="attr"><a name="transfers_transfer_type_feed_data" id="transfers_transfer_type_feed_data"></a>transfer_type </td>

<td >Required. The transfer_type field specifies the type of connection for the specified (from_stop_id, to_stop_id) pair. Valid values for this field are:

<ul>

<li>0 or (empty) - This is a recommended transfer point between two routes. </li>

<li>1 - This is a timed transfer point between two routes. The departing vehicle is expected to wait for the arriving one, with sufficient time for a passenger to transfer between routes </li>

<li>2 - This transfer requires a minimum amount of time between arrival and departure to ensure a connection.

The time required to transfer is specified by min_transfer_time. </li>

<li>3 - Transfers are not possible between routes at this location. </li>

</ul>

</td>

</tr>

<tr>

<td scope="row" class="attr"><a name="transfers_min_transfer_time_feed_data" id="transfers_min_transfer_time_feed_data"></a>min_transfer_time</td>

<td >Optional. When a connection between routes requires an amount of time between arrival and departure (transfer_type=2), the min_transfer_time field defines the amount of time that must be available in an itinerary to permit a transfer between routes at these stops. The min_transfer_time must be sufficient to permit a typical rider to move between the two stops, including buffer time to allow for schedule variance on each route.

The min_transfer_time value must be entered in seconds, and must be a non-negative integer. <code></code></td>

</tr>

</tbody>

</table>

<h1><a name="transitFeedSampleData" id="transitFeedSampleData"></a>Sample Data</h1>

This section shows comma-delimited data samples for each file in a transit feed. The sample data files shown here aren't all related to each other.

agency.txt

<pre>agency_id, agency_name,agency_url,agency_timezone,agency_phone

FunBus,The Fun Bus,http://www.thefunbus.org,America/Los_Angeles,(310) 555-0222</pre>

stops.txt

<pre>

stop_id,stop_name,stop_desc,stop_lat,stop_lon,stop_url,location_type,parent_station

S1,Mission St. & Silver Ave.,The stop is located at the southwest corner of the intersection.,37.728631,-122.431282,,

S2,Mission St. & Cortland Ave.,The stop is located 20 feet south of Mission St.,37.74103,-122.422482,,

S3,Mission St. & 24th St.,The stop is located at the southwest corner of the intersection.,37.75223,-122.418581,,

S4,Mission St. & 21st St.,The stop is located at the northwest corner of the intersection.,37.75713,-122.418982,,

S5,Mission St. & 18th St.,The stop is located 25 feet west of 18th St.,37.761829,-122.419382,,

S6,Mission St. & 15th St.,The stop is located 10 feet north of Mission St.,37.766629,-122.419782,,

S7,24th St. Mission Station,37.752240,-122.418450,,,2

S8,24th St. Mission Station,37.752240,-122.418450,http://www.bart.gov/stations/stationguide/stationoverview_24st.asp,1, </pre>

routes.txt

<pre>

route_id,route_short_name,route_long_name,route_desc,route_type

A,17,Mission,"The ""A"" route travels from lower Mission to Downtown. The ""A"" route is available for service on weekdays and weekends, but weekend service has limited stops.",3

</pre>

trips.txt

<pre>route_id,service_id,trip_id,trip_headsign,block_id

A,WE,AWE1,Downtown,1

A,WE,AWE2,Downtown,2

</pre>

stop_times.txt

<pre>

trip_id,arrival_time,departure_time,stop_id,stop_sequence,pickup_type,dropoff_type

AWE1,0:06:10,0:06:10,S1,1,0,0,0

AWE1,,,S2,2,0,1,3

AWE1,0:06:20,0:06:30,S3,3,0,0,0

AWE1,,,S5,4,0,0,0

AWE1,0:06:45,0:06:45,S6,5,0,0,0

AWD1,0:06:10,0:06:10,S1,1,0,0,0

AWD1,,,S2,2,0,0,0

AWD1,0:06:20,0:06:20,S3,3,0,0,0

AWD1,,,S4,4,0,0,0

AWD1,,,S5,5,0,0,0

AWD1,0:06:45,0:06:45,S6,6,0,0,0

</pre>

calendar.txt

<pre>

service_id,monday,tuesday,wednesday,thursday,friday,saturday,sunday,start_date,end_date

WE,0,0,0,0,0,1,1,20060701,20060731

WD,1,1,1,1,1,0,0,20060701,20060731

</pre>

calendar_dates.txt

This example shows service exceptions for the Independence Day holiday in 2006. On Monday July 3, 2006, regular weekday service (service_id=WD) is interrupted (exception_type=2). Instead, weekend service (service_id=WE) runs on that date (exception_type=1). The same change applies on Tuesday July 4, as well.

<pre>

service_id,date,exception_type

WD,20060703,2

WE,20060703,1

WD,20060704,2

WE,20060704,1

</pre>

fare_attributes.txt

<pre>fare_id,price,currency_type,payment_method,transfers,transfer_duration

1,0.00,USD,0,0,0

2,0.50,USD,0,0,0

3,1.50,USD,0,0,0

4,2.00,USD,0,0,0

5,2.50,USD,0,0,0</pre>

fare_rules.txt

<pre>fare_id,route_id,origin_id,destination_id,contains_id

a,TSW,1,1,

a,TSE,1,1,

a,GRT,1,1,

a,GRJ,1,1,

a,SVJ,1,1,

a,JSV,1,1,

a,GRT,2,4,

a,GRJ,4,2,

b,GRT,3,3,

c,GRT,,,6</pre>

shapes.txt

<pre>shape_id,shape_pt_lat,shape_pt_lon,shape_pt_sequence,shape_dist_traveled

A_shp,37.61956,-122.48161,1,0

A_shp,37.64430,-122.41070,2,6.8310

A_shp,37.65863,-122.30839,3,15.8765

</pre>

frequencies.txt

<pre>trip_id,start_time,end_time,headway_secs

AWE1,05:30:00,06:30:00,300

AWE1,06:30:00,20:30:00,180

AWE1,20:30:00,28:00:00,420</pre>

transfers.txt

<pre>from_stop_id,to_stop_id,transfer_type,min_transfer_time

S6,S7,2,300 S7,S6,3,

S23,S7,1,

</pre>

<h1><a name="transitAgencyExample" id="transitAgencyExample"></a>Demo Transit Agency Example</h1>

The "Demo Transit Agency" is a fictional transit agency that Google created to illustrate a complete transit feed. To see transit data from this fictional agency in Google Maps, <a href="http://www.google.com/transit?ttype=dep&saddr=North+Ave+at+N+A+Ave+Beatty,+NV&daddr=W+Cottonwood+Dr+at+A+Ave+S+Beatty,+NV&ie=UTF8">click here</a>.

To view the zip file for this example, download the file <a href="sample-feed.zip">sample-feed.zip</a>. You can also preview the feed contents for the Demo Transit Agency as <a href="http://spreadsheets.google.com/pub?key=puMHBiWYEbXT0UxQGLDpuBA&output=html">an HTML file</a> or <a href="http://spreadsheets.google.com/pub?key=puMHBiWYEbXT0UxQGLDpuBA&output=xls">an XLS file</a>.

<h1><a name="transitScreenshots" id="transitScreenshots"></a>Displaying Transit Data to Maps Users</h1>

The following screenshots show sample user interfaces displaying transit data in Google Maps. Each screenshot highlights a different field from a transit feed.

Note: The Google Maps user interface for transit is subject to change at Google's discretion. As such, there is no guarantee that the data that you provide will be displayed exactly as shown in the screenshots below.

Figure 1: Highlighting the route's <a href="#route_short_name_feed_data">short name</a> (20)

Figure 2: Highlighting the route's <a href="#route_long_name_feed_data">long name</a> (Burnside/Stark)

Figure 3: Highlighting the <a href="#trip_headsign_feed_data">Trip Headsign</a> (Gresham TC)

Figure 4: Highlighting the <a href="#route_type_feed_data">Route Type</a> (with a bus icon)

</div>

</div>

</div>

</div>

Except as otherwise <a

href="http://code.google.com/policies.html#restrictions">noted</a>,

the content of this page is licensed under the <a rel="license"

href="http://creativecommons.org/licenses/by/2.5/">Creative Commons

Attribution 2.5 License</a>.

<!-- <rdf:RDF xmlns="http://web.resource.org/cc/"

xmlns:dc="http://purl.org/dc/elements/1.1/"

xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">

</Work>

</License>

</rdf:RDF> -->

</div>

<a href="/">Code Home</a> -

<a href="http://www.google.com/accounts/TOS">Terms of Service</a> -

<a href="http://www.google.com/privacy.html">Privacy Policy</a> -

<a href="http://moderator.appspot.com/#e%253Dagltb2RlcmF0b3JyDgsSBlNlcmllcxifggIM%252Bv%253D0">Feedback</a> -

<a href="/more/">Site Directory</a>

Google Code offered in:

<a href="/intl/zh-CN/">中文</a> -

<a href="/intl/en/">English</a> -

<a href="/intl/pt-BR/">Português</a> -

<a href="/intl/ru/">Pусский</a> -

<a href="/intl/es/">Español</a> -

</div>

</div>

</div>

try {

var transitTracker = _gat._getTracker("UA-1237346-1");

transitTracker._setAllowAnchor(true);

transitTracker._initData();

transitTracker._trackPageview();

} catch(e) {}

</script>

</body>

</html>

#format rst

=====================================

The Internal Structure of Python Eggs

=====================================

STOP! This is not the first document you should read!

This document assumes you have at least some passing familiarity with

*using* setuptools, the ``pkg_resources`` module, and EasyInstall. It

does not attempt to explain basic concepts like inter-project

dependencies, nor does it contain detailed lexical syntax for most

file formats. Neither does it explain concepts like "namespace

packages" or "resources" in any detail, as all of these subjects are

covered at length in the setuptools developer's guide and the

``pkg_resources`` reference manual.

Instead, this is **internal** documentation for how those concepts and

features are *implemented* in concrete terms. It is intended for people

who are working on the setuptools code base, who want to be able to

troubleshoot setuptools problems, want to write code that reads the file

formats involved, or want to otherwise tinker with setuptools-generated

files and directories.

Note, however, that these are all internal implementation details and

are therefore subject to change; stick to the published API if you don't

want to be responsible for keeping your code from breaking when

setuptools changes. You have been warned.

.. contents:: **Table of Contents**

----------------------

Eggs and their Formats

----------------------

A "Python egg" is a logical structure embodying the release of a

specific version of a Python project, comprising its code, resources,

and metadata. There are multiple formats that can be used to physically

encode a Python egg, and others can be developed. However, a key

principle of Python eggs is that they should be discoverable and

importable. That is, it should be possible for a Python application to

easily and efficiently find out what eggs are present on a system, and

to ensure that the desired eggs' contents are importable.

There are two basic formats currently implemented for Python eggs:

1. ``.egg`` format: a directory or zipfile *containing* the project's

code and resources, along with an ``EGG-INFO`` subdirectory that

contains the project's metadata

2. ``.egg-info`` format: a file or directory placed *adjacent* to the

project's code and resources, that directly contains the project's

metadata.

Both formats can include arbitrary Python code and resources, including

static data files, package and non-package directories, Python

modules, C extension modules, and so on. But each format is optimized

for different purposes.

The ``.egg`` format is well-suited to distribution and the easy

uninstallation or upgrades of code, since the project is essentially

self-contained within a single directory or file, unmingled with any

other projects' code or resources. It also makes it possible to have

multiple versions of a project simultaneously installed, such that

individual programs can select the versions they wish to use.

The ``.egg-info`` format, on the other hand, was created to support

backward-compatibility, performance, and ease of installation for system

packaging tools that expect to install all projects' code and resources

to a single directory (e.g. ``site-packages``). Placing the metadata

in that same directory simplifies the installation process, since it

isn't necessary to create ``.pth`` files or otherwise modify

``sys.path`` to include each installed egg.

Its disadvantage, however, is that it provides no support for clean

uninstallation or upgrades, and of course only a single version of a

project can be installed to a given directory. Thus, support from a

package management tool is required. (This is why setuptools' "install"

command refers to this type of egg installation as "single-version,

externally managed".) Also, they lack sufficient data to allow them to

be copied from their installation source. easy_install can "ship" an

application by copying ``.egg`` files or directories to a target

location, but it cannot do this for ``.egg-info`` installs, because

there is no way to tell what code and resources belong to a particular

egg -- there may be several eggs "scrambled" together in a single

installation location, and the ``.egg-info`` format does not currently

include a way to list the files that were installed. (This may change

in a future version.)

Code and Resources

==================

The layout of the code and resources is dictated by Python's normal

import layout, relative to the egg's "base location".

For the ``.egg`` format, the base location is the ``.egg`` itself. That

is, adding the ``.egg`` filename or directory name to ``sys.path``

makes its contents importable.

For the ``.egg-info`` format, however, the base location is the

directory that *contains* the ``.egg-info``, and thus it is the

directory that must be added to ``sys.path`` to make the egg importable.

(Note that this means that the "normal" installation of a package to a

``sys.path`` directory is sufficient to make it an "egg" if it has an

``.egg-info`` file or directory installed alongside of it.)

Project Metadata

=================

If eggs contained only code and resources, there would of course be

no difference between them and any other directory or zip file on

``sys.path``. Thus, metadata must also be included, using a metadata

file or directory.

For the ``.egg`` format, the metadata is placed in an ``EGG-INFO``

subdirectory, directly within the ``.egg`` file or directory. For the

``.egg-info`` format, metadata is stored directly within the

``.egg-info`` directory itself.

The minimum project metadata that all eggs must have is a standard

Python ``PKG-INFO`` file, named ``PKG-INFO`` and placed within the

metadata directory appropriate to the format. Because it's possible for

this to be the only metadata file included, ``.egg-info`` format eggs

are not required to be a directory; they can just be a ``.egg-info``

file that directly contains the ``PKG-INFO`` metadata. This eliminates

the need to create a directory just to store one file. This option is

*not* available for ``.egg`` formats, since setuptools always includes

other metadata. (In fact, setuptools itself never generates

``.egg-info`` files, either; the support for using files was added so

that the requirement could easily be satisfied by other tools, such

as the distutils in Python 2.5).

In addition to the ``PKG-INFO`` file, an egg's metadata directory may

also include files and directories representing various forms of

optional standard metadata (see the section on `Standard Metadata`_,

below) or user-defined metadata required by the project. For example,

some projects may define a metadata format to describe their application

plugins, and metadata in this format would then be included by plugin

creators in their projects' metadata directories.

Filename-Embedded Metadata

==========================

To allow introspection of installed projects and runtime resolution of

inter-project dependencies, a certain amount of information is embedded

in egg filenames. At a minimum, this includes the project name, and

ideally will also include the project version number. Optionally, it

can also include the target Python version and required runtime

platform if platform-specific C code is included. The syntax of an

egg filename is as follows::

name ["-" version ["-py" pyver ["-" required_platform]]] "." ext

The "name" and "version" should be escaped using the ``to_filename()``

function provided by ``pkg_resources``, after first processing them with

``safe_name()`` and ``safe_version()`` respectively. These latter two

functions can also be used to later "unescape" these parts of the

filename. (For a detailed description of these transformations, please

see the "Parsing Utilities" section of the ``pkg_resources`` manual.)

The "pyver" string is the Python major version, as found in the first

3 characters of ``sys.version``. "required_platform" is essentially

a distutils ``get_platform()`` string, but with enhancements to properly

distinguish Mac OS versions. (See the ``get_build_platform()``

documentation in the "Platform Utilities" section of the

``pkg_resources`` manual for more details.)

Finally, the "ext" is either ``.egg`` or ``.egg-info``, as appropriate

for the egg's format.

Normally, an egg's filename should include at least the project name and

version, as this allows the runtime system to find desired project

versions without having to read the egg's PKG-INFO to determine its

version number.

Setuptools, however, only includes the version number in the filename

when an ``.egg`` file is built using the ``bdist_egg`` command, or when

an ``.egg-info`` directory is being installed by the

``install_egg_info`` command. When generating metadata for use with the

original source tree, it only includes the project name, so that the

directory will not have to be renamed each time the project's version

changes.

This is especially important when version numbers change frequently, and

the source metadata directory is kept under version control with the

rest of the project. (As would be the case when the project's source

includes project-defined metadata that is not generated from by

setuptools from data in the setup script.)

Egg Links

=========

In addition to the ``.egg`` and ``.egg-info`` formats, there is a third

egg-related extension that you may encounter on occasion: ``.egg-link``

files.

These files are not eggs, strictly speaking. They simply provide a way

to reference an egg that is not physically installed in the desired

location. They exist primarily as a cross-platform alternative to

symbolic links, to support "installing" code that is being developed in

a different location than the desired installation location. For

example, if a user is developing an application plugin in their home

directory, but the plugin needs to be "installed" in an application

plugin directory, running "setup.py develop -md /path/to/app/plugins"

will install an ``.egg-link`` file in ``/path/to/app/plugins``, that

tells the egg runtime system where to find the actual egg (the user's

project source directory and its ``.egg-info`` subdirectory).

``.egg-link`` files are named following the format for ``.egg`` and

``.egg-info`` names, but only the project name is included; no version,

Python version, or platform information is included. When the runtime

searches for available eggs, ``.egg-link`` files are opened and the

actual egg file/directory name is read from them.

Each ``.egg-link`` file should contain a single file or directory name,

with no newlines. This filename should be the base location of one or

more eggs. That is, the name must either end in ``.egg``, or else it

should be the parent directory of one or more ``.egg-info`` format eggs.

As of setuptools 0.6c6, the path may be specified as a platform-independent

(i.e. ``/``-separated) relative path from the directory containing the

``.egg-link`` file, and a second line may appear in the file, specifying a

platform-independent relative path from the egg's base directory to its

setup script directory. This allows installation tools such as EasyInstall

to find the project's setup directory and build eggs or perform other setup

commands on it.

-----------------

Standard Metadata

-----------------

In addition to the minimum required ``PKG-INFO`` metadata, projects can

include a variety of standard metadata files or directories, as

described below. Except as otherwise noted, these files and directories

are automatically generated by setuptools, based on information supplied

in the setup script or through analysis of the project's code and

resources.

Most of these files and directories are generated via "egg-info

writers" during execution of the setuptools ``egg_info`` command, and

are listed in the ``egg_info.writers`` entry point group defined by

setuptools' own ``setup.py`` file.

Project authors can register their own metadata writers as entry points

in this group (as described in the setuptools manual under "Adding new

EGG-INFO Files") to cause setuptools to generate project-specific

metadata files or directories during execution of the ``egg_info``

command. It is up to project authors to document these new metadata

formats, if they create any.

``.txt`` File Formats

=====================

Files described in this section that have ``.txt`` extensions have a

simple lexical format consisting of a sequence of text lines, each line

terminated by a linefeed character (regardless of platform). Leading

and trailing whitespace on each line is ignored, as are blank lines and

lines whose first nonblank character is a ``#`` (comment symbol). (This

is the parsing format defined by the ``yield_lines()`` function of

the ``pkg_resources`` module.)

All ``.txt`` files defined by this section follow this format, but some

are also "sectioned" files, meaning that their contents are divided into

sections, using square-bracketed section headers akin to Windows

``.ini`` format. Note that this does *not* imply that the lines within

the sections follow an ``.ini`` format, however. Please see an

individual metadata file's documentation for a description of what the

lines and section names mean in that particular file.

Sectioned files can be parsed using the ``split_sections()`` function;

see the "Parsing Utilities" section of the ``pkg_resources`` manual for

for details.

Dependency Metadata

===================

``requires.txt``

----------------

This is a "sectioned" text file. Each section is a sequence of

"requirements", as parsed by the ``parse_requirements()`` function;

please see the ``pkg_resources`` manual for the complete requirement

parsing syntax.

The first, unnamed section (i.e., before the first section header) in

this file is the project's core requirements, which must be installed

for the project to function. (Specified using the ``install_requires``

keyword to ``setup()``).

The remaining (named) sections describe the project's "extra"

requirements, as specified using the ``extras_require`` keyword to

``setup()``. The section name is the name of the optional feature, and

the section body lists that feature's dependencies.

Note that it is not normally necessary to inspect this file directly;

``pkg_resources.Distribution`` objects have a ``requires()`` method

that can be used to obtain ``Requirement`` objects describing the

project's core and optional dependencies.

``dependency_links.txt``

------------------------

A list of dependency URLs, one per line, as specified using the

``dependency_links`` keyword to ``setup()``. These may be direct

download URLs, or the URLs of web pages containing direct download

links, and will be used by EasyInstall to find dependencies, as though

the user had manually provided them via the ``--find-links`` command

line option. Please see the setuptools manual and EasyInstall manual

for more information on specifying this option, and for information on

how EasyInstall processes ``--find-links`` URLs.

``depends.txt`` -- Obsolete, do not create!

-------------------------------------------

This file follows an identical format to ``requires.txt``, but is

obsolete and should not be used. The earliest versions of setuptools

required users to manually create and maintain this file, so the runtime

still supports reading it, if it exists. The new filename was created

so that it could be automatically generated from ``setup()`` information

without overwriting an existing hand-created ``depends.txt``, if one

was already present in the project's source ``.egg-info`` directory.

``namespace_packages.txt`` -- Namespace Package Metadata

========================================================

A list of namespace package names, one per line, as supplied to the

``namespace_packages`` keyword to ``setup()``. Please see the manuals

for setuptools and ``pkg_resources`` for more information about

namespace packages.

``entry_points.txt`` -- "Entry Point"/Plugin Metadata

=====================================================

This is a "sectioned" text file, whose contents encode the

``entry_points`` keyword supplied to ``setup()``. All sections are

named, as the section names specify the entry point groups in which the

corresponding section's entry points are registered.

Each section is a sequence of "entry point" lines, each parseable using

the ``EntryPoint.parse`` classmethod; please see the ``pkg_resources``

manual for the complete entry point parsing syntax.

Note that it is not necessary to parse this file directly; the

``pkg_resources`` module provides a variety of APIs to locate and load

entry points automatically. Please see the setuptools and

``pkg_resources`` manuals for details on the nature and uses of entry

points.

The ``scripts`` Subdirectory

============================

This directory is currently only created for ``.egg`` files built by

the setuptools ``bdist_egg`` command. It will contain copies of all

of the project's "traditional" scripts (i.e., those specified using the

``scripts`` keyword to ``setup()``). This is so that they can be

reconstituted when an ``.egg`` file is installed.

The scripts are placed here using the disutils' standard

``install_scripts`` command, so any ``#!`` lines reflect the Python

installation where the egg was built. But instead of copying the

scripts to the local script installation directory, EasyInstall writes

short wrapper scripts that invoke the original scripts from inside the

egg, after ensuring that sys.path includes the egg and any eggs it

depends on. For more about `script wrappers`_, see the section below on

`Installation and Path Management Issues`_.

Zip Support Metadata

====================

``native_libs.txt``

-------------------

A list of C extensions and other dynamic link libraries contained in

the egg, one per line. Paths are ``/``-separated and relative to the

egg's base location.

This file is generated as part of ``bdist_egg`` processing, and as such

only appears in ``.egg`` files (and ``.egg`` directories created by

unpacking them). It is used to ensure that all libraries are extracted

from a zipped egg at the same time, in case there is any direct linkage

between them. Please see the `Zip File Issues`_ section below for more

information on library and resource extraction from ``.egg`` files.

``eager_resources.txt``

-----------------------

A list of resource files and/or directories, one per line, as specified

via the ``eager_resources`` keyword to ``setup()``. Paths are

``/``-separated and relative to the egg's base location.

Resource files or directories listed here will be extracted

simultaneously, if any of the named resources are extracted, or if any

native libraries listed in ``native_libs.txt`` are extracted. Please

see the setuptools manual for details on what this feature is used for

and how it works, as well as the `Zip File Issues`_ section below.

``zip-safe`` and ``not-zip-safe``

---------------------------------

These are zero-length files, and either one or the other should exist.

If ``zip-safe`` exists, it means that the project will work properly

when installedas an ``.egg`` zipfile, and conversely the existence of

``not-zip-safe`` means the project should not be installed as an

``.egg`` file. The ``zip_safe`` option to setuptools' ``setup()``

determines which file will be written. If the option isn't provided,

setuptools attempts to make its own assessment of whether the package

can work, based on code and content analysis.

If neither file is present at installation time, EasyInstall defaults

to assuming that the project should be unzipped. (Command-line options

to EasyInstall, however, take precedence even over an existing

``zip-safe`` or ``not-zip-safe`` file.)

Note that these flag files appear only in ``.egg`` files generated by

``bdist_egg``, and in ``.egg`` directories created by unpacking such an

``.egg`` file.

``top_level.txt`` -- Conflict Management Metadata

=================================================

This file is a list of the top-level module or package names provided

by the project, one Python identifier per line.

Subpackages are not included; a project containing both a ``foo.bar``

and a ``foo.baz`` would include only one line, ``foo``, in its

``top_level.txt``.

This data is used by ``pkg_resources`` at runtime to issue a warning if

an egg is added to ``sys.path`` when its contained packages may have

already been imported.

(It was also once used to detect conflicts with non-egg packages at

installation time, but in more recent versions, setuptools installs eggs

in such a way that they always override non-egg packages, thus

preventing a problem from arising.)

``SOURCES.txt`` -- Source Files Manifest

========================================

This file is roughly equivalent to the distutils' ``MANIFEST`` file.

The differences are as follows:

* The filenames always use ``/`` as a path separator, which must be

converted back to a platform-specific path whenever they are read.

* The file is automatically generated by setuptools whenever the

``egg_info`` or ``sdist`` commands are run, and it is *not*

user-editable.

Although this metadata is included with distributed eggs, it is not

actually used at runtime for any purpose. Its function is to ensure

that setuptools-built *source* distributions can correctly discover

what files are part of the project's source, even if the list had been

generated using revision control metadata on the original author's

system.

In other words, ``SOURCES.txt`` has little or no runtime value for being

included in distributed eggs, and it is possible that future versions of

the ``bdist_egg`` and ``install_egg_info`` commands will strip it before

installation or distribution. Therefore, do not rely on its being

available outside of an original source directory or source

distribution.

------------------------------

Other Technical Considerations

------------------------------

Zip File Issues

===============

Although zip files resemble directories, they are not fully

substitutable for them. Most platforms do not support loading dynamic

link libraries contained in zipfiles, so it is not possible to directly

import C extensions from ``.egg`` zipfiles. Similarly, there are many

existing libraries -- whether in Python or C -- that require actual

operating system filenames, and do not work with arbitrary "file-like"

objects or in-memory strings, and thus cannot operate directly on the

contents of zip files.

To address these issues, the ``pkg_resources`` module provides a

"resource API" to support obtaining either the contents of a resource,

or a true operating system filename for the resource. If the egg

containing the resource is a directory, the resource's real filename

is simply returned. However, if the egg is a zipfile, then the

resource is first extracted to a cache directory, and the filename

within the cache is returned.

The cache directory is determined by the ``pkg_resources`` API; please

see the ``set_cache_path()`` and ``get_default_cache()`` documentation

for details.

The Extraction Process

----------------------

Resources are extracted to a cache subdirectory whose name is based

on the enclosing ``.egg`` filename and the path to the resource. If

there is already a file of the correct name, size, and timestamp, its

filename is returned to the requester. Otherwise, the desired file is

extracted first to a temporary name generated using

``mkstemp(".$extract",target_dir)``, and then its timestamp is set to

match the one in the zip file, before renaming it to its final name.

(Some collision detection and resolution code is used to handle the

fact that Windows doesn't overwrite files when renaming.)

If a resource directory is requested, all of its contents are

recursively extracted in this fashion, to ensure that the directory

name can be used as if it were valid all along.

If the resource requested for extraction is listed in the

``native_libs.txt`` or ``eager_resources.txt`` metadata files, then

*all* resources listed in *either* file will be extracted before the

requested resource's filename is returned, thus ensuring that all

C extensions and data used by them will be simultaneously available.

Extension Import Wrappers

-------------------------

Since Python's built-in zip import feature does not support loading

C extension modules from zipfiles, the setuptools ``bdist_egg`` command

generates special import wrappers to make it work.

The wrappers are ``.py`` files (along with corresponding ``.pyc``

and/or ``.pyo`` files) that have the same module name as the

corresponding C extension. These wrappers are located in the same

package directory (or top-level directory) within the zipfile, so that

say, ``foomodule.so`` will get a corresponding ``foo.py``, while

``bar/baz.pyd`` will get a corresponding ``bar/baz.py``.

These wrapper files contain a short stanza of Python code that asks

``pkg_resources`` for the filename of the corresponding C extension,

then reloads the module using the obtained filename. This will cause

``pkg_resources`` to first ensure that all of the egg's C extensions

(and any accompanying "eager resources") are extracted to the cache

before attempting to link to the C library.

Note, by the way, that ``.egg`` directories will also contain these

wrapper files. However, Python's default import priority is such that

C extensions take precedence over same-named Python modules, so the

import wrappers are ignored unless the egg is a zipfile.

Installation and Path Management Issues

=======================================

Python's initial setup of ``sys.path`` is very dependent on the Python

version and installation platform, as well as how Python was started

(i.e., script vs. ``-c`` vs. ``-m`` vs. interactive interpreter).

In fact, Python also provides only two relatively robust ways to affect

``sys.path`` outside of direct manipulation in code: the ``PYTHONPATH``

environment variable, and ``.pth`` files.

However, with no cross-platform way to safely and persistently change

environment variables, this leaves ``.pth`` files as EasyInstall's only

real option for persistent configuration of ``sys.path``.

But ``.pth`` files are rather strictly limited in what they are allowed

to do normally. They add directories only to the *end* of ``sys.path``,

after any locally-installed ``site-packages`` directory, and they are

only processed *in* the ``site-packages`` directory to start with.

This is a double whammy for users who lack write access to that

directory, because they can't create a ``.pth`` file that Python will

read, and even if a sympathetic system administrator adds one for them

that calls ``site.addsitedir()`` to allow some other directory to

contain ``.pth`` files, they won't be able to install newer versions of

anything that's installed in the systemwide ``site-packages``, because

their paths will still be added *after* ``site-packages``.

So EasyInstall applies two workarounds to solve these problems.

The first is that EasyInstall leverages ``.pth`` files' "import" feature

to manipulate ``sys.path`` and ensure that anything EasyInstall adds

to a ``.pth`` file will always appear before both the standard library

and the local ``site-packages`` directories. Thus, it is always

possible for a user who can write a Python-read ``.pth`` file to ensure

that their packages come first in their own environment.

Second, when installing to a ``PYTHONPATH`` directory (as opposed to

a "site" directory like ``site-packages``) EasyInstall will also install

a special version of the ``site`` module. Because it's in a

``PYTHONPATH`` directory, this module will get control before the

standard library version of ``site`` does. It will record the state of

``sys.path`` before invoking the "real" ``site`` module, and then

afterwards it processes any ``.pth`` files found in ``PYTHONPATH``

directories, including all the fixups needed to ensure that eggs always

appear before the standard library in sys.path, but are in a relative

order to one another that is defined by their ``PYTHONPATH`` and

``.pth``-prescribed sequence.

The net result of these changes is that ``sys.path`` order will be

as follows at runtime:

1. The ``sys.argv[0]`` directory, or an emtpy string if no script

is being executed.

2. All eggs installed by EasyInstall in any ``.pth`` file in each

``PYTHONPATH`` directory, in order first by ``PYTHONPATH`` order,

then normal ``.pth`` processing order (which is to say alphabetical

by ``.pth`` filename, then by the order of listing within each

``.pth`` file).

3. All eggs installed by EasyInstall in any ``.pth`` file in each "site"

directory (such as ``site-packages``), following the same ordering

rules as for the ones on ``PYTHONPATH``.

4. The ``PYTHONPATH`` directories themselves, in their original order

5. Any paths from ``.pth`` files found on ``PYTHONPATH`` that were *not*

eggs installed by EasyInstall, again following the same relative

ordering rules.

6. The standard library and "site" directories, along with the contents

of any ``.pth`` files found in the "site" directories.

Notice that sections 1, 4, and 6 comprise the "normal" Python setup for

``sys.path``. Sections 2 and 3 are inserted to support eggs, and

section 5 emulates what the "normal" semantics of ``.pth`` files on

``PYTHONPATH`` would be if Python natively supported them.

For further discussion of the tradeoffs that went into this design, as

well as notes on the actual magic inserted into ``.pth`` files to make

them do these things, please see also the following messages to the

distutils-SIG mailing list:

* http://mail.python.org/pipermail/distutils-sig/2006-February/006026.html

* http://mail.python.org/pipermail/distutils-sig/2006-March/006123.html

Script Wrappers

---------------

EasyInstall never directly installs a project's original scripts to

a script installation directory. Instead, it writes short wrapper

scripts that first ensure that the project's dependencies are active

on sys.path, before invoking the original script. These wrappers

have a #! line that points to the version of Python that was used to

install them, and their second line is always a comment that indicates

the type of script wrapper, the project version required for the script

to run, and information identifying the script to be invoked.

The format of this marker line is::

"# EASY-INSTALL-" script_type ": " tuple_of_strings "\n"

The ``script_type`` is one of ``SCRIPT``, ``DEV-SCRIPT``, or

``ENTRY-SCRIPT``. The ``tuple_of_strings`` is a comma-separated

sequence of Python string constants. For ``SCRIPT`` and ``DEV-SCRIPT``

wrappers, there are two strings: the project version requirement, and

the script name (as a filename within the ``scripts`` metadata

directory). For ``ENTRY-SCRIPT`` wrappers, there are three:

the project version requirement, the entry point group name, and the

entry point name. (See the "Automatic Script Creation" section in the

setuptools manual for more information about entry point scripts.)

In each case, the project version requirement string will be a string

parseable with the ``pkg_resources`` modules' ``Requirement.parse()``

classmethod. The only difference between a ``SCRIPT`` wrapper and a

``DEV-SCRIPT`` is that a ``DEV-SCRIPT`` actually executes the original

source script in the project's source tree, and is created when the

"setup.py develop" command is run. A ``SCRIPT`` wrapper, on the other

hand, uses the "installed" script written to the ``EGG-INFO/scripts``

subdirectory of the corresponding ``.egg`` zipfile or directory.

(``.egg-info`` eggs do not have script wrappers associated with them,

except in the "setup.py develop" case.)

The purpose of including the marker line in generated script wrappers is

to facilitate introspection of installed scripts, and their relationship

to installed eggs. For example, an uninstallation tool could use this

data to identify what scripts can safely be removed, and/or identify

what scripts would stop working if a particular egg is uninstalled.

ShowText of this page
EditText of this page
FindPage by browsing, title search , text search or an index
Or try one of these actions: AttachFile, DeletePage, LikePages, LocalSiteMap, SpellCheck