a/OpenWeather-gRPC-API
1
0
Fork 0
mirror of https://codeberg.org/andyscott/OpenWeather-gRPC-API.git synced 2024-12-20 12:03:10 -05:00
Code Issues Projects Releases Packages Wiki Activity

Update README

Browse source
This commit is contained in:
Andrew Scott 2022-09-01 23:52:52 -04:00
parent f304672317
commit 47749ab05e
Signed by: a
GPG key ID: 3EB62D0BBB8DB381
1 changed files with 32 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
README.md
View file

@ -1,18 +1,20 @@
# OpenWeather-gRPC-API
A microservice that accepts remote procedure calls to fetch weather data.
A microservice that accepts remote procedure calls to fetch weather and
geolocation data. Get current forecasts and 5-day forecasts by city,
zip code, or exact coordinates, or obtain exact coordinates for a given
city or zip code.
The service uses [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview)
to define a [gRPC API](https://grpc.io/docs/what-is-grpc/introduction/) that
fetches current and extended weather data.
Weather and geolocation data is obtained from
[OpenWeatherMap.org](https://openweathermap.org/api).
At minimum, an API key that can access the the
[Current weather](https://openweathermap.org/current),
[Daily Forecast 16 Days](https://openweathermap.org/forecast16), and
[Geocoding](https://openweathermap.org/api/geocoding-api) APIs is
required.
[OpenWeatherMap.org](https://openweathermap.org/api). An API key
that can access the [Current Weather](https://openweathermap.org/current),
[5 day](https://openweathermap.org/forecast5), and
[Geocoding](https://openweathermap.org/api/geocoding-api) APIs is required. As
of the last update to this README, a free account is sufficient.
### Starting the Server
@ -34,20 +36,21 @@ root of the project.
### Basic Workflow
1. Generate some server-side code and the code for your preferred language from the files in
the proto directory with the protocol compiler `protoc`
- Note that the `protoc-gen-go` and `protoc-gen-go-grpc` plugins must be installed to generate the server-side code
2. Import your newly generated code into your project (Leave the servers code in the proto directory)
3. Use the imported code to allow your client to connect with the server
4. Use the imported code within your own functions to make requests
the proto directory with the protocol compiler `protoc`.
- Note that the `protoc-gen-go` and `protoc-gen-go-grpc` plugins must be installed to generate the server-side Go code.
2. Import your newly generated code into your project (Leave the servers code in the proto directory).
3. Use the imported code to allow your client to connect with the server.
4. Use the imported code within your own functions to make requests. It is recommended to review the protocol buffer definitions to get an idea of the types of requests the server will accept. Actual implementation will vary depending on your preferred programming language, however an example in Go is provided below.
#### Generating code from the .proto files
Run protoc from the root of the project. The below example shows how one might
Run protoc from the root of the project. The following example shows how one might
generate Go code.
```
protoc -Iproto --go_opt=module=codeberg.org/andcscott/OpenWeatherMap-gRPC-API \
--go_out=. --go-grpc_opt=module=codeberg.org/andcscott/OpenWeatherMap-gRPC-API \
protoc -Iproto --go_opt=module=codeberg.org/andcscott/OpenWeather-gRPC-API \
--go_out=. --go-grpc_opt=module=codeberg.org/andcscott/OpenWeather-gRPC-API \
--go-grpc_out=. proto/*.proto
```
@ -56,7 +59,7 @@ protoc -Iproto --go_opt=module=codeberg.org/andcscott/OpenWeatherMap-gRPC-API \
Import the code into your project. Example in Go:
```
import pb "codeberg.org/andcscott/OpenWeatherMap-gRPC-API/proto"
import pb "codeberg.org/andcscott/OpenWeather-gRPC-API/proto"
```
#### Using the imported code to connect to the server
@ -81,12 +84,20 @@ In this case, we're requesting the current weather for Corvallis, OR.
```
func doCurrent(c pb.WeatherServiceClient) {
res, err := c.Current(context.Background(), &pb.RequestCurrent{
City: "Corvallis",
LocationType: pb.LocationType_LOCATION_TYPE_CITY,
Units: pb.Units_UNITS_METRIC,
Location: &pb.OneOfLocation{
LocationId: &pb.OneOfLocation_City{
City: "Corvallis",
},
},
})
if err != nil {
log.Fatalln(err)
}
log.Println(res.Payload)
}
```
@ -95,16 +106,16 @@ See the [test-client](test-client/current.go) for more details.
## Receiving the response
Data will be sent to your client as JSON when requesting forecasts. Example from the above call:
Data will be sent to your client as JSON when requesting forecasts. Geolocation
requests return a pair of floats representing the latitude and longitude for the
given location. Example from the above call:
```
{"coord":{"lon":-123.262,"lat":44.5646},"weather":[{"id":800,"main":"Clear","description":"clear sky","icon":"01n"}],"base":"stations","main":{"temp":296.87,"feels_like":297.13,"temp_min":294.98,"temp_max":298.62,"pressure":1007,"humidity":70},"visibility":10000,"wind":{"speed":2.14,"deg":284,"gust":1.94},"clouds":{"all":0},"dt":1658811503,"sys":{"type":2,"id":2005452,"country":"US","sunrise":1658753522,"sunset":1658807208},"timezone":-25200,"id":5720727,"name":"Corvallis","cod":200}
```
Geolocation requests return a pair of floats representing the latitude and longitude for the given location.
## UML Sequence Diagram
<a href="https://codeberg.org/andcscott/OpenWeather-gRPC-API/media/branch/main/info/UML.png"><img src="info/UML.png" alt="UML sequence diagram" align="center" width="500"/></a>
<a href="./info/UML.png"><img src="info/UML.png" alt="UML sequence diagram" align="center" width="500"/></a>