{{template>:doctable
    | name = SPTrans
    | version = 0.1.0
    | accountable = Rogério Schneider
    | depdency = None
}}

===== SPTrans =====
A prefeitura de São Paulo fornece uma API para consulta de posicionamento da frota de ônibus que atende ao transporte público municipal. A API Olho Vivo é de acesso aberto, mediante cadastro do desenvolvedor e suas aplicações.

===== Links importantes =====
  * [[https://bitbucket.org/endler/ext-pubtrans|Repo Git EXT-PubTrans]] - Código preservado no branch ''sptrans'' e na tag ''20140916_0244_posicao-dl-sptrans-only''. Como o repositório evoluiu para um serviço mais genérico, para outras APIs, seu nome foi alterado para ''EXT-PubTrans''.

  * [[http://www.sptrans.com.br/desenvolvedores|Área para desenvolvedores da API Olho Vivo]] - Utilize como primeiro passo, para criar a sua credencial pessoal de acesso e registrar as suas aplicações em uma conta.

  * [[http://www.sptrans.com.br/desenvolvedores/APIOlhoVivo/Documentacao.aspx|Como começar]] - Passo a passo para iniciar o uso da API.

  * [[http://www.sptrans.com.br/desenvolvedores/APIOlhoVivo/Documentacao.aspx?1|Documentação da API Olho Vivo]] - Documentação completa com todas as rotas expostas pela API Olho Vivo. Contém exemplos de uso para cada serviço.

  * [[http://www.sptrans.com.br/desenvolvedores/GTFS.aspx|GTFS (1)]] [[https://developers.google.com/transit/gtfs/reference?hl=pt-br|GTFS (2)]] - Referências para o formato de dados da API.

===== Exemplos de uso =====
Abaixo temos alguns exemplos de uso da API Olho Vivo.

==== Endereço da API ====
Endereço principal da API. Pode mudar a rota /v0 variando o número de acordo com a versão da API.

  http://api.olhovivo.sptrans.com.br/v0

==== Preparação do ambiente ====
É preciso exportar o token da sua aplicação antes de poder reproduzir os comandos dos exemplos abaixo. Todos os exemplos utilizam a variável de ambiente $TOKEN para ler o valor correto da chave de acesso.

  export TOKEN=<token_da_sua_app>

==== Login ====
Antes de consultar a API é preciso iniciar um processo de autenticação. Após o POST de login é preciso gerenciar corretamente os cookies da sessão HTTP para que a API responda corretamente.

<file bash login.sh>
curl -sv -X POST -d '' -b /tmp/cookie-jar.txt -c /tmp/cookie-jar.txt "http://api.olhovivo.sptrans.com.br/v0/Login/Autenticar?token=$TOKEN"

> POST /v0/Login/Autenticar?token=$TOKEN HTTP/1.1
> User-Agent: curl/7.22.0 (i686-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: api.olhovivo.sptrans.com.br
> Accept: */*
> Content-Length: 0
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Type: application/json; charset=utf-8
< Expires: -1
< Server: Microsoft-IIS/7.5
< X-AspNet-Version: 4.0.30319
< Set-Cookie: apiCredentials=2FCC66D5E42C11C64366D96FE275E5BF2B4B1C93E8A3FF7E15437CA5FF366DF0A7B351178CA1D448A2161A636E396DC833AFBB723119A22D3F169233175DC949AB7C641B171F3284227C33A4BD0B9C5DBEF04F70368ED308D0F3502866BDCB9F93FC74F8E3323AB44081770BDBAAADB7447951D6EEDC69B14301B4A0A56C9B54D72A727F0C3E71252D49BC3954E13BE8C328D91A2D42E95AD904B4EDD50B7278026F5CEA4618DBCF325DE9ABC11FC958BDF65FBD210121BFF07AAF36F56CAE8E189C3872BAAA4F74AD011505589EA9EC; path=/; HttpOnly
< X-Powered-By: ASP.NET
< Date: Sat, 06 Sep 2014 07:48:04 GMT
< Content-Length: 4
<
true
</file>

==== Linhas (buscar) ====
Retorna códigos de linhas a partir da pesquisa de um termo.

<file bash linhas-buscar.sh>
curl -sv -b /tmp/cookie-jar.txt -c /tmp/cookie-jar.txt "http://api.olhovivo.sptrans.com.br/v0/Linha/Buscar?termosBusca=Liberdade" | jq .

> GET /v0/Linha/Buscar?termosBusca=Liberdade HTTP/1.1
> User-Agent: curl/7.22.0 (i686-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: api.olhovivo.sptrans.com.br
> Accept: */*
> Cookie: apiCredentials=2FCC66D5E42C11C64366D96FE275E5BF2B4B1C93E8A3FF7E15437CA5FF366DF0A7B351178CA1D448A2161A636E396DC833AFBB723119A22D3F169233175DC949AB7C641B171F3284227C33A4BD0B9C5DBEF04F70368ED308D0F3502866BDCB9F93FC74F8E3323AB44081770BDBAAADB7447951D6EEDC69B14301B4A0A56C9B54D72A727F0C3E71252D49BC3954E13BE8C328D91A2D42E95AD904B4EDD50B7278026F5CEA4618DBCF325DE9ABC11FC958BDF65FBD210121BFF07AAF36F56CAE8E189C3872BAAA4F74AD011505589EA9EC
>
< HTTP/1.1 200 OK
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Type: application/json; charset=utf-8
< Expires: -1
< Server: Microsoft-IIS/7.5
< X-AspNet-Version: 4.0.30319
< X-Powered-By: ASP.NET
< Date: Sat, 06 Sep 2014 07:56:43 GMT
< Content-Length: 663
<
[
  {
    "CodigoLinha": 692,
    "Circular": true,
    "Letreiro": "2123",
    "Sentido": 1,
    "Tipo": 10,
    "DenominacaoTPTS": "METRÔ LIBERDADE",
    "DenominacaoTSTP": "VILA MEDEIROS",
    "Informacoes": null
  },
  {
    "CodigoLinha": 33460,
    "Circular": true,
    "Letreiro": "2123",
    "Sentido": 2,
    "Tipo": 10,
    "DenominacaoTPTS": "METRÔ LIBERDADE",
    "DenominacaoTSTP": "VILA MEDEIROS",
    "Informacoes": null
  },
  {
    "CodigoLinha": 693,
    "Circular": true,
    "Letreiro": "2127",
    "Sentido": 1,
    "Tipo": 10,
    "DenominacaoTPTS": "METRÔ LIBERDADE",
    "DenominacaoTSTP": "JD. BRASIL",
    "Informacoes": null
  },
  {
    "CodigoLinha": 33461,
    "Circular": true,
    "Letreiro": "2127",
    "Sentido": 2,
    "Tipo": 10,
    "DenominacaoTPTS": "METRÔ LIBERDADE",
    "DenominacaoTSTP": "JD. BRASIL",
    "Informacoes": null
  }
]
</file>

==== Paradas (buscar) ====
Retorna códigos de paradas a partir da pesquisa de um termo.

<file bash paradas-buscar.sh>
curl -sv -b /tmp/cookie-jar.txt -c /tmp/cookie-jar.txt "http://api.olhovivo.sptrans.com.br/v0/Parada/Buscar?termosBusca=Pacaembu" | jq .

> GET /v0/Parada/Buscar?termosBusca=Pacaembu HTTP/1.1
> User-Agent: curl/7.22.0 (i686-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: api.olhovivo.sptrans.com.br
> Accept: */*
> Cookie: apiCredentials=2FCC66D5E42C11C64366D96FE275E5BF2B4B1C93E8A3FF7E15437CA5FF366DF0A7B351178CA1D448A2161A636E396DC833AFBB723119A22D3F169233175DC949AB7C641B171F3284227C33A4BD0B9C5DBEF04F70368ED308D0F3502866BDCB9F93FC74F8E3323AB44081770BDBAAADB7447951D6EEDC69B14301B4A0A56C9B54D72A727F0C3E71252D49BC3954E13BE8C328D91A2D42E95AD904B4EDD50B7278026F5CEA4618DBCF325DE9ABC11FC958BDF65FBD210121BFF07AAF36F56CAE8E189C3872BAAA4F74AD011505589EA9EC
>
< HTTP/1.1 200 OK
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Type: application/json; charset=utf-8
< Expires: -1
< Server: Microsoft-IIS/7.5
< Set-Cookie: apiCredentials=27F85582A2625CF61095A99B3CBCF08EA6AE4EB9EA44FA370077D7EAB1D359E1FB18432C7D679A8FFE93C19C7FC7961AF744FFE2986B0CDC0A47484E0DDEEA6D9769F13246F5F6E48A8DF1CA23B36DC97DE4ADA4E232BDD245FF5E048D9780EF5DC296A86C7B001DFE99D6E8E35EC7CA11EB454D02A4E2A75BE5CCF7224A408C63BC7234D0BB5015DAC054C19746F252C1E6DCED90A70C5CA6A28C49AEBFF0E99C4EC307D2845A7FF5535CFB1EE960FA759F4F05F928D69F7687643384DED60A0D887DCC00980154913962DDD4167977; path=/; HttpOnly
< X-AspNet-Version: 4.0.30319
< X-Powered-By: ASP.NET
< Date: Sat, 06 Sep 2014 08:07:46 GMT
< Content-Length: 275
<
[
  {
    "CodigoParada": 700016791,
    "Nome": "PACAEMBU B/C",
    "Endereco": "R FRANCISCO ESTACIO FORTES/ AV PACAEMBU",
    "Latitude": -23.532068,
    "Longitude": -46.660957
  },
  {
    "CodigoParada": 700016792,
    "Nome": "PACAEMBU C/B",
    "Endereco": "AV PACAEMBU/ R TUPI",
    "Latitude": -23.531864,
    "Longitude": -46.660859
  }
]
</file>

==== Paradas (corredor) ====
JSON com todos os corredores será salvo no arquivo data/paradas-por-corredor.txt.

<file bash paradas-corredor.sh>
for x in $(seq 11)
do
    echo "- Corredor $x"
    curl -sv -b /tmp/cookie-jar.txt -c /tmp/cookie-jar.txt "http://api.olhovivo.sptrans.com.br/v0/Parada/BuscarParadasPorCorredor?codigoCorredor=$x" \
    | jq .
    echo
done | tee data/paradas-por-corredor.txt
</file>

==== Corredores (listar) ====
Lista os corredores inteligentes.

<file bash corredores-listar.sh>
curl -sv -b /tmp/cookie-jar.txt -c /tmp/cookie-jar.txt "http://api.olhovivo.sptrans.com.br/v0/Corredor" | jq .

> GET /v0/Corredor HTTP/1.1
> User-Agent: curl/7.22.0 (i686-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: api.olhovivo.sptrans.com.br
> Accept: */*
> Cookie: apiCredentials=2E423A1C7F3FE250369AC103F20088EB86A96B537B12800501F1A7958D72DD0DCF4E1FA5565C97EA39940C25143C5426951DCE46D355882EB418484D5F75EF1418854E023CB05B5904671AB9A9A3FB70867CDB7573B8F86ECA803615A101A9CE2D0A6C52D801C23B43A27605136CD458EDA914FFAE8AF94A907C93FB63027D4A3DCAE8FA03867399481A4DC6FCC68F4AE59EC51059739909C883AF2C15ABAC0EF2B8E9C90DBDBC62C700D1DE5A3A6C5023435E983C99AF91EF0A234AC18394F13742670249B93E96C21A0ED2DDA7BC98
>
< HTTP/1.1 200 OK
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Type: application/json; charset=utf-8
< Expires: -1
< Server: Microsoft-IIS/7.5
< X-AspNet-Version: 4.0.30319
< X-Powered-By: ASP.NET
< Date: Sat, 06 Sep 2014 08:21:32 GMT
< Content-Length: 364
<
[
  {
    "CodCot": 0,
    "CodCorredor": 8,
    "Nome": "Campo Limpo"
  },
  {
    "CodCot": 0,
    "CodCorredor": 9,
    "Nome": "Expresso Tiradentes"
  },
  {
    "CodCot": 0,
    "CodCorredor": 3,
    "Nome": "Inajar de Souza"
  },
  {
    "CodCot": 0,
    "CodCorredor": 7,
    "Nome": "Parelheiros"
  },
  {
    "CodCot": 0,
    "CodCorredor": 1,
    "Nome": "Pirituba"
  },
  {
    "CodCot": 0,
    "CodCorredor": 2,
    "Nome": "Santo Amaro"
  },
  {
    "CodCot": 0,
    "CodCorredor": 10,
    "Nome": "Paes de Barros"
  }
]
</file>

==== Posição dos veículos (por linha) ====
Retorna a posição dos veículos que estão atendendo a uma determinada linha.

Este é o serviço mais importante pois fornece as coordenadas de posicionamento dos veículos em serviço.

<file bash posicao-linha.sh>
curl -sv -b /tmp/cookie-jar.txt -c /tmp/cookie-jar.txt "http://api.olhovivo.sptrans.com.br/v0/Posicao?codigoLinha=33461" | jq .

> GET /v0/Posicao?codigoLinha=33461 HTTP/1.1
> User-Agent: curl/7.22.0 (i686-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: api.olhovivo.sptrans.com.br
> Accept: */*
> Cookie: apiCredentials=2E423A1C7F3FE250369AC103F20088EB86A96B537B12800501F1A7958D72DD0DCF4E1FA5565C97EA39940C25143C5426951DCE46D355882EB418484D5F75EF1418854E023CB05B5904671AB9A9A3FB70867CDB7573B8F86ECA803615A101A9CE2D0A6C52D801C23B43A27605136CD458EDA914FFAE8AF94A907C93FB63027D4A3DCAE8FA03867399481A4DC6FCC68F4AE59EC51059739909C883AF2C15ABAC0EF2B8E9C90DBDBC62C700D1DE5A3A6C5023435E983C99AF91EF0A234AC18394F13742670249B93E96C21A0ED2DDA7BC98
>
< HTTP/1.1 200 OK
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Type: application/json; charset=utf-8
< Expires: -1
< Server: Microsoft-IIS/7.5
< X-AspNet-Version: 4.0.30319
< X-Powered-By: ASP.NET
< Date: Sat, 06 Sep 2014 08:32:00 GMT
< Content-Length: 153
<
{
  "hr": "05:32",
  "vs": [
    {
      "p": "22850",
      "a": true,
      "py": -23.516589875,
      "px": -46.604841875000005
    },
    {
      "p": "22822",
      "a": true,
      "py": -23.554221000000002,
      "px": -46.6331835
    }
  ]
}
</file>

==== Previsão de chegada dos veículos (por linha) ====
Dada uma linha, é informada a previsão de chegada e posicionamento atual dos veículos que a atendem.

<file bash previsao-linha.sh>
curl -sv -b /tmp/cookie-jar.txt -c /tmp/cookie-jar.txt "http://api.olhovivo.sptrans.com.br/v0/Previsao/Linha?codigoLinha=33461" | jq .

> GET /v0/Previsao/Linha?codigoLinha=33461 HTTP/1.1
> User-Agent: curl/7.22.0 (i686-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: api.olhovivo.sptrans.com.br
> Accept: */*
> Cookie: apiCredentials=2E423A1C7F3FE250369AC103F20088EB86A96B537B12800501F1A7958D72DD0DCF4E1FA5565C97EA39940C25143C5426951DCE46D355882EB418484D5F75EF1418854E023CB05B5904671AB9A9A3FB70867CDB7573B8F86ECA803615A101A9CE2D0A6C52D801C23B43A27605136CD458EDA914FFAE8AF94A907C93FB63027D4A3DCAE8FA03867399481A4DC6FCC68F4AE59EC51059739909C883AF2C15ABAC0EF2B8E9C90DBDBC62C700D1DE5A3A6C5023435E983C99AF91EF0A234AC18394F13742670249B93E96C21A0ED2DDA7BC98
>
< HTTP/1.1 200 OK
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Type: application/json; charset=utf-8
< Expires: -1
< Server: Microsoft-IIS/7.5
< Set-Cookie: apiCredentials=3E8646703FFE5CDFF03C05CED150E456D3914E64FFDC5607512B73DAC07D129F974DFB96F799F877B30BD12CDF85CAA45A9B3E89C682C87C087F6E8E12EACD7269E601867D252DDFCC2484FE571923366FCE4FD57B9D6C11A52B44BADA62088A84CF9514D10440CD3CBF6E6C9A400CAE5BBC48B9D5EC9B9CFF5B8A823F3C4155E1C7E40CBB711C58425C0E6DBCF90E0D9A48BC026DE30F7FC07534BF59ECBA76665E2181B6676F1CAC87DCE1B42A13A131479EB75943DA3FD515DD30650372891957EB57C59BAACB3839B91333A44803; path=/; HttpOnly
< X-AspNet-Version: 4.0.30319
< X-Powered-By: ASP.NET
< Date: Sat, 06 Sep 2014 08:47:13 GMT
< Content-Length: 1596
<
{
  "hr": "05:47",
  "ps": [
    {
      "cp": 910003786,
      "np": null,
      "py": -23.49562,
      "px": -46.585261,
      "vs": [
        {
          "p": "22822",
          "t": "06:01",
          "a": true,
          "py": -23.525668333333336,
          "px": -46.611473333333336
        }
      ]
    },
    {
      "cp": 910003782,
      "np": null,
      "py": -23.49503,
      "px": -46.580862,
      "vs": [
        {
          "p": "22822",
          "t": "06:02",
          "a": true,
          "py": -23.525668333333336,
          "px": -46.611473333333336
        }
      ]
    },
    {
      "cp": 910003778,
      "np": null,
      "py": -23.495193,
      "px": -46.578781,
      "vs": [
        {
          "p": "22822",
          "t": "06:02",
          "a": true,
          "py": -23.525668333333336,
          "px": -46.611473333333336
        }
      ]
    },
    {
      "cp": 940004421,
      "np": null,
      "py": -23.496566,
      "px": -46.575964,
      "vs": [
        {
          "p": "22822",
          "t": "06:03",
          "a": true,
          "py": -23.525668333333336,
          "px": -46.611473333333336
        }
      ]
    },
    {
      "cp": 940004358,
      "np": null,
      "py": -23.494704,
      "px": -46.5756,
      "vs": [
        {
          "p": "22822",
          "t": "06:03",
          "a": true,
          "py": -23.525668333333336,
          "px": -46.611473333333336
        }
      ]
    },
    {
      "cp": 940004359,
      "np": null,
      "py": -23.48946,
      "px": -46.57264,
      "vs": [
        {
          "p": "22822",
          "t": "06:05",
          "a": true,
          "py": -23.525668333333336,
          "px": -46.611473333333336
        }
      ]
    },
    {
      "cp": 940004032,
      "np": null,
      "py": -23.489418,
      "px": -46.570809,
      "vs": [
        {
          "p": "22822",
          "t": "06:05",
          "a": true,
          "py": -23.525668333333336,
          "px": -46.611473333333336
        }
      ]
    },
    {
      "cp": 940003891,
      "np": null,
      "py": -23.489401,
      "px": -46.56986,
      "vs": [
        {
          "p": "22822",
          "t": "06:06",
          "a": true,
          "py": -23.525668333333336,
          "px": -46.611473333333336
        }
      ]
    },
    {
      "cp": 910003784,
      "np": "",
      "py": -23.494814,
      "px": -46.583202,
      "vs": [
        {
          "p": "22822",
          "t": "06:01",
          "a": true,
          "py": -23.525668333333336,
          "px": -46.611473333333336
        }
      ]
    },
    {
      "cp": 9412668,
      "np": "",
      "py": -23.490836,
      "px": -46.574455,
      "vs": [
        {
          "p": "22822",
          "t": "06:04",
          "a": true,
          "py": -23.525668333333336,
          "px": -46.611473333333336
        }
      ]
    },
    {
      "cp": 800016588,
      "np": "SÉ/BOMBEIROS",
      "py": -23.550694,
      "px": -46.631906,
      "vs": []
    }
  ]
}
</file>

==== Previsão de chegada dos veículos (por parada) ====
Dada uma parada, é informada a previsão de chegada e posicionamento atual dos veículos que a atendem.

Este serviço foi utilizado em um script mais elaborado para descobrir a listagem completa de linhas, uma vez que apenas a listagem completa de paradas é fornecida.

<file bash previsao-parada.sh>
curl -sv -b /tmp/cookie-jar.txt -c /tmp/cookie-jar.txt "http://api.olhovivo.sptrans.com.br/v0/Previsao/Parada?codigoParada=700016792" | jq .

> GET /v0/Previsao/Parada?codigoParada=700016792 HTTP/1.1
> User-Agent: curl/7.22.0 (i686-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: api.olhovivo.sptrans.com.br
> Accept: */*
> Cookie: apiCredentials=E87C1CA3864AF6323A05D598B01AF2539D58028DF6E9D494759AB93B264D27C80ABC787963640240B3D7065356DF49991474998102EC4625D1CFD156B0BD80A0DEDCD3EDE83A466A9CCC82168D38198D194EFEA4D6AF6691C604AC4096C6CFBF2DDC267959DC8752EA8937A888849DF7F51088BECA910E2285CA94CA37E6A9170B89B7D8BB2DC25AF43CDE2032C76423D7BD3E19727FB407C6C7FFDAC6ED6A64262012C8CB87428819E3BF08FC68634DC4AE2DE591C03AE7DADE86883E933A7214991747E9EF2499C909BAE6449ADF9D
>
< HTTP/1.1 200 OK
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Type: application/json; charset=utf-8
< Expires: -1
< Server: Microsoft-IIS/7.5
< X-AspNet-Version: 4.0.30319
< X-Powered-By: ASP.NET
< Date: Sat, 06 Sep 2014 08:50:22 GMT
< Content-Length: 861
<
{
  "hr": "05:50",
  "p": {
    "cp": 700016792,
    "np": "PACAEMBU C/B",
    "py": -23.531864,
    "px": -46.660859,
    "l": [
      {
        "c": "8696-41",
        "cl": 33218,
        "sl": 2,
        "lt0": "PCA.RAMOS DE AZEVEDO",
        "lt1": "JARAGUA",
        "qv": 1,
        "vs": [
          {
            "p": "11695",
            "t": "05:55",
            "a": false,
            "py": -23.538629999999998,
            "px": -46.64681166666666
          }
        ]
      },
      {
        "c": "8594-10",
        "cl": 33200,
        "sl": 2,
        "lt0": "PCA.RAMOS DE AZEVEDO",
        "lt1": "CID. D'ABRIL",
        "qv": 1,
        "vs": [
          {
            "p": "11816",
            "t": "05:55",
            "a": true,
            "py": -23.539899999999996,
            "px": -46.64444
          }
        ]
      },
      {
        "c": "875A-10",
        "cl": 609,
        "sl": 1,
        "lt0": "PERDIZES (VIA ARATÃS)",
        "lt1": "AEROPORTO",
        "qv": 2,
        "vs": [
          {
            "p": "62214",
            "t": "06:02",
            "a": true,
            "py": -23.553359999999998,
            "px": -46.66026166666667
          },
          {
            "p": "62008",
            "t": "06:34",
            "a": true,
            "py": -23.618095,
            "px": -46.66196166666667
          }
        ]
      },
      {
        "c": "874T-10",
        "cl": 307,
        "sl": 1,
        "lt0": "LAPA",
        "lt1": "IPIRANGA",
        "qv": 1,
        "vs": [
          {
            "p": "51645",
            "t": "06:16",
            "a": true,
            "py": -23.588033333333335,
            "px": -46.63051666666667
          }
        ]
      }
    ]
  }
}
</file>

==== Previsão de chegada dos veículos (por parada e linha) ====
Dada uma parada e uma linha, é informada a previsão de chegada e posicionamento atual dos veículos que as atendem.

<file bash previsao-parada-e-linha.sh>
curl -sv -b /tmp/cookie-jar.txt -c /tmp/cookie-jar.txt "http://api.olhovivo.sptrans.com.br/v0/Previsao?codigoParada=700016792&codigoLinha=307" | jq .

> GET /v0/Previsao?codigoParada=700016792&codigoLinha=307 HTTP/1.1
> User-Agent: curl/7.22.0 (i686-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: api.olhovivo.sptrans.com.br
> Accept: */*
> Cookie: apiCredentials=E87C1CA3864AF6323A05D598B01AF2539D58028DF6E9D494759AB93B264D27C80ABC787963640240B3D7065356DF49991474998102EC4625D1CFD156B0BD80A0DEDCD3EDE83A466A9CCC82168D38198D194EFEA4D6AF6691C604AC4096C6CFBF2DDC267959DC8752EA8937A888849DF7F51088BECA910E2285CA94CA37E6A9170B89B7D8BB2DC25AF43CDE2032C76423D7BD3E19727FB407C6C7FFDAC6ED6A64262012C8CB87428819E3BF08FC68634DC4AE2DE591C03AE7DADE86883E933A7214991747E9EF2499C909BAE6449ADF9D
>
< HTTP/1.1 200 OK
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Type: application/json; charset=utf-8
< Expires: -1
< Server: Microsoft-IIS/7.5
< X-AspNet-Version: 4.0.30319
< X-Powered-By: ASP.NET
< Date: Sat, 06 Sep 2014 08:52:03 GMT
< Content-Length: 245
<
{
  "hr": "05:52",
  "p": {
    "cp": 700016792,
    "np": "PACAEMBU C/B",
    "py": -23.531864,
    "px": -46.660859,
    "l": [
      {
        "c": "874T-10",
        "cl": 307,
        "sl": 1,
        "lt0": "LAPA",
        "lt1": "IPIRANGA",
        "qv": 1,
        "vs": [
          {
            "p": "51645",
            "t": "06:16",
            "a": true,
            "py": -23.581475,
            "px": -46.63818833333333
          }
        ]
      }
    ]
  }
}
</file>

===== Scripts de download automatizado de posicionamento de veículos =====
Foi criado um conjunto de scripts que utiliza uma série de serviços da API Olho Vivo de maneira a manter uma base local atualizada com as posições de veículos fornecidas por GPS.

O propósito de se manter uma base local atualizada é o da utilização desses dados de posicionamento para simulação e análise de movimentação com embasamento em padrões reais de deslocamento urbano.

Para que fosse possível coletar e manter uma amostra de dados de posicionamento, um conjunto de scripts foi desenvolvido. Trata-se de um script de descoberta de linhas, chamado ''update-linhas.sh'' e de um script de download em paralelo, que coleta as posições de veículos em cada linha, chamado ''posicao-dl.rb''.

==== Script  update-linhas.sh ====
Encontra-se no repositório Git do LAC e faz o seguinte processo:

  * Utiliza os arquivos apiref/routes.txt e apiref/stops.txt para obter uma lista de paradas conhecidas. Estes arquivos podem ser obtidos pelo site da API Olho Vivo, na área de download dos arquivos GTFS.
  * De posse da lista de paradas, enumera em cada uma delas quais as previsões de chegada de veículos e salva o resultado em um arquivo. Esta previsão de chegada por parada contém algumas informações, dentre elas, alguns códigos de linhas com atividade no momento.
  * Ao terminar a consulta em todas as paradas, uma lista de linhas ativas é extraída das previsões resultantes. Esta lista de linhas será salva no arquivo data/linhas.txt e será utilizada como entrada por outro script. Este outro script seria o ''posicao-dl.rb'' e é ele o responsável pelo download em massa das posições GPS fornecidas pela API, linha por linha.

Exemplo de execução contínua do script de descoberta de linhas, via cron:
<file bash cron-linhas.sh>
# Executa a cada quatro horas
0 */4 * * * user cd /home/user/sptrans; ./update-linhas.sh <token_da_sua_app>
</file>

==== Script  posicao-dl.rb ====
Encontra-se no repositório Git do LAC e faz o seguinte processo:

  * Utiliza a lista de linhas descoberta pelo script ''update-linhas.sh'', salva em data/linhas.txt, e faz a consulta, linha por linha, das posições de veículos em atividade em cada linha.
  * O download é feito em paralelo e é configurável.
  * O ideal é que o número de threads seja ajustado para terminar o processamento dentro de 85 segundos, uma vez que a API Olho Vivo mantém os dados atualizados com as posições dos veículos nesta mesma frequência.

Exemplo de execução contínua do script de download de posicionamento de veículos, via cron:
<file bash cron-posicao.sh>
# Executa a cada minuto
* * * * * user cd /home/user/sptrans; /usr/bin/unbuffer /home/user/.rvm/gems/ruby-2.1.2@sptrans/wrappers/ruby posicao-dl.rb -t <token_da_sua_app> -d /path/to/data/pos -l data/linhas.txt -w 50
</file>

==== Utilizando os scripts ====

=== update-linhas.sh ===

O script ''update-linhas.sh'' não apresenta maiores dificuldades em seu uso. Basta executar a partir da raiz do repositório Git. É um Bash e é suportado em qualquer distribuição Linux. Foi testado no Ubuntu.

Note que o script ''update-linhas.sh'', ao final da sua execução, cria um commit no Git com o arquivo data/linhas.txt atualizado. Nada é removido do linhas.txt já existente no repositório, apenas as linhas novas descobertas é que serão adicionadas, sem duplicação.

  cd /home/user/sptrans
  ./update-linhas.sh <token_da_sua_app>

=== posicao-dl.rb ===

O script ''posicao-dl.rb'' exige um setup do ambiente local pois se trata de um programa Ruby um pouco mais complexo. Felizmente o instrumental para gerenciar dependências de pacotes na linguagem Ruby é bem poderoso. Basta seguir os passos abaixo e deverá ser possível executar o script em qualquer máquina Linux ou Mac:

  * Instalar o RVM (Ruby Version Manager - http://rvm.io).

  curl -sSL https://get.rvm.io | bash -s stable

  * Abrir uma nova aba ou fazer login para garantir que o RVM seja carregado em um novo shell.
  * Instalar o Ruby 2.1.2.

  rvm install ruby-2.1.2

  * Acessar o diretório raiz do Git e confirmar que o RVM trocou o Ruby e o Gemset correntes.

  cd /
  cd /home/user/sptrans
  rvm current
  (deve retornar: ruby-2.1.2@sptrans)

  * Instalar as dependências.

  bundle

  * Utilizar o ''posicao-dl.rb''.

  ./posicao-dl.rb -h

  Usage:
  
    ./posicao-dl.rb [options]
  
  Examples:
  
    ./posicao-dl.rb -t <token_da_sua_app> -d data/pos -l data/linhas.txt -w 5
    ./posicao-dl.rb -t <token_da_sua_app> -d data/pos -l data/linhas.txt -v
    ./posicao-dl.rb -t <token_da_sua_app> -d data/pos -l data/linhas.txt -vvv
    ./posicao-dl.rb -t <token_da_sua_app> -d data/pos -l data/linhas.txt -w 100 -vvv
  
  Options:
  
    -t, --token             Olho Vivo API token.
    -d, --download_dir      Download dir to store jsons with buses' GPS coordinates.
    -l, --routes_file       File containing routes to query for buses' positioning.
    -w, --threads_num       Number of worker threads for parallel download. (default: 5)
    -v, --verbose           Verbose mode.
    -h, --help              Display this help message.

===== Formato dos JSONs salvos =====
Os arquivos salvos pelo script ''posicao-dl.rb'' seguem o padrão abaixo.

  /path/to/data/pos/p_<id_do_veiculo>.json
  /path/to/data/pos/p_1337.json

<file python p_1337.json>
{
  "p": "1337",
  "d": [
    {
      "t": 1410109464,
      "a": true,
      "x": -46.738139000000004,
      "y": -23.454661
    },
    {
      "t": 1410109525,
      "a": true,
      "x": -46.738139000000004,
      "y": -23.454661
    }
  ]
}
</file>

''p'' é o identificador de um veículo, também está presente no nome do arquivo. Os arquivos são salvos agrupando todas as posições coletadas para um determinado veículo.

''d'' é uma lista de posições coletadas. Tende a crescer conforme a coleta via script é executada.

''t'' é o timestamp (seconds from the epoch / unix timestamp) da data da coleta de uma determinada posição GPS via API. A data expressa o momento da coleta na API, já que a API não informa a data da coleta no veículo.

''a'' true ou false. Não ficou claro pela documentação da API o que exatamente este campo significa. Talvez indique se o veículo estava parado ou em movimento no momento da coleta.

''x'' e ''y'' são as coordenadas informadas pela API.

===== Volume de dados =====

Em um primeiro acompanhamento, os seguintes valores aproximados foram medidos:

  * 2k linhas de ônibus sendo consultadas abaixo de 60 segundos com 100 threads. Estão listadas no arquivo data/linhas.txt.

  wc -l data/linhas.txt
  2572 data/linhas.txt

  * 14k veículos acompanhados diariamente.

  find data/pos -type f | wc -l
  14423

  * 5M posições GPS coletadas diariamente (380 posições por veículo em média).

  # Total em três dias de operação
  cat *json | jq '.d[].t' | wc -l
  16585174

  * 350MB de dados coletados diariamente.

  # Total em três dias de operação
  du -sm data/pos
  1025  data/pos

Dados coletados utilizando um computador pessoal, desktop, com sistema operacional Linux Ubuntu 12.04 (32 bits), com CPU Core 2 DUO de 3GHz, com 4GB de RAM e discos SATA simples (sem RAID). Conexão internet doméstica, de 10mbps.

===== Contato =====
  * [[user:rogerio:start|Rogério Schneider]]: rschneider@inf.puc-rio.br / stockrt@gmail.com