Ever had to implement an external API that does have documentation, but does not offer an SDK or OpenAPI spec? GitHub Copilot is a really great tool to help with these kinds of conversions. In this post, I’ll show you how to quickly consume an external API using GitHub Copilot.
The problem
I would like to use the OpenWeather API to get the current weather for a specific location. The API documentation is available at https://openweathermap.org/current. The documentation for a single endpoint looks something like the following:
The documentation is pretty clear, however I am a lazy developer and I don’t want to be writing the code to consume this API myself. I would like to use GitHub Copilot to generate the code for me. I might even get the benefit of less human error.
The magic
Let us assume I am trying to consume this API using a front end built in Typescript. I want to create a class that will handle the API calls for me. Of course, I want the responses to be strongly typed. GitHub Copilot is clever, but cannot read my mind. So I will need to be explicit about what I want.
There is another key piece of information that I will need to include, which is the documentation for the rest api. I will simply copy-paste the relevant parts of the documentation into my chat session, and let Copilot do the rest.
The end result is the following prompt:
The following is an api endpoint specification.
Implement the typescript code to be able to consume the api.
Include a type for the response and a service class
that holds the logic to call the endpoint.
Call current weather data How to make an API call API call
https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={API key}
Parameters lat required Latitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our Geocoding API lon required Longitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our Geocoding API appid required Your unique API key (you can always find it on your account page under the "API key" tab) mode optional Response format. Possible values are xml and html. If you don't use the mode parameter format is JSON by default. Learn more units optional Units of measurement. standard, metric and imperial units are available. If you do not use the units parameter, standard units will be applied by default. Learn more lang optional You can use this parameter to get the output in your language. Learn more Please use Geocoder API if you need automatic convert city names and zip-codes to geo coordinates and the other way around.
Please note that built-in geocoder has been deprecated. Although it is still available for use, bug fixing and updates are no longer available for this functionality.
Examples of API calls
https://api.openweathermap.org/data/2.5/weather?lat=44.34&lon=10.99&appid={API key}
API response If you do not see some of the parameters in your API response it means that these weather phenomena are just not happened for the time of measurement for the city or location chosen. Only really measured or calculated data is displayed in API response. JSON JSON format API response example
{ "coord": { "lon": 10.99, "lat": 44.34 }, "weather": [ { "id": 501, "main": "Rain", "description": "moderate rain", "icon": "10d" } ], "base": "stations", "main": { "temp": 298.48, "feels_like": 298.74, "temp_min": 297.56, "temp_max": 300.05, "pressure": 1015, "humidity": 64, "sea_level": 1015, "grnd_level": 933 }, "visibility": 10000, "wind": { "speed": 0.62, "deg": 349, "gust": 1.18 }, "rain": { "1h": 3.16 }, "clouds": { "all": 100 }, "dt": 1661870592, "sys": { "type": 2, "id": 2075663, "country": "IT", "sunrise": 1661834187, "sunset": 1661882248 }, "timezone": 7200, "id": 3163858, "name": "Zocca", "cod": 200 }
JSON format API response fields
coord coord.lon Longitude of the location coord.lat Latitude of the location weather (more info Weather condition codes) weather.id Weather condition id weather.main Group of weather parameters (Rain, Snow, Clouds etc.) weather.description Weather condition within the group. Please find more here. You can get the output in your language. Learn more weather.icon Weather icon id base Internal parameter main main.temp Temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit main.feels_like Temperature. This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit main.pressure Atmospheric pressure on the sea level, hPa main.humidity Humidity, % main.temp_min Minimum temperature at the moment. This is minimal currently observed temperature (within large megalopolises and urban areas). Please find more info here. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit main.temp_max Maximum temperature at the moment. This is maximal currently observed temperature (within large megalopolises and urban areas). Please find more info here. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit main.sea_level Atmospheric pressure on the sea level, hPa main.grnd_level Atmospheric pressure on the ground level, hPa visibility Visibility, meter. The maximum value of the visibility is 10 km wind wind.speed Wind speed. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour wind.deg Wind direction, degrees (meteorological) wind.gust Wind gust. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour clouds clouds.all Cloudiness, % rain rain.1h (where available) Rain volume for the last 1 hour, mm. Please note that only mm as units of measurement are available for this parameter rain.3h (where available) Rain volume for the last 3 hours, mm. Please note that only mm as units of measurement are available for this parameter snow snow.1h(where available) Snow volume for the last 1 hour, mm. Please note that only mm as units of measurement are available for this parameter snow.3h (where available)Snow volume for the last 3 hours, mm. Please note that only mm as units of measurement are available for this parameter dt Time of data calculation, unix, UTC sys sys.type Internal parameter sys.id Internal parameter sys.message Internal parameter sys.country Country code (GB, JP etc.) sys.sunrise Sunrise time, unix, UTC sys.sunset Sunset time, unix, UTC timezone Shift in seconds from UTC id City ID. Please note that built-in geocoder functionality has been deprecated. Learn more here name City name. Please note that built-in geocoder functionality has been deprecated. Learn more here cod Internal parameter
The first part are my instructions to Copilot. The second part is the documentation that I copied from the OpenWeather API documentation. This resulted in the following code:
First, Copilot defined the response types:
interface Coord {
lon: number;
lat: number;
}
interface Weather {
id: number;
main: string;
description: string;
icon: string;
}
interface Main {
temp: number;
feels_like: number;
temp_min: number;
temp_max: number;
pressure: number;
humidity: number;
sea_level: number;
grnd_level: number;
}
interface Wind {
speed: number;
deg: number;
gust: number;
}
interface Rain {
'1h'?: number;
'3h'?: number;
}
interface Clouds {
all: number;
}
interface Sys {
type: number;
id: number;
country: string;
sunrise: number;
sunset: number;
}
interface WeatherResponse {
coord: Coord;
weather: Weather[];
base: string;
main: Main;
visibility: number;
wind: Wind;
rain?: Rain;
clouds: Clouds;
dt: number;
sys: Sys;
timezone: number;
id: number;
name: string;
cod: number;
}
Next, it defined the service class:
import axios from 'axios';
class WeatherService {
private API_KEY = 'your_api_key_here'; // replace with your actual API key
private BASE_URL = 'https://api.openweathermap.org/data/2.5/weather';
async getWeather(lat: number, lon: number): Promise<WeatherResponse> {
const response = await axios.get(`${this.BASE_URL}?lat=${lat}&lon=${lon}&appid=${this.API_KEY}`);
return response.data;
}
}
It even mentioned a potential security hazard; the suggestion contains a hardcoded api key but instead I would probably want to reference a secret store somewhere, or get the api key from an environment variable.
Conclusion
GitHub Copilot cannot only help you with code completions or with generating code based on specific instructions. It can also understand a raw copy paste of documentation, and generate code based on that. Saving you precious time and mental load.